In case you use the dockerContainersFile to configure a YAML file (Cube format or Compose format) for loading the definition of your containers, you can use cube.environment system property to append a prefix to the file you want to load.

For example, in case you set dockerContainersFile to docker-compose.yml and cube.environment not set, Cube loads a file named docker-compose.yml. But if cube.environment is set to qa (-Dcube.environment=qa), the Cube loads a file called docker-compose.qa.yml.

This property is useful for loading different configurations depending on the environment you are running the tests.

After a container is started, it starts booting up the defined services/commands. Depending on the nature of service, the lifecycle of these services are linked to start up or not. For example Tomcat, Wildlfy, TomEE and in general all Java servers must be started in foreground and this means that from the point of view of the Docker client, the container never finishes to start. But on the other side other services like Redis are started in background and when the container is started you can be sure that Redis server is there. To avoid executing tests before the services are ready, you can set which await strategy should be used from Arquillian Cube side to accept that Docker container and all its defined services are up and ready.

Currently next await strategies are supported:

native

it uses wait command. In this case current thread is waiting until the Docker server notifies that has started. In case of foreground services this is not the approach to be used.

polling

in this case a polling (with ping or ss command) is executed for 5 seconds against all exposed ports. When communication to all exposed ports is acknowledged, the container is considered to be up. This approach is the one to be used in case of services started in foreground. By default polling executes ss command inside the running container to know if the server is already running. You can use a ping from client by setting type attribute to ping; Note that ping only works if you are running Docker daemon on localhost. In almost all cases the default behaviour matches all scenarios. If it is not specified, this is the default strategy.

static

similar to polling but it uses the host ip and specified list of ports provided as configuration parameter. This can be used in case of using Boot2Docker.

sleeping

sleeps current thread for the specified amount of time. You can specify the time in seconds or milliseconds.

By default in case you don’t specify any await strategy, polling with ss command is used.

1. Optional parameter to configure sleeping time between poling. You can set in seconds using s or miliseconds using ms. By default time unit is miliseconds and value 500.

2. Optional parameter to configure number of retries to be done. By default 10 iterations are done.

1. Optional parameter to configure sleeping time between poling. You can set in seconds using s or miliseconds using ms. By default time unit is miliseconds and value 500.

When you are using Docker you can set two different parameters, exposedPort and portBinding. exposedPorts are ports that are available inside Docker infrastructure and they are used for communication between Docker containers but not from outside. On the other side portBindings are a way to instruct Docker container to publish a port to be available from outside (for example from our test).

It seems reasonable that if you set a port binding this port should automatically be exposed port as well. For this reason in Arquillian Cube you can use portBinding and it will automatically set to exposed port.

In next example we are only setting portBinding and Arquillian Cube will instruct Docker to expose port 8080 and of course bind the port 8080 so it can be accessible from outside.

Also it is not necessary to set the network protocol (tcp or udp). If protocol is not specified portBindings: ["8080"] then tcp is used by default. Notice that you need to add double-quotes to stringify the value.

With the configuration option connectionMode you can bypass the Create/Start Cube commands if the a Docker Container with the same name is already running on the target system. If so, Arquillian Cube will reuse that Container moving forward.

This allows you to prestart the containers manually during development and just connect to them to avoid the extra cost of starting the Docker Containers for each test run. This assumes you are not changing the actual definition of the Docker Container itself.

An example of this configuration could be:

connectionMode is an attribute that can receive three parameters:

STARTANDSTOP

it is the default one if not set any and simply creates and stops all Docker Containers. If a container is already running, an exception is thrown.

STARTORCONNECT

it tries to bypass the Create/Start Cube commands if a container with the same name is already running, and if it is the case doesn’t stop it at the end. But if container is not already running, Cube will start one and stop it at the end of the execution.

STARTORCONNECTANDLEAVE

it is exactly the same of STARTORCONNECT but if container is started by Cube it won’t be stopped at the end of the execution so it can be reused in next executions.

