Arquillian - So you can rule your code. Not the bugs.

The Arquillian project adheres to three core principles:

Arquillian brings your test to the runtime so you don’t have to manage the runtime from the test. Arquillian packs the necessary orchestration logic neatly into the platform an its extensions. As a result, executing an Arquillian test is as simple as selecting "Run As > Test" in the IDE or executing the "test" goal from the build tool.

Using Arquillian, you write a basic test case and annotate it with declarative behavior that says, "`@RunWith` Arquillian". This declaration tells Arquillian to take over execution of the test when it’s launched.

That’s when the real magic happens.

Launching an Arquillian test is as simple as right-clicking the test class in the IDE and selecting Run As > Test (e.g., JUnit, TestNG, Spock, etc). Based on the classpath configuration, Arquillian starts or binds to the target container (JBoss AS, GlassFish, OpenEJB, etc) and deploys the test archive defined in the @Deployment method. The archive includes the test case along with the specified classes, resources and libraries. Your test then executes inside the container and enjoys all the same services as an application component. That means you get dependency and resource injection into the test, you can access EJBs, you can load a persistence unit, you can get a handle to a database connection, etc. Arquillian then captures the test results and transports them back to the test runner for reporting.

Aside from a few extra declarations (i.e., @RunWith and @Deployment), an Arquillian test looks like any other unit test and launched like any other unit test.

Integration testing is very important in Java EE. The reason is two-fold:

The first reason is inherent in enterprise applications. For the application to perform any sort of meaningful work, it has to pull the strings on other components, resources (e.g., a database) or systems (e.g., a web service). Having to write any sort of test that requires an enterprise resource (database connection, entity manager, transaction, injection, etc) is a non-starter because the developer has no idea what to even use. Clearly there is a need for a simple solution, and Arquillian fills that void.

Some might argue that, as of Java EE 5, the business logic performed by most Java EE components can now be tested outside of the container because they are POJOs. But let’s not forget that in order to isolate the business logic in Java EE components from infrastructure services (transactions, security, etc), many of those services were pushed into declarative programming constructs. At some point you want to make sure that the infrastructure services are applied correctly and that the business logic functions properly within that context, justifying the second reason that integration testing is important in Java EE.

How can a single Arquillian test be executed in different containers? How does Arquillian decide which container to target? And how are both remote and local invocations supported?

The answers to these questions touch upon the extensibility of Arquillian.

Container selection occurs at runtime. Arquillian selects the target container according to which container adapter is available on the runtime classpath at the time the test is launched. Therefore, you must include the container adapter as a test-scoped dependency that corresponds to the container you want to target.

Arquillian delegates to an SPI (Service Provider Interface) to handle starting and stopping the server and deploying and undeploying archives. In this case, the SPI is the interface org.jboss.arquillian.spi.client.DeployableContainer. If you recall from the getting started guide, we added an Arquillian container adapter according to the target container we wanted to use. That library contains an implementation of this interface, thus controlling how Arquillian handles deployment.

If you want to add support for another container in Arquillian, you need to provide an implementation of the DeployableContainer interface.

To switch to another container, you just change which container adapter is on the classpath before running the test.

One way to swap the libraries on the classpath is to manually edit the dependencies defined in the pom.xml each time. But that’s just tedious. The recommended approach is to use Maven profiles.

Maven profiles allow you to partition your dependencies into groups, one group for each container adapter and its related artifacts. When running the tests, you activate one of those groups, which in turn selects a target container. The profile is activated either using either a commandline flag (-P) or a preference in the IDE.

The Getting Started Guide explains how to setup and use Maven profiles for this purpose in more detail.

So far we’ve covered how a container adapter is selected. It’s also possible to configure the container adapter, which we’ll look at next.

We’ve covered how a container gets selected, but how does Arquillian know how to locate or communicate with the container? That’s where configuration comes in.

You can come a long way with default values, but at some point you may need to customize some of the container settings to fit your environment. Let’s see how this can be done with Arquillian.

Arquillian will look for configuration settings in a file named arquillian.xml in the root of your classpath. If it exists it will be auto loaded, else default values will be used. This file is not a requirement.

