Arquillian tutorial

User Rating: 4 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Inactive
 

Arquillian is a platform that simplifies integration testing for Java middleware. It deals with all the plumbing of container management, deployment, and framework initialization so you can focus on the task of writing your tests—real tests. Arquillian minimizes the burden on you—the developer—by covering aspects surrounding test execution; some of these aspects are as follows:

  • Managing the life cycle of the container (start/stop)
  • Bundling the test class with the dependent classes and resources into a deployable archive
  • Enhancing the test class (for example, resolving @Inject, @EJB, and @Resource injections)
  • Deploying the archive to test applications (deploy/undeploy), and capturing results and failures

 Enough with introductions, let's get our hands dirty with a real example! The following is an Arquillian Test Class which is going to test a full Java EE project:

@RunWith(Arquillian.class)
public class ArquillianTest {


    @Deployment
    public static Archive<?> createTestArchive() {


        return ShrinkWrap.create(WebArchive.class, "test-demo.war")
                .addPackage(Manager.class.getPackage())
                .addPackage(SimpleProperty.class.getPackage())
                .addPackage(Producer.class.getPackage())
                .addPackage(RepositoryManager.class.getPackage())
                .addPackage(ServiceBean.class.getPackage())
                .addAsResource("META-INF/persistence.xml")
                .addAsWebInfResource(EmptyAsset.INSTANCE, "beans.xml")
                // Deploy our test datasource
                ;

    }

    @Inject
    ServiceBean service;

    @Inject
    RepositoryManager query;

    @Test
    public void testApplication() throws Exception {

        SimpleProperty property = new SimpleProperty();
        property.setKey("mykey");
        property.setValue("value");
        
        service.put(property);
        System.out.println("Created SimpleProperty");
        
        SimpleProperty key = query.queryCache("mykey");
        System.out.println("Retrieved: "+property);
        assertNotNull(key);
        
        service.delete(property);
        System.out.println("Deleted: "+property);
        
         
    }

}

This class is part of an exercise lab which can be downloaded from here. The purpose of this example is to insert a key/value pair using the ServiceBean method and then use the RepositoryManager class to verify that data has been actually inserted.
The first thing that you should have noticed is the following annotation that tells JUnit to use Arquillian as the test controller:
@RunWith(Arquillian.class)
public class ArquillianTest {
}

Arquillian then looks for a static method with the @Deployment annotation; it creates a micro deployment, including all the resources, just as you would when packaging your applications with your favorite tool:

The fluent API provided by the ShrinkWrap project (http://www.jboss.org/shrinkwrap) makes this technique possible using the create method, which accepts the type of deployment unit (WebArchive) as the argument thedeployment name (in our case, we will name it test-demo.war) and all the resources are included in this archive. In our case, instead of including all the single classes, we are using the addPackageutility method that adds all the classes that are contained in a class package.


Building the Arquillian test

Although Arquillian does not depend on a specific build tool, it is commonly used with Maven; it offers dependency management and thus simplifies the task of including the Arquillian libraries in the application since they are distributed in the Central Maven repository.

The first thing that is necessary to include in order to run an Arquillian test is the JUnit dependency that is required to run our unit tests:

<dependency>
 <groupId>junit</groupId>
 <artifactId>junit</artifactId>
 <scope>test</scope>
</dependency>

Next, if you want to test enterprise features such as EJB and the Java Transaction API (JTA), you need to include the  org.jboss.arquillian.junit dependency as well:
<dependency>
 <groupId>org.jboss.arquillian.junit</groupId>
 <artifactId>arquillian-junit-container</artifactId>
 <scope>test</scope>
</dependency>

After that, since our Arquillian test uses a protocol to communicate with the server application, we will need to add the org.jboss.arquillian.protocol dependency (named so as it's compatible with Servlet 2.5/3.0 specifications):
<dependency>
 <groupId>org.jboss.arquillian.protocol</groupId>
 <artifactId>arquillian-protocol-servlet</artifactId>
 <scope>test</scope>
</dependency>

After getting done with the dependencies, we will now include two profiles into our configuration. A profile can basically be used to create different target environments for our goals; in our case, we will create two profiles:
The first profile is named arq-jbossas-managed; it will start a new JBoss AS instance and execute the test, shutting it down when done:
<profile>
   <id>arq-jbossas-managed</id>
   <dependencies>
      <dependency>
         <groupId>org.jboss.as</groupId>
         <artifactId>jboss-as-arquillian-containermanaged</artifactId>
         <scope>test</scope>
      </dependency>
   </dependencies>
</profile>

The second profile is named arq-jbossas-remote; it will perform testing against a remote JBoss AS instance:
<profile>
   <id>arq-jbossas-remote</id>
   <dependencies>
      <dependency>
         <groupId>org.jboss.as</groupId>
         <artifactId>jboss-as-arquillian-containerremote</artifactId>
         <scope>test</scope>
      </dependency>
   </dependencies>
</profile>

Running Arquillian Test with a managed container

Arquillian needs to know where JBoss AS is installed so that it can manage the lifecycle of the container using the startup script. You can configure the JBOSS HOME application into the arquillian.xml file shown as follows:

 
<arquillian xmlns="http://jboss.org/schema/arquillian" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
   <defaultProtocol type="Servlet 3.0" />
   <container qualifier="jboss" default="true">
      <configuration>
         <property name="jbossHome">C:\jboss-as-7.1.1.Final</property>
      </configuration>
   </container>
</arquillian>

Run the test from a terminal windows (or from within your IDE which supports Maven) using:

mvn clean test -Parq-jbossas-managed

Running Arquillian Test with a remote container

You can run the test against a remote JBoss AS installation which by default should be running on localhost and 9999 as management port. You can however override these values by adding to arquillian.xml the following parameters:

<arquillian xmlns="http://jboss.org/schema/arquillian" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd">
   <defaultProtocol type="Servlet 3.0" />
   <container qualifier="jboss" default="true">
      <configuration>
         <property name="managementAddress">myhost</property>
         <property name="managementPort">9999</property>
      </configuration>
   </container>
</arquillian>

In order to run it from a terminal window execute:

mvn clean test -Parq-jbossas-remote

 

JBoss AS 7 Development Book

This tutorial includes resources from the JBoss AS 7 Development book. If you liked it, consider purchasing a copy of it from Packt Publishing Site

Advertisement