Sometimes when the tests has finished and container is stopped you want to inspect some data like container console or getting a file from the container to manual inspecting. In these cases you can configure each container to copy console log or copy a file/s from container to local machine just before container is stopped.

Next snippet shows how to copy a directory from container to local disk:

1. beforeStop goes into the container section and may contain a list of copy and log elements.

2. copy is used to notify that we want to copy some directories or files form from container location to to local location.

3. log is used to notify that we want to copy container log to to local location.

In case of log command the standard output and the error output are returned. log Docker command can receive some configuration paramters and you can set them too in configuration file.

serverUri parameter is where you configure the Uri of Docker server. This parameter is not mandatory and in case you don’t set it, Arquillian Cube will use next values:

In case of boot2docker it will run the command boot2docker ip to get the ip and substitute the dockerHost keyword to the ip returned by that command.

Note that by default Arquillian Cube assumes that boot2docker command is on PATH, but you can configure its location by using boot2dockerPath property which is the full location (and program name) of boot2docker. For example /opt/boot2dockerhome/boot2docker.

boot2docker runs in https and you need to set the certificates path. These certificates are copied by boot2docker by default at <HOME>/.boot2docker/certs/boot2docker-vm. If this property is not set and the serverUri contains dockerHost, then this property is automatically configured to <HOME>/.boot2docker/certs/boot2docker-vm so you don’t need to worry to set for each environment.

In case of docker-machine it will run the command docker-machine ip <machineName> to get the ip and substitute the dockerHost keyword to the ip returned by that command.

Note that by default Arquillian Cube assumes that docker-machine command is on PATH, but you can configure its location by using the dockerMachinePath proeprty which is the full location (and program name too) of docker-machine. For example /usr/bin/docker-machine..

docker-machine can run with boot2docker together. And this docker host instance runs in https so you need to set the certificates path. These certificates are copied by docker-machine by default at <HOME>/.docker/machine/machines. If this property is not set and docker-machine is run, then this property is automatically configured to default location, so you don’t need to worry to set for each environment.

For example you can configure arquillian.xml file to use docker-machine as:

1. Sets docker machine to dev.

Notice that you only need to add machineName property in case you have more than one machine running, everything else it is exactly the same as previous examples.

If you are running your tests inside your continuous integration/delivery server (for example in Jenkins) and at the same time the server is running inside Docker. Then the docker containers started for Cube are run inside a Docker container. So you effectively face the Docker inside Docker problem.

From Arquillian Cube perspective we cannot do a lot of things, more then adapting to this situation by changing the serverUri. Basically it ignores any SERVER_URI, Boot2Docker or docker-machine properties and sets the serverUri to unix:///var/run/docker.sock.

You can avoid this behaviour by setting dockerInsideDockerResolution to false.

INFO: In this case almost all work should be done in infrastructure level by configuring correctly Docker instances. For this reason it is important that before running Cube tests, you test manually your infrastructure to be sure that everything is connected as expected.

In next sections, some minor information is provided on how to run Docker inside/on Docker. Keep in mind that you need to configure continuous integration/delivery correctly.

CubeController is facade class that let’s you interact with any cube container. It offers some operations like creating and destroying Cubes (in case of Docker, it is Docker containers), copy a directory to local directory, get a log with all the changes that happened to Cube filesystem, execute a Top command or copy the logs to local file.

Suppose you have next Docker Container definition in dockerContainers property:

If you enrich your test with CubeController then you will be able to:

• call cubeController.create("manual_database") to create the Cube defined in dockerContainers with name manual_database.

• call cubeController.start("manual_database") to start the given Cube.

• call cubeController.stop("manual_database") to stop the given Cube.

• call cubeController.destroy("manual_database") to destroy the given Cube.

But also it offers some extra operations not related with the lifecycle of a Cube.

• cubeController.copyFileDirectoryFromContainer("manual_database", "/db", newFolder.getAbsolutePath()) to copy content from container folder /db to newFolder local location.