Let’s imagine that we’re working for the company example.com and in our environment we have two servers; test.example.com and hudson.example.com. test.example.com is the JBoss instance we use for our integration tests and hudson.example.com is our continuous integration server that we want to run our integration suite from. By default, Arquillian will use localhost, so we need to tell it to use test.example.com to run the tests. The JBoss AS container by default use the Servlet protocol, so we have to override the default configuration.

That should do it! Here we use the JBoss AS 6.0 Remote container which default use the Servlet 3.0 protocol implementation. We override the default Servlet configuration to say that the http requests for this container can be executed over test.example.com:8181, but we also need to configure the container so it knows where to deploy our archives. We could for example have configured the Servlet protocol to communicate with a Apache server in front of the JBoss AS Server if we wanted to. Each container has different configuration options.

For a complete overview of all the containers and their configuration options, see the container adapters appendix.

Please see the container adapters appendix for a list of supported containers, including details for how to use and configure them.

During execution of your Arquillian test-suite, you may have configured one or more containers with which you need to execute the test suite. This is usually configured with maven profiles, but in the case where individual container options need to be specified at runtime to the target container. This is where you will need to specify configurations in your arquillian.xml file, and also activate those configurations using Java system properties.

Before Arquillian negotiates the execution of the test, it enriches the test class by satisfying injection points specified declaratively using annotations.

When running your tests the embedded Weld EE container, Arquillian activates scopes as follows:

Scope control is experimental at this point and may be altered in a future release of Arquillian.

So far, we’ve focused on testing your application internals, but we also want to test how others (people, or other programs) interact with the application. Typically, you want to make sure that every use case and execution path is fully tested. Third parties can interact with your application in a number of ways, for example web services, remote EJBs or via HTTP. You need to check that your object serialization or networking work for instance.

This is why Arquillian comes with two run modes, in container and as client. in container is to test your application internals and as client is to test how your application is used by clients. Let’s dive a bit deeper into the differences between the run modes and see how they affect your test execution and packaging.

We have previously seen Arquillian deploys ShrinkWrap Archives, but some times you need to deploy other items like a JMS Queue or a DataSource for your test to run. This can be done by using a ShrinkWrap sub project called ShrinkWrap Descriptors. Just like you would deploy an Archive you can deploy a Descriptor.

When dealing with multiple different environments and hidden dynamic container configuration you very soon come to a point where you need access to the backing containers ip/port/context information. This is especially useful when doing remote end point testing. So instead of trying to setup all containers on the same ip/port/context, or hard code this in your test, Arquillian provides something we call @ArquillianResource injection. Via this injection point we can expose multiple internal objects.

When you need to get a hold of the request URI (up through the context path) your Deployment defined, e.g. "http://localhost:8080/test", you can use @ArquillianResource on a field or method argument of type URL:

If you are deploying an EAR with multiple WARs, and you’ve deployed a given servlet to just one of them, you can provide the servlet’s class to get the request URI up through the context path for the WAR that contains that servlet, e.g. "http://localhost:8080/test1" vs. "http://localhost:8080/test2":

Sometimes a single Deployment is not enough, and you need to specify more than one to get your test done.

Maybe you want to test communication between two different web applications?

Arquillian supports this as well. Simply just add more @Deployment methods to the test class and you’re done. You can use the @Deployment.order if they need to be deployed in a specific order. When dealing with multiple in container deployments, you need to specify which Deployment context the individual test methods should run in. You do this by adding a name to the deployment by using the @Deployment.name and refer to that name on the test method by adding @OperateOnDeployment("deploymentName").

There are times when you need to involve multiple containers in the same test case, if you for instance want to test clustering. The first step you need to take is to add a group with multiple containers to your Arquillian configuration.

So what we have done here is to say we have two containers that Arquillian will control, container-1 and container-2. Arquillian will now instead of starting up one container, which is normal, start up two. In your test class you can target different deployments against the different containers using the @TargetsContainer("containerName") annotation on your Deployment methods.

We now have a single test class that will be executed in two different containers. testRunningInDep1 will operate in the context of the dep1 deployment which is deployed on the container named container-1 and testRunningInDep2 will operate in the context of deployment dep2 which is deployed on container container-2. As the test moves along, each method is executed inside the individual containers.

