Arquillian Cube

Include the following snippet in your pom.xml file:

Then include the individual modules as you see fit, by simply depending on the unified pom name:

You can define networks using cube format (Docker Compose v1 (the one supported by Cube) does not have support to networks. For defining them you only need to use the reserved word networks.

You can also use networks to connect to more than one network:

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:

By default in case you don’t specify any await strategy, polling with ss command is used with automatic fallback to wait-fo_it strategy.

Custom Await strategy:

and the configuration comes as:

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:

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. Or if your need is more specific, you can provide a custom implementation

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

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.

Custom BeforeStop action:

and the configuration comes as:

In case you are using COMPOSE format, you cannot configure cube custom properties like await or beforeStop. You can use a property called cubeSpecificProperties allows you to add them in already defined containers.

Previous snippet would override await strategy to polling and set a beforeStop event in cube container named tomcat defined in a previous docker-compose definition.

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 property which is the full location (and program name too) of docker-machine. For example /usr/bin/docker-machine. But, if docker-machine command is not on PATH, Cube will download the latest version. In this case, machineDriver must be provided to create the 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:

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 on your continuous integration/delivery server (for example on Jenkins or GitLab runners) 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 - DockerHost is not the machine where your test is running.

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:

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

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:

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:

Also you can provide your own implementation of autostart containers. To make it so, first you need to implement org.arquillian.cube.spi.AutoStartParser interface.

Then you need to use reserved word custom: + full qualified class name in the autoStartContainers property.

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:

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:

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.

Arquillian Cube sets some system properties to be used in tests in case you cannot use enrichers (i.e in case of JUnit rules). These system properties are:

For each container started:

Star operator let’s you indicate to Arquillian Cube that you want to generate cube names randomly and adapt links as well. In this way when you execute your tests in parallel there will be no conflicts because of names or binding ports.

Let’s see an example:

You add the special character * to indicate that cube name should be randomized.

With previous example Cube will:

So for example the result file could look like:

Since now the ports are unique and names are unique, you can run tests using same orchestration in parallel against same docker host.

The same approach can work for ensuring that each test run has a unique network. As docker allows multiple networks to have the same name, it will not throw an error if two concurrent tests create networks with the same name. However, as cube networks are specified by name in the cube specification, if there are multiple networks with the same name, the cube could end up in any one of them, resulting in hard to debug test failures.

Again, adding the special character * to the end of the network name will cause a random network name to be used. The name can then be used for a cube’s networkMode or in the cube’s network list, and it will be substituted correctly when the test runs.

Let’s see a simple example of 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 a simple POJO with special annotations:

The @Cube annotation is used to configure a Container Object. Its value property is used to specify how the started container will be named (in this example pingpong) while the portBinding property can be used to specify the port binding information for the container instance (in this case 5000→8080/tcp). Notice that portBinding can also accept an array, in which case more than one port binding definitions can be specified.

The next annotation is @CubeDockerFile, which configures how the container is created. This example will use a Dockerfile located at the default class path location. As the default location is the package+classname, in our example the Dockerfile should be placed at org/superbiz/containerobject/PingPongContainer. It is possible to set any other class path location by passing it as the value property of the @CubeDockerFile annotation.

Any Cube can be enriched with any client side enricher. In the previous example a @HostIp enricher is used, but it could be enriched similarly with @CubeIp (which works similar to @HostPort), or a DockerClient instance if the field is annotated with @ArquillianResource.

Finally the @HostPort is used to translate the exposed port to the bound port. In this example the port value will be 5000. Later you will learn briefly why this annotation is important.

After creating the container object, you can start using it in your test:

The most important step in that test example is setting the Container Object as a field of the test class, and annotating it with @Cube. Before running a test, Arquillian will detect that it needs to (i) start a new Cube (Docker container), (ii) create the Container Object and (iii) inject it in the test. Notice that this @Cube annotation is exactly the same as the one used when you defined the Container Object. Placing a @Cube annotation on the field will allow you to override any property of the Container Object from the test side. Due to the override mechanism, it is important to use the @HostPort annotation when the bound port is needed, since it can be changed from the test definition.

Another option is using a generic container objects provided by Arquillian Cube to generate cube instances. Using this approach you gain in velocity at time of writing the definition, but on the other side it is harder to reuse them or providing custom operations like you can do in custom container objects.

With DSL you can generate container objects or network objects as well.

With Requirements you can set if you want to skip tests if some environment or property variables are not set. This is useful for example if you require that DOCKER_HOST, DOCKER_TLS_VERIFY or DOCKER_CERT_PATH system or environment variable must be set.

Notice that Cube takes precedence these variables over configured in arquillian.xml.

To use it you need to add requirements dependency.

Then you can use an special runner or a JUnit rule. If you use Rule, the scope of annotations are only a test class, if you use the runner then annotations can be used in a suite level.

Let’s see how to use with Rule.

But you can use the runner approach to use it suite level.

Other annotations you can use are: RequiresEnvironmentVariable and RequiresSystemProperty which basically instead of checking as system property or environment variable, they only checks ones.

But also there is an annotation in docker module for checking the environment against docker machine.

Previous test will only be executed if in the environment where test is running has docker machine installed with a machine named dev.

You can also implement your own requirement annotations. To do it you only need to do two things.

Let’s see an example of how to implement a requirement against docker version.

And the implementation logic:

After that you can use this annotation as any other requirements provided by Cube.

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:

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.

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.

And finally the test:

The Arquillian Drone extension for Arquillian provides a simple way how to include functional tests for your application with a web-based user interface. Arquillian Drone brings the power of WebDriver into the Arquillian framework.

Arquillian Drone provides some features that make it better to use instead of plain WebDriver:

You can read more about Drone at https://docs.jboss.org/author/display/ARQ/Drone

Arquillian Graphene is a set of extensions for the WebDriver API, focused on rapid development and usability in a Java environment. Its API encourages people to write tests for AJAX-based web applications in a concise and maintainable way. Graphene strives for reusable tests by simplifying the use of web page abstractions (Page Objects and Page Fragments). You will get a taste of the Graphene API in just a minute!

Previous approach works but it has some problems:

To fix these problems, you can use Arquillian Cube Docker RestAssured integration which creates a RequestSpecBuilder with correct values set.

In previous section you’ve read that by just adding reporter dependency, you get integration between cube and reporter and some information about cube (for example a docker container) is reported.

But sometimes you need more information about the system and not each cube individually. For this reason there is a docker cube reporter integration that adds on the report information specific to docker environment like the composition used during deployment or docker host information.

For this reason if you add next dependency too:

Information about docker host and an schema of docker compositions will be added in the report.

In Cube Docker Drone/Graphene Integration you’ve read that you can execute web UI tests inside a docker container which contains the browser. Also an screencast is recorded so you can review lately what has happened inside the container.

If you add previous dependency arquillian-cube-docker-reporter and arquillian-reporter-depchain in a cube docker drone project, then the report will contain the screencasts as well in the report, so you can play from the report the recordings as well.

If you add arquillian-cube-docker-reporter and arquillian-reporter-depchain in a cube docker RestAssured project, then the report will contain the request and response logs for all test methods.

There is a arquillian cube kubernetes reporter integration that give report information about resources configuration and kubernetes session i.e. Namespace, Master URL, Replication Controllers, Pods, Services etc.

For this reason you have to add following dependency:

Arquillian Cube Docker Reports: https://github.com/arquillian/arquillian-cube/tree/master/docker/ftest-reporter

Arquillian Cube Docker Drone Reports: https://github.com/arquillian/arquillian-cube/tree/master/docker/ftest-drone-reporter

Arquillian Cube Kubernetes Reports: https://github.com/arquillian/arquillian-cube/tree/master/kubernetes/ftest-kubernetes-reporter

Arquillian Reporter for more information: https://github.com/arquillian/arquillian-reporter

This extension will create and manage one temporary namespace for your tests, apply all Kubernetes resources required to create your environment and once everything is ready it will run your tests. The tests will be enriched with resources required to access services. Finally when testing is over it will cleanup everything.

In addition to the main testing namespace additional secondary namespaces could be used during testing. Cube would not modify them, but tests could be enriched with resources from secondary namespaces to access services in them in case you need to verify changes made by services you are testing.

This extension will neither mutate your containers (by deploying, reconfiguring etc) nor your Kubernetes resources and takes a black box approach to testing.

The main modules of this extension are the following:

To use Kubernetes extension you need to register next dependency in your build tool: org.arquillian.cube:arquillian-cube-kubernetes:${version}.

To use OpenShift extension you need to register next dependency in your build tool: org.arquillian.cube:arquillian-cube-openshift:${version}.

The plugin can be configured using the traditional arquillian.xml, via system properties or environment variables (in that particular order). Which means that for every supported configuration parameter, the arquillian.xml will be looked up first, if it doesn’t contain an entry, the system properties will be used. If no result has been found so far the environment variables will be used.

Note: When checking for environment variables, property names will get capitalized, and symbols like "." will be converted to "_". For example foo.bar.baz will be converted to FOO_BAR_BAZ.

The default behavior of the extension is to create a unique testing namespace per test suite. The namespace is created Before the suite is started and destroyed in the end. For debugging purposes, you can set the namespace.cleanup.enabled and namespace.destroy.enabled to false and keep the testing namespace around.

In other cases you may find it useful to manually create and manage the environment rather than having arquillian do that for you. In this case you can use the namespace.use.existing option to select an existing testing namespace. This option goes hand in hand with env.init.enabled which can be used to prevent the extension from modifying the environment.

Last but not least, you can just tell arquillian, that you are going to use the current namespace as testing namespace. In this case, arquillian cube will delegate to Kubernetes Client that in turn will use:

to determine the current testing namespace.

In addition to the primary testing namespace a number of secondary namespaces could participate in tests, but only as a possible location of resources needed to be accessed during tests, usually with verifying purpose. When the service you are testing made some changes in state of services in another namespaces, you can specify the secondary namespace in a field of @Named annotation to reach them.

After creating or selecting an existing namespace, the next step is the environment preparation. This is the stage where all the required Kubernetes configuration will be applied.

Creating an environment does not guarantee its readiness. For example a Docker image may be required to get pulled by a remote repository and this make take even several minutes. Running a test against a Pod which is not Running state is pretty much pointless, so we need to wait until everything is ready.

This extension will wait up to wait.timeout until everything is up and running. Everything? It will wait for all Pods and Service (that were created during the test suite initialization) to become ready. It will poll them every wait.poll.interval milliseconds. For services there is also the option to perform a simple "connection test" by setting the flag wait.for.service.connection.enabled to true. In this case it will not just wait for the service to be ready, but also to be usable/connectable.

As mentioned in the overview, this extension will not try to deploy your tests, inside an application container. It doesn’t need nor want to know what runs inside your docker containers, nor will try to mess with it. It doesn’t even need to run inside Kubernetes (it can just run in your laptop and talk to the kubernetes master).

So what exactly is your test case going to test?

The test cases are meant to consume and test the provided services and assert that the environment is in the expected state.

The test case may obtain everything it needs, by accessing the Kubernetes resources that are provided by the plugin as @ArquillianResources (see resource providers below).

The resource providers available, can be used to inject to your test cases the following resources:

The Openshift extension also provides:

Here’s a small example:

The test code above, demonstrates how you can inject an use inside your test the KubernetesClient and the Session object. It also demonstrates the use of kubernetes-assertions which is a nice little library based on assert4j for performing assertions on top of the Kubernetes model.

Also, you can gather control of what to deploy, when to deploy or when to wait for resources readiness. To control you need to inject into test the org.arquillian.cube.kubernetes.impl.KubernetesAssistant.

The next example is intended to show how you can inject a resource by id.

The next example is intended to show how you can inject a resource from secondary namespace.

The next example shows how to inject a resource filtering by label.

The next example is intended to how you can inject a resource list.

Now let’s see how can you inject OpenShift Client Service.

In case of OpenShift, test can be enriched with OpenShiftClient.

Also you can gather control of what to deploy, when to deploy or when to wait for resources readiness. To control you need to inject into test the org.arquillian.cube.openshift.impl.client.OpenShiftAssistant.