• List<ChangeLog> changesOnFilesystem = cubeController.changesOnFilesystem("manual_database") to returns a log with all changes that has occurred inside given Cube.

• TopContainer top = cubeController.top("manual_testing") to get the result of executing top command inside Cube.

• cubeController.copyLog("manual_testing", follow, stdout, stderr, timestamp, tail, byteArrayOutputStream) to copy Cube log to given outputStream. This operation only works in Client mode.

Probably any application you may write will need an application/servlet container but also other servers like database server or mail server. Each one will be placed on one Docker Container. So for example a full application may contain one Docker Container with an application server (for example Wildfly) and another container with a database (for example H2).

Arquillian Cube can orchestrate these containers as well.

An example of orchestration can be:

1. We use link property to connect Wildfly container to database container.

In this case when a test is started both containers are started and when both are ready to receive requests, the test will be executed.

And the database definition shall be:

Cube will normally start a Docker container when it has the same name as an active Arquillian container and all the links from this container to another containers as we have seen in previous example. Basically Cube resolves all the container depdendencies as well e.g. a database where the application saves data, or mail server where application sends an email.

That works for things that are DeployableContainer’s. For any other container services that might not have a link to the DeployableContainer, e.g. a monitor, you can use the autoStartContainers option to define which Docker containers to automatically start up. The option takes a comma separated list of Docker container ids. e.g. monitor. Arquillian Cube will attempt to start the containers in parallel if possible as well as start any linked containers. Also if you need to start several images, instead of adding them as CSV, you can use a regular expression by prefixing with regexp:, for example setting the property to regexp:a(.*) would start all container ids starting with a.

For example:

Arquillian Cube can automatically configure default ports of container in case of port forwarding.

What Arquillian Cube does internally is remapping default DeployableContainer port values to the ones configured in Docker Containers configuration.

Suppose you have a Docker Container configuration like:

1. Note that the exposed port is the 8081.

Then in theory you should configure the remote Tomcat adapter to port 8081 on your arquillian.xml file. But let’s say that you are using that remote adapter for a remote local machine Tomcat (outside Docker) too, and is configured to use 8080 port.

Which basically uses default port (8080) to connect to remote server.

In this case you don’t need to create a new container tag, Arquillian Cube is smart enough to change the default port value automatically; in case of Tomcat 8080 to 8081. Arquillan Cube will apply autoremapping to all properties that contains port as a substring of the property, and will remap if it is necessary.

If you are using a remote docker server (not on localhost) or for example boot2docker you may want to set that ip to Arquillian remote adapter configuration so it can deploy the archive under test. In these cases you can hardcode this ip to Arquillian container adapter configuration or you can use the special tag dockerServerIp. At runtime these tag will be replaced by Arquillian Cube to docker server ip configured in serverUri parameter. This replacement only works in properties that contains the string host or address in property name.

So for example:

1. We set the serverUri as usually.

2. dockerServerIp is replaced at runtime.

The host property will be replaced automatically to 192.168.0.2.

In case of using unix socket dockerServerUri is replaced to localhost.

Also Arquillian Cube can help you in another way inferring boot2docker ip. In case you are running in MACOS or Windows with boot2docker, you may not need to set host property at all nor using dockerServerIp. Arquillian Cube will inspect any property in configuration class that contains the word address or host that it is not overriden in arquillian.xml and it will set the boot2docker server automatically.

So previous example could be modified to:

And in case you are running on Windows or MacOS, `host`property will be automatically set to the +boot2docker +ip.

Let’s see a simple example on how you can implement a Container Object in Cube. Suppose you want to create a container object that encapsulates a ping pong server running inside Docker. The Container Object will be like a simple POJO with special annotations:

1. @Cube annotation configures Container Object

2. A Container Object can be enriched with Arquillian enrichers

3. Container Object hides how to connect to PingPong server.