Arquillian does not support ClassLoader isolation on the client side so for this feature to work the container adapter must support running multiple instances within the same ClassLoader/JVM. Currently this only works with containers of type Remote or Managed as the adapter normally will connect to an isolated server started in its own JVM.

A protocol is how Arquillian talks and executes the tests inside the container. For ease of development and configuration a container defines a default protocol that will be used if no other is specified. You can override this default behavior by defining the @OverProtocol annotation on your @Deployment method.

When testExecutedUsingCustomProtocol is executed, instead of using the containers protocol which is defined by default, Arquillian will use MyCustomProtocol to communicate with the container. Since this is defined on Deployment level, you can have different test methods which operate on different deployments and therefore being executed using different protocols. This can be useful when for instance a protocols packaging requirements hinder how you define your archive, or you simply can not communicate with the container using the default protocol due to e.g. firewall settings.

Arquillian only supports Servlet 2.5 and Servlet 3.0 at this time. EJB 3.0 and 3.1 are planned. But you might implement your own Protocol. For doing this, please see the Complete Protocol Reference for the better knowing what is currently supported.

The first time you try Arquillian, you may find that assertions that use the Java assert keyword are not working. Keep in mind that the test is not executing the same JVM as the test runner.

In order for the Java keyword "assert" to work you have to enable assertions (using the -ea flag) in the JVM that is running the container. You may want to consider specifying the package names of your test classes to avoid assertions to be enabled throughout the container’s source code.

The Local Protocol implementation is used by most EE5 compliant containers. It does nothing to the deployment. The Local Protocol is also used when executing in run mode as client.

Packaging rules

The Servlet 2.5 Protocol implementation is used by most EE5 compliant containers. It will attempt to add a war to the deployment.

Packaging rules

The Servlet 3.0 Protocol implementation is used by most EE6 compliant containers. It will attempt to add a web-fragment to the deployment.

Packaging rules

The secret ingredient required to activate the Arquillian test runner is getting the correct libraries on the classpath. (Often easier said than done). The libraries consist of the Arquillian container integration and the container runtime (for an embedded container) or deployment client (for a remote container).

In general, the steps to incorporate Arquillian into a build, regardless of what build tool you are using, can be summarized as:

If you are only running the Arquillian tests on a single container, this setup is exceptionally straightforward. The challenge comes when you want to run the tests on multiple containers. It’s really just a matter of putting the correct libraries on the test classpath, though.

For some build systems, isolating multiple classpath definitions is more tricky than others. For instance, in Maven, you only get one test classpath per run (without using really advanced plugin configuration). You can toggle between different test classpath pairings through the use of profiles. Each profile contains the libraries for a single target container (a combination of the libraries itemized in steps 2 and 3 above). You’ll see this strategy used in the Arquillian examples.

Other build tools, such as Gradle, can easily define new test tasks that each have their own, unique classpath. This makes it not only possible to separate out the target containers, but also run the tests against each one in the same build execution. We’ll see an example of that later in this chapter. Gradle can also emulate the Maven profile strategy through the use of build fragment imports. We’ll also show an example of that approach for contrast.

The community has gravitated towards Maven as the preferred build tool for projects that use Arquillian. Details on how to setup Arquillian in a Maven project is covered in detail in the Arquillian Guides.

Gradle is a build tool that allows you to create declarative, maintainable, concise and highly-performing builds. More importantly, in this context, Gradle gives you all the freedom you need instead of imposing a rigid build lifecycle on you. You’ll get a glimpse of just how flexible Gradle can be by learning how to integrate Arquillian into a Gradle build.

We’ll be contrasting two strategies for running Arquillian tests from Gradle:

The first strategy is the recommended one since it gives you the benefit of being able to run your tests on multiple containers in the same build. However, the second approach is less esoteric and will be more familiar to Maven users. Of course, Gradle is so flexible that there are likely other solutions for this problem. We invite you to give us feedback if you find a better way (or another way worth documenting).

Let’s get the common build stuff out of the way, then dive into the two strategies listed above.

WRITE ME

This guide will detail how to use Arquillian using ant. We will use maven to download all the required jars.

Overview of Steps

Work in progress. Please return.