@Cube annotation is used to configure this Container Object. Initially you set that the started container will be named pingpong and the port binding information for the container instance, in this case 5000→8080/tcp. Notice that this can be an array to set more than one port binding definition.

Next annotation is @CubeDockerFile which configure how Container is created. In this case using a Dockerfile located at default class path location. The default location is the package+classname, so for example in previous case, Dockerfile should be placed at org/superbiz/containerobject/PingPongContainer. Of course you can set any other class path location by passing as value of the annotation.

Any Cube can be enriched with any client side enricher, in this case with @HostIp enricher, but it could be enriched with DockerClient using @ArquillianResource as well.

Finally the @HostPort is used to translate the exposed port to bound port. So in this example port value will be 5000. You are going to lean briefly why this annotation is important.

And then you can start using this container object in your test:

The most important thing here is that you need to set Container Object as a field of the class and annotate with @Cube. It is very important to annotate the field with Cube, so before Arquillian runs the test, it can detect that it needs to start a new Cube (Docker container), create the Container Object and inject it in the test. Notice that this annotation is exactly the same as used when you defined the Container Object. And it is in this way because you can override any property of the Container Object from the test side. This is why @HostPort annotation is important, since port can be changed from the test definition, you need to find a way to inject the correct port inside the container object.

Let’s suppose we are writing a service which should return as text the current day and time. To serve this service to the world we decide to use undertow embedded server.

The code looks like:

1. This class is a CLI application.

2. Returns a text with the day and time formatted with SimpleDateFormat.

See that this application is a CLI application which is pretty different from previous examples. Previously the packaged application was deployed inside an application server, which in fact means that Arquillian connects to the server and tells it to deploy that file.

In this example there is no application server nor servlet server waiting for Arquillian to deploy an archive but the application is self-contained, it contains everything. So in fact if you want to run the application probably you will end up by doing something like java -jar daytime.jar.

So how to write a test for these classes if we are using Docker as runtime container?

The first thing to do is add arquillian-cube-containerless dependency.

Next step is creating a Dockerfile. This is required because we need to set not only the container image to be used but how to run the application. But see that there is a problem on creating a Dockerfile in this case. The jar name is not static because it will depend on the name you give during the creation of the archive (using Shrinkwrap). So in fact Dockerfile should be templaterized. And this is something that Arquillian Cube can do for you. The idea is creating a file called DockerfileTemplate.

1. ${deployableFilname} will be replaced at runtime by the name of the jar file created by Shrinkwrap.

Then we need to touch arquillian.xml file by setting an special container definition so Arquillian doesn’t crash because of trying to deploy the archive into a none defined container.

1. The Docker container is defined as per usual.

2. buildImage attribute is used to define the dockerfile location.

3. This attribute sets the directory where the Dockerfile is stored. In fact in this case it is the directory where DockerfileTemplate file is stored.

4. A container provided by Arquillian Cube must be defined.

5. This property is used to set which container must be started.

6. This property sets the exposed port by the embedded server.

And finally the test:

1. Tests should be run as-client.

2. ShrinkWrap Maven resolver gets all dependencies for Undertow.

3. Create a jar file called daytime.jar with DaytimeServer class.

4. Undertow dependencies are merged inside jar.

5. Because it is a runnable jar, MANIFEST is created accordantly.

6. Simple test.

In previous section we have seen that we can test any java CLI application that offers a socket connection. But if you think clearly there is nothing that avoid Arquillian Cube to deploy applications developed in other languages like Node.js, Play, Ruby on Rails, …​

Let’s see an example on how you can use Arquillian Cube to test a Node.js hello world application.

First thing to do is create the Node.js application.

Then we need to define a DockerfileTemplate as we did for Undertow.

1. We need to use ADD command adding the deployed file instead of COPY. We are going to see why below.

Finally the arquillian.xml configuration file.

1. This property is used to set which container must be started. In this case node.

And finally the Arquillian test.

1. Tests should be run as-client.

2. GenericArchive with tar extension must be created using Shrinkwrap.

3. Simple test.