Preface: Test in the container!

Ever since the inception of Java EE, testing enterprise applications has been a major pain point. Testing business
components, in particular, can be very challenging. Often, a vanilla unit test isn't sufficient for validating
such a component's behavior. Why is that? The reason is that components in an enterprise
application rarely perform operations which are strictly self-contained. Instead, they interact with or provide
services for the greater system. They also have declarative functionality which gets applied at runtime. You could
say "no business component is an island."

The way the component interacts with the system is just as important as the work it performs. Even with the
application separated into more layers than your favorite Mexican dip, to validate the correctness of a component,
you have to observe it carrying out its work—in situ. Unit tests and mock testing can only
take you so far. Business logic aside, how do you test your component's "enterprise" semantics?

Especially true of business components, you eventually have to ensure that the declarative services, such as
dependency injection and transaction control, actually get applied and work as expected. It means interacting with
databases or remote systems and ensuring that the component plays well with its collaborators. What happens when
your Message Driven Bean can't parse the XML message? Will the right component be injected? You may just need to
write a test to explore how the declarative services behave, or that your application is configured correctly to
use them. This style of testing needed here is referred to as integration testing, and it's an essential part of
the enterprise development process.

Arquillian, a new testing framework developed at JBoss.org, empowers the developer to write integration tests for
business objects that are executed inside a container or that interact with the container as a client. The
container may be an embedded or remote Servlet container, Java EE application server, Java SE CDI environment or
any other container implementation provided. Arquillian strives to make integration testing no more complicated
than basic unit testing.

The importance of Arquillian in the Java EE space cannot be emphasized enough. If writing good tests for Java EE
projects is some dark art in which knowledge is shared only by the Java gurus, people are either going to be
turned off of Java EE or a lot of fragile applications are going to be written. Arquillian is set to become the
first comprehensive solution for testing Java EE applications, namely because it leverages the container rather
than a contrived runtime environment.

This guide documents Arquillian's architecture, how to get started using it and how to extend it. If you have
questions, please use the discussion forum in the top-level Arquillian space on JBoss.org. We also provide a JIRA issue tracking system for bug reports and feature
requests. If you are interested in the development of Arquillian, or want to translate this documentation into
your language, we welcome you to join us in the Arquillian Development subspace on JBoss.org.

We believe that integration testing should be no more complex than writing a basic unit test. We created
Arquillian to realize that goal. One of the major complaints we've heard about Seam 2 testing (i.e., SeamTest)
was, not that it isn't possible, but that it isn't flexible and it's difficult to setup. We wanted to correct
those shortcomings with Arquillian.

Testing needs vary greatly, which is why it's so vital that, with Arquillian (and ShrinkWrap), we have decomposed
the problem into its essential elements. The result is a completely flexible and portable integration testing
framework.

1.1. Mission statement

Arquillian is the missing link in Java EE development. Developers have long had to fend for themselves in the testing stage, burdened with
bootstrapping the infrastructure on which the test depends. That's time lost, and it places a high barrier to entry on integration testing.
Arquillian tears down that barrier.

Arquillian is a container-oriented test framework. It picks up where unit tests leave off, targeting the integration of application code
inside a real runtime environment. Just as Java EE 5 simplified the server programming model by providing declarative services for POJOs,
Arquillian equips tests with container lifecycle management and enrichment.

With Arquillian, you write a basic test case and annotate it with declarative behavior that says, "run with Arquillian." Launching the
test is as simple as right-clicking the test class in the IDE and selecting Run As > JUnit or TestNG test.
Based on the classpath configuration, Arquillian starts or binds to the target container (JBoss AS, GlassFish, OpenEJB, etc) and
deploys the test case bundled with the test archive defined in the @Deployment method. Your test 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. Yet, on the surface,
it looks like any other unit test. (Arquillian also has a client execution mode, which only deploys the test archive, not the test case).

Instead of bringing your runtime to the test, Arquillian brings your test to the runtime.

Features of Arquillian include:

Runnable from both JUnit and TestNG

Abstracts out server lifecycle and deployment

Injects resources like managed beans, EJBs or objects from JNDI into the test instance

Zero reliance upon a formal build; can be run or debugged from IDEs like Eclipse, IDEA, NetBeans

Supports remote and embedded containers: JBoss AS, GlassFish, Jetty, Tomcat, OpenEJB, OSGi and more on the way

Enables pass-by-reference between the test and the server, even if the server is in another JVM from the test launcher

Provides an extensible SPI - plug in your own containers and take advantage of the Arquillian bus to provide services to the test

No longer does writing a test involve system administration tasks. No more custom scripts or copy-paste Maven configuration.
No more full builds. No more test classpath mayhem. No more looking up resources manually in JNDI. No more reliance on coarse-grained,
black-box testing.

Arquillian keeps you focused on the test, while enjoying the services provided by the container. And it's turning heads.

At the core, Arquillian provides a custom test runner for JUnit and TestNG that turns
control of the test execution lifecycle from the unit testing framework to Arquillian. From there, Arquillian
can delegate to service providers to setup the environment to execute the tests inside or against the
container. An Arquillian test case looks just like a regular JUnit or TestNG test case with two declarative
enhancements, which will be covered later.

Since Arquillian works by replacing the test runner, Arquillian tests can be executed using existing test IDE,
Ant and Maven test plugins without any special configuration. Test results are reported just like you would
expect. That's what we mean when we say using Arquillian is no more complicated than basic unit testing.

At this point, it's appropriate to pause and define the three aspects of an Arquillian test case. This
terminology will help you better understand the explainations of how Arquillian works.

container — a runtime environment for a deployment

deployment — the process of dispatching an artifact to a container to make it operational

archive — a packaged assembly of code, configuration and resources

The test case is dispatched to the container's environment through coordination with
ShrinkWrap, which is used to declaratively define a custom Java EE archive that
encapsulates the test class and its dependent resources. Arquillian packages the ShrinkWrap-defined archive at
runtime and deploys it to the target container. It then negotiates the execution of the
test methods and captures the test results using remote communication with the server. Finally, Arquillian
undeploys the test archive. We'll go into more detail about how Arquillian works in a later chapter.

So what is the target container? Some proprietary testing container that emulates the behavior of the technology
(Java EE)? Nope, it's pluggable. It can be your actual target runtime, such as JBoss AS, GlassFish or Tomcat.
It can even been an embedded container such as JBoss Embedded AS, GlassFish Embedded or Weld SE. All of this is
made possible by a RPC-style (or local, if applicable) communication between the test runner and the
environment, negotiating which tests are run, the execution, and communicating back the results. This means two
things for the developer:

You develop Arquillian tests just like you would a regular unit test and

the container in which you run the tests can be easily swapped, or you can use each one.

With that in mind, let's consider where we are today with integration testing in Java EE and why an easy
solution is needed.

1.3. Integration testing in Java EE

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

Business components often interact with resources or sub-system provided by the container

Many declarative services get applied to the business component at runtime

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.

1.3.1. Testing the real component

The reality is that you aren't really testing your component until you test it in situ. It's all to easy to
create a test that puts on a good show but doesn't provide any real guarantee that the code under test
functions properly in a production environment. The show typically involves mock components and/or bootstrapped
environments that cater to the test. Such "unit tests" can't verify that the declarative services kick in as
they should. While unit tests certainly have value in quickly testing algorithms and business calculations
within methods, there still need to be tests that exercise the component as a complete service.

Rather than instantiating component classes in the test using Java's new operator, which is customary in a unit
test, Arquillian allows you to inject the container-managed instance of the component directly into your test
class (or you can look it up in JNDI) so that you are testing the actual component, just as it runs inside the
application.

1.3.2. Finding a happy medium

Do you really need to run the test in a real container when a Java SE CDI environment would do?

It's true, some tests can work without a full container. For instance, you can run certain tests in a Java
SE CDI environment with Arquillian. Let's call these "standalone" tests, whereas tests which do require a
full container are called "integration" tests. Every standalone test can also be run as an integration test,
but not the other way around. While the standalone tests don't need a full container, it's also important to
run them as integration tests as a final check just to make sure that there is nothing they conflict with
(or have side effects) when run in a real container.

It might be a good strategy to make as many tests work in standalone mode as possible to ensure a quick test
run, but ultimately you should consider running all of your tests in the target container. As a result, you'll
likely enjoy a more robust code base.

We've established that integration testing is important, but how can integration testing being accomplished
without involving every class in the application? That's the benefit that ShrinkWrap brings to Arquillian.

1.3.3. Controlling the test classpath

One huge advantage ShrinkWrap brings to Arquillian is classpath control. The classpath of a test run has
traditionally been a kitchen sink of all production classes and resources with the test classes and resources
layered on top. This can make the test run indeterministic, or it can just be hard to isolate test resources
from the main resources.

Arquillian uses ShrinkWrap to create "micro deployments" for each test, giving you fine-grained control over
what you are testing and what resources are available at the time the test is executed. An archive can
include classes, resources and libraries. This not only frees you from the classpath hell that typically
haunts test runners (Eclipse, Maven), it also gives you the option to focus on the interaction between an
subset of production classes, or to easily swap in alternative classes. Within that grouping you get the
self-assembly of services provided by Java EE—the very integration which is being tested.

Let's move on and consider some typical usage scenarios for Arquillian.

1.4. Usage scenarios

With the strategy defined above, where the test case is executed in the container, you should get the sense of
the freedom you have to test a broad range of situations that may have seemed unattainable when you only had
the primitive unit testing environment. In fact, anything you can do in an application you can now do in your
test class.

A fairly common scenario is testing an EJB session bean. As you are inside the container, you can simply do a
JNDI lookup to get the EJB reference and your test becomes a client of the EJB. But having to use JNDI to get
a reference to the EJB is inconvenient (at least to Java EE 5 developers that have become accustomed to
annotation-based dependency injection). Arquillian allows you to use the @EJB annotation to
inject the reference to an EJB session bean into your test class.

EJB session beans are one type of Java EE resource you may want to access. But that's just the beginning.
You can access any resource available in a Java EE container, from a UserTransaction to
a DataSource to a mail session. Any of these resources can be injected directly into
your test class using the Java EE 5 @Resource annotation.

Resource injections are convenient, but they are so Java EE 5. In Java EE 6, when you
think dependency injection, you think JSR-299: CDI. Your test class can access any bean in the
ShrinkWrap-defined archive, provided the archive contains a beans.xml file to make it a bean archive. And you
can inject bean instances directly into your class using the @Inject annotation, or you can
inject an Instance reference to the bean, allowing you to create a bean instance when needed
in the test. Of course, you can do anything else you can do with CDI within your test as well.

Another important scenario in integration testing is performing data access. If the ShrinkWrap-defined archive
contains a persistence.xml descriptor, the persistence unit will be started when the archive is deployed
and you can perform persistence operations. You can obtain a reference to an EntityManager
by injecting it into your class with @PersistenceContext or from a CDI producer-field.
Alternatively, you can execute the persistence operation indirectly through an EJB session bean or a managed bean.

Those examples should give you an idea of some of the tasks that are possible from within an
Arquillian-enhanced test case. Now that you have plenty of motivation for using Arquillian, let's
look at how to get started using Arquillian.

Chapter 2. Introductory examples

The following examples demonstrate the use of Arquillian. Currently Arquillian is distributed as a Maven only
project, so you'll need to grab the examples from Git. You can choose between a
JUnit example and a
TestNG example. In this
tutorial we show you how to use both.

Running these tests from the command line is easy. The examples run against all the servers supported
by Arquillian (of course, you must choose a container that is capable of deploying EJBs for these tests).
To run the test, we'll use Maven. For this tutorial, we'll use JBoss AS 6 (currently at Milestone 3), for
which we use the jbossas-remote-6 profile.

First, make sure you have a copy of JBoss AS; you can download it from jboss.org.
We strongly recommend you use a clean copy of JBoss AS. Unzip JBoss AS to a directory of your choice and start it; we'll
use $JBOSS_HOME to refer to this location throughout the tutorial.

You can also run the tests in an IDE. We'll show you how to run the tests in Eclipse, with m2eclipse installed, next.

Before running an Arquillian test in Eclipse, you must have the plugin for the unit testing framework you are
using installed. Eclipse ships with the JUnit plugin, so you are already setup if you selected JUnit. If you
are writing your tests with TestNG, you need the Eclipse TestNG plugin.

Since the examples in this guide are based on a Maven 2 project, you will also need the m2eclipse plugin. Instructions for
using the m2eclipse update site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page.
For more, read the m2eclipse reference
guide.

Once the plugins are installed, import your Maven project into the Eclipse workspace. Before executing the
test, you need to enable the profile for the target container, as we did on the command line. We'll
go ahead and activate the profile globally for the project (we also need the default profile, read the note above for more). Right click on the project and select Properties.
Select the Maven property sheet and in the first form field, enter jbossas-remote-6; you also need
to tell Maven to not resolve dependencies from the workspace (this interferes with resource loading):

Maven settings for project

Click OK and accept the project changes. Before we execute tests, make sure that Eclipse has properly processed all
the resource files by running a full build on the project by selecting Clean from Project menu. Now you are ready
to execute tests.

Assuming you have JBoss AS started from running the tests on the command line, you can now execute the tests.
Right click on the InjectionTestCase.java file in the Package Explorer and select Run As... > JUnit Test
or Run As... > TestNG Test depending on which unit testing framework the test is using.

Running the test from Eclipse using TestNG

You can now execute all the tests from Eclipse!

2.1. Testing an EJB

Here's a JUnit Arquillian test that validates the behavior of the EJB session bean
GreetingManager. Arquillian looks up an instance of the EJB session bean in the test archive
and injects it into the matching field type annotated with @EJB.

The TestNG version of this test looks identical, except that it extends the
org.jboss.arquillian.testng.Arquillian class rather than being annotated with
@RunWith.

2.2. Testing CDI beans

Here's an example of an JUnit Arquillian test that validates the GreetingManager EJB session
bean again, but this time it's injected into the test class using the @Inject annotation.
You could also make GreenManager a basic managed bean and inject it with the same
annotation. The test also verifies that the CDI BeanManager instance is available and gets
injected. Notice that to inject beans with CDI, you have to add a beans.xml file to the test archive.

2.3. Testing JPA

In order to test JPA, you need both a database and a persistence unit. For the sake of example, let's assume we
are going to use the default datasource provided by the container and that the tables will be created
automatically when the persistence unit starts up. Here's a persistence unit configuration that satisfies that
scenario.

Now let's assume that we have an EJB session bean that injects a persistence context and is responsible for
storing and retrieving instances of our domain class, User. We've catered it a bit to the
test for purpose of demonstration.

Now let's create an Arquillian test to ensure we can persist and subsequently retrieve a user. Notice that
we'll need to add the persistence unit descriptor to the test archive so that the persistence unit is
booted in the test archive.

2.4. Testing JMS

Here's another JUnit Arquillian test that exercises with JMS, something that may have previously seemed very
tricky to test. The test uses a utility class QueueRequestor to encapsulate the low-level
code for sending and receiving a message using a queue.

That should give you a taste of what Arquillian tests look like. To learn how to setup Arquillian in your
application and start developing tests with it, refer to the Chapter 3, Getting started chapter.

We've promised you that integration testing with Arquillian is no more complicated than writing a unit test. Now
it's time to prove it to you. In this chapter, we'll look at what is required to setup Arquillian in your
project, how to write an Arquillian test case, how to execute the test case and how the test results are
displayed. That sounds like a lot, but you'll be writing your own Arquillian tests in no time. (You'll also learn
about Chapter 7, Debugging remote tests in Chapter 7).

3.1. Setting up Arquillian in a Maven project

The quickest way to get started with Arquillian is to add it to an existing Maven 2 project. Regardless of
whether you plan to use Maven as your project build, we recommend that you take your first steps with
Arquillian this way so as to get to your first green bar with the least amount of distraction.

The first thing you should do is define a Maven property for the version of Arquillian you are going to use.
This way, you only have to maintain the version in one place and can reference it using the Maven variable
syntax everywhere else in your build file.

Next, you'll need to decide whether you are going to write tests in JUnit 4.x or TestNG 5.x. Once you make that
decision (use TestNG if you're not sure), you'll need to add either the JUnit or TestNG library to your test
build path as well as the corresponding Arquillian library.

If you plan to use JUnit 4, begin by adding the following two test-scoped dependencies to
the <dependencies> section of your pom.xml.

Now we need to validate that this code runs. We'll be creating a test in the src/test/java
classpath of the project.

Granted, in this trivial case, we could simply instantiate the implementation class in a unit test to test the
calculations. However, let's assume that this bean is more complex, needing to access enterprise services. We
want to test it as a full-blown container-managed bean, not just as a simple class instance. Therefore,
we'll inject the bean into the test class using the @Inject annotation.

You're probably very familiar with writing tests using either JUnit or TestNG. A regular JUnit or TestNG test
class requires two enhancements to make it an Arquillian integration test:

Define the deployment archive for the test using ShrinkWrap

Declare for the test to use the Arquillian test runner

The deployment archive for the test is defined using a static method annotated with Arquillian's
@Deployment annotation that has the following signature:

publicstaticArchive<?> methodName();

We'll add the managed bean to the archive so that we have something to test. We'll also add an
empty beans.xml file, so that the deployment is CDI-enabled:

The JUnit and TestNG versions of our test class will be nearly identical. They will only differ in how they
hook into the Arquillian test runner.

When creating the JUnit version of the Arquillian test case, you will define at least one test method annotated
with the JUnit @Test annotation and also annotate the class with the
@RunWith annotation to indicate that Arquillian should be used as the test runner for this
class.

TestNG doesn't provide anything like JUnit's @RunWith annotation, so instead the TestNG
version of the Arquillian test case must extend the Arquillian class and define at least one method annotated
with TestNG's @Test annotation.

As you can see, we are not instantiating the bean implementation class directly, but rather using the CDI
reference provided by the container at the injection point, just as it would be used in the application. (If
the target container supports EJB, you could replace the @Inject annotation with
@EJB). Now let's
see if this baby passes!

3.3. Setting up and running the test in Maven

As we've been emphasizing, this test is going to run inside of a container. That means you have to have a
container running somewhere. While you can execute tests in an embedded container or a Java SE CDI environment,
we're going to start off by testing using the real deal.

If you haven't already, download the latest version of JBoss AS 6.0 from the JBoss AS download page, extract the distribution and
start the container.

Since Arquillian needs to perform JNDI lookups to get references to the components under test, we need to
include a jndi.properties file on the test classpath. Create the file
src/test/resources/jndi.properties and populate it with the following contents:

Next, we're going to return to pom.xml to add another dependency. Arquillian picks which container it's going
to use to deploy the test archive and negotiate test execution using the service provider mechanism, meaning
which implementation of the DeployableContainer SPI is on the classpath. We'll control
that through the use of Maven profiles. Add the following profiles to pom.xml:

The tests are passing, but we don't see a green bar. To get that visual, we need to run the tests in the IDE.
Arquillian tests can be executed using existing IDE plugins for JUnit and TestNG, respectively, or so you've
been told. It's once again time to prove it.

3.4. Setting up and running the test in Eclipse

Before running an Arquillian test in Eclipse, you must have the plugin for the unit testing framework you are
using installed. Eclipse ships with the JUnit plugin, so you are already setup if you selected JUnit. If you
are writing your tests with TestNG, you need the Eclipse TestNG plugin.

Note

Since the example in this guide is based on a Maven 2 project, you will also need the m2eclipse plugin. Instructions for
using the m2eclipse update site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page.
For more, read the m2eclipse reference
guide.

Once the plugins are installed, import your Maven project into the Eclipse workspace. Before executing the
test, you need to enable the profile for the target container, as you did in the previous section. We'll
go ahead and activate the profile globally for the project. Right click on the project and select Properties.
Select the Maven property sheet and in the first form field, enter jbossas-remote-6; you also need
to tell Maven to not resolve depedencies from the workspace (this interferes with resource loading):

Maven settings for project

Click OK and accept the project changes. Before we execute tests, make sure that Eclipse has properly processed all
the resource files by running a full build on the project by selecting Clean from Project menu. Now you are ready
to execute tests.

Right click on the TemperatureConverterTest.java file in the Package Explorer and select Run As... > JUnit Test
or Run As... > TestNG Test depending on which unit testing framework the test is using.

Running the the JUnit test in Eclipse

3.5. Setting up and running the test in NetBeans

Things get even simpler when using NetBeans 6.8 or better. NetBeans ships with native Maven 2 support and,
rather than including a test plugin for each unit testing framework, it has a generic test plugin which
delegates to the Maven surefire plugin to execute the tests.

Import your Maven project into NetBeans. Then, look for a select menu in the main toolbar, which you can
use to set the active Maven profile. Select the jbossas-remote-6 profile as shown here:

NetBeans project configuration

Now you are ready to test. Simply right click on the TemperatureConverter.java file in the Projects pane and
select Test File. NetBeans will delegate to the Maven surefire plugin to execute the tests and then
display the results in a result windown, showing us a pretty green bar!

Successful test report in NetBeans

As you can see, there was no special configuration necessary to execute the tests in either Eclipse or NetBeans.

Chapter 4. Target containers

Arquillian's forte is not only in its ease of use, but also in its flexibility. Good integration testing is not
just about testing in any container, but rather testing in the container
you are targeting. It's all too easy to kid ourselves by validating components in a
specialized testing container, only to realize that the small variations causes the components fail when it comes
time to deploy to the application for real. To make tests count, you want to execute them in the real container.

Arquillian supports a variety of target containers out of the box, which will be covered in this chapter. If the
container you are using isn't supported, Arquillian makes it very easy to plug in your own implementation.

4.1. Container varieties

You can run the same test case against various containers with Arquillian. The test class does not reference
the container directly, which means you don't get locked into a proprietary test environment. It also means you
can select the optimal container for development or easily test the compatibility of your application.

Arquillian recognizes three container interaction styles:

a remote container resides in a separate JVM from the test runner; Arquillian binds to the container to
deploy and undeploy the test archive and invokes tests via a remote protocol (typically HTTP)

an embedded container resides in the same JVM as the test runner; lifecycle managed by Arquillian; tests
are executed via a local protocol for containers without a web component (e.g., Embedded EJB) and via a
remote protocol for containers that have a web component (e.g., Embedded Java EE)

a managed container is the same as a remote container, but in addition, its
lifecycle (startup/shutdown) is managed by Arquillian and is run as a separate process

Containers can be further classified by their capabilities. There are three common catagories:

Arquillian provides SPIs that handle each of the tasks involved in controlling the runtime environment,
executing the tests and aggregating the results. So in theory, you can support just about any environment that
can be controlled with the set of hooks you are given.

4.2. Container management

While the management of an embedded container is straightforward, you may wonder how
Arquillian knows where the remote and managed containers are installed. Actually, Arquillian only needs to know
the install path of managed containers (e.g., jbossas-managed-6). In this case, since
Arquillian manages the container process, it must have access to the container's startup script. For managed
JBoss AS containers, the install path is read from the environment variable JBOSS_HOME.

For remote containers (e.g., jbossas-remote-6), Arquillian simply needs to know that the
container is running and communicates with it using a remote protocol (e.g., JNDI). For remote JBoss AS
containers, the JNDI settings are set in a jndi.properties file on the classpath. You also have to set the
remote address and HTTP port in the container configuration if they differ from the default values (localhost
and 8080 for JBoss AS, respectively).

4.3. Supported containers

The implementations provided so far are shown in the table below. Also listed is the artifactId of the JAR that
provides the implementation. To execute your tests against a container, you must include the artifactId that
corresponds to that container on the classpath. Use the following Maven profile definition as a template to add
support for a container to your Maven build, replacing %artifactId% with the artifactId from the table. You
then activate the profile when executing the tests just as you did in the Chapter 3, Getting started
chapter.

Support for other containers is planned, including Weblogic (remote), WebSphere (remote) and Hibernate.

4.4. Container configuration

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. We're going to have a look at how this can be done with Arquillian.
Arquillian will look for 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. So this file is not a requirement.

Lets 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.

That should do it! "Each type of container has it's own XML namespace for configuration - here we use the JBoss AS 6.0
Remote container. Each container has different configuration options. Next step is to create a
container element in that namespace and add the options you want to configure inside.
In this example we're saying that the server we want to test against can be found on
address test.example.com using port 8181, and the remote server can communicate back to us
on address hudson.example.com on port 7000. Some containers expect to be given a URL from which
they can retrieve the application to be deployed. For these containers, Arquillian will start a local HTTP server.

Chapter 5. Test enrichment

When you use a unit testing framework like JUnit or TestNG, your test case lives in a world on its own. That
makes integration testing pretty difficult because it means the environment in which the business logic
executes must be self-contained within the scope of the test case (whether at the suite, class or method
level). The bonus of setting up this environment in the test falls on the developer's shoulders.

With Arquillian, you no longer have to worry about setting up the execution environment because that is all
handled for you. The test will either be running in a container or a local CDI environment. But you still
need some way to hook your test into this environment.

A key part of in-container integration testing is getting access the container-managed components that you plan to
test. Using the Java new operator to instantiate the business class is not suitable in this testing scenario
because it leaves out the declaratives services that get applied to the component at runtime. We want the real
deal. Arquillian uses test enrichment to give us access to the real deal. The visible result of test enrichment is
injection of container resources and beans directly into the test class.

5.1. Injection into the test case

Before Arquillian negotiates the execution of the test, it enriches the test class by satisfying injection
points specified declaratively using annotations. There are three injection-based enrichers provided by
Arquillian out of the box:

@Resource - Java EE resource injections

@EJB - EJB session bean reference injections

@Inject - CDI injections

The first two enrichers use JNDI to lookup the instance to inject. The CDI injections are handled by treating
the test class as a bean capable of receiving standard CDI injections.

The @Resource annotation gives you access to any object which is available via JNDI. It follows
the standard rules for @Resource (as defined in the Section 2.3 of the Common Annotations for
the Java Platform specification).

The @EJB annotation performs a JNDI lookup for the EJB session bean reference using the
following equation in the specified order:

If no matching beans were found in those locations the injection will fail.

Warning

At the moment, the lookup for an EJB session reference relies on some common naming convention of EJB beans.
In the future the lookup will rely on the standard JNDI naming conventions established in Java EE 6.

In order for CDI injections to work, the test archive defined with ShrinkWrap must be a bean archive. That
means adding beans.xml to the META-INF directory. Here's a @Deployment method that shows
one way to add a beans.xml to the archive:

In an application that takes full advantage of CDI, you can likely get by only using injections defined with
the @Inject annotation. Regardless, the other two types of injection come in handy from
time-to-time.

This chapter walks through the details of test execution, covering both the remote and local container cases.

Note

Whilst it's not necessary to understand the details of how Arquillian works, it is often useful to have some
insight. This chapter gives you an overview of how Arquillian executes your test for you in your chosen
container.

6.1. Anatomy of a test

In both JUnit 4 and TestNG 5, a test case is a class which contains at least one test method. The test method
is designated using the @Test annotation from the respective framework. An Arquillian test
case looks just like a regular JUnit or TestNG test case with two declarative enhancements:

The class contains a static method annotated with @Deployment that returns a JavaArchive

The class is annotated with @RunWith(Arquillian.class) (JUnit) or extends
Arquillian (TestNG)

With those two modifications in place, the test is recognized by the Arquillian test runner and will be
executed in the target container. It can also use the extra functionality that Arquillian provides—namely
container resource injections and the injection of beans.

6.2. ShrinkWrap packaging

When the Arquillian test runner processes a test class, the first thing it does is retrieve the definition of
the Java archive from the @Deployment method, appends the test class to the archive and
packages the archive using ShrinkWrap.

The name of the archive is irrelevant, so the base name "test" is typically choosen (e.g., test.jar, test.war).
Once you have created the shell of the archive, the sky is really the limit of how you can assemble it. You are
customizing the layout and contents of the archive to suit the needs of the test. Essentially, you creating a
micro application in which to execute the code under test.

You can add the following artifacts to the test archive:

Java classes

A Java package (which adds all the Java classes in the package)

Classpath resources

File system resources

A programmatically-defined file

Java libraries (JAR files)

Other Java archives defined by ShrinkWrap

Consult the ShrinkWrap API to discover all the options you have available for constructing the test archive.

6.3. Test archive deployment

After the Arquillian test runner packages the test archive, it deploys it to the container. For a remote
container, this means copying the archive the hot deployment directory or deploying the archive using the
container's remote deployment service. In the case of a local container, such as Weld SE, deploying the archive
simply means registering the contents of the archive with the runtime environment.

How does Arquillian support multiple containers? And how are both remote and local cases
supported? The answer to this question gets into the extensibility of Arquillian.

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.DeployableContainer. If you recall from the getting started
section, we included an Arquillian library 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 wanted to
introduce support for another container in Arquillian, you would simply provide an implementation of this
interface.

With the archive deployed, all is left is negotiating execution of the test and capturing the results. As you
would expect, once all the methods in the test class have be run, the archive is undeployed.

6.4. Enriching the test class

The last operation that Arquillian performs before executing the individual test methods is "enriching" the
test class instance. This means hooking the test class to the container environment by satisfying its injection
points. The enrichment is provided by any implementation of the
org.jboss.arquillian.spi.TestEnricher SPI on the classpath. Chapter 5, Test enrichment
details the injection points that Arquillian supports.

6.5. Negotiating test execution

The question at this point is, how does Arquillian negotiate with the container to execute the test
when the test framework is being invoked locally? Technially the mechanism is pluggable using another SPI,
org.jboss.arquillian.spi.ContainerMethodExecutor. Arquillian provides a default
implementation for remote servers which uses HTTP communication and an implementation for local tests, which
works through direct execution of the test in the same JVM. Let's have a look at how the remote execution
works.

The archive generator bundles and registers (in the web.xml descriptor) an HttpServlet,
org.jboss.arquillian.protocol.servlet.ServletTestRunner, that responds to test execution GET requests. The test
runner on the client side delegates to the org.jboss.arquillian.spi.ContainerMethodExecutor
SPI implementation, which originates these test execution requests to transfer control to the container JVM.
The name of the test class and the method to be executed are specified in the request query parameters named
className and methodName, respectively.

When the test execution request is received, the servlet delegates to an implementation of the
org.jboss.arquillian.spi.TestRunner SPI, passing it the name of the test class and the test
method. TestRunner generates a test suite dynamically from the test class and method name
and runs the suite (now within the context of the container).

The ServletTestRunner translates the native test result object of JUnit or TestNG into a
org.jboss.arquillian.spi.TestResult and passes it back to the test executor on the client
side by serializing the translated object into the response. The object gets encoded as either html or a
serialized object, depending on the value of the outputMode request parameter that was passed to the servlet.
Once the result has been transfered to the client-side test runner, the testing framework (JUnit or TestNG)
wraps up the run of the test as though it had been executed in the same JVM.

Now you should have an understanding for how tests can be executed inside the container, but still be executed
using existing IDE, Ant and Maven test plugins without any modification. Perhaps you have even started thinking
about ways in which you can enhance or extend Arquillian. But there's still one challenge that remains for
developing tests with Arquillian. How do you debug test? We'll look at how to hook a debugger into the test
execution process in the next chapter.

6.6. Test run modes

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 you 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. Lets dive a bit deeper into the differences between the run modes and
see how they effect your test execution and packaging.

6.6.1. Mode: in-container

@RunWith(Arquillian.class)@Run(IN_CONTAINER)publicclassMyTestCase

As we mentioned above, we need to repackage your @Deployment, adding some Arquillian support
classes, to run in-container. This gives us the ability to communicate with the test, enrich the test and run the
test remotely. In this mode, the test executes in the remote container; Arqullian uses this mode by default.

Here is an overview of the expected output of the packaging process when you provide a @Deployment.

Table 6.1. Servlet Protocol 2.5 rules

@Deployment

Output

Action

JavaArchive

EnterpriseArchive

Create a new EnterpriseArchive, add @Deployment and ServletProtocol as module, the other Auxiliary Archives as libraries.

WebArchive

Exception

Can not merge two WebArchives and both packaged in a EnterpriseArchive will result in isolation issues.
[a]

EnterpriseArchive

EnterpriseArchive

Same as JavaArchive, but using the @Deployment defined EnterpriseArchive instead of creating a new.

[a] In the current release Arquillian does not try to merge descriptor files, like web.xml, nor can you
avoid it trying to package the @Deployment. This will change in future releases.

Table 6.2. Servlet Protocol 3.0 rules

@Deployment

Output

Action

JavaArchive

WebArchive

Creates a new WebArchive, adds @Deployment and Auxiliary Archives as libraries.

WebArchive

WebArchive

Adds @Deployment and Auxiliary Archives as libraries.

EnterpriseArchive

EnterpriseArchive

Creates a new WebArchive, adds @Deployment and Auxiliary Archives as libraries.

Note

In Alpha4 Arquillian only has one type of protocol implementation for communicating with remote servers, the servlet protocol.
So the reason for the big difference in packaging between EE 5 and EE 6 containers is mainly due to the support of
Web Fragments in the EE 6 specification. Web Fragments lets Arquillian add it self to the @Deployment
without drastically changing it, but it also means it has to be a WebArchive in the deployment.

In the next release you will be able to control the packaging your self and we will also look into
other protocol implementations like jmx and remote ejb.

6.6.2. Mode: as-client

@RunWith(Arquillian.class)@Run(AS_CLIENT)publicclassMyTestCase

Now this mode is the easy part. As apposed to in-container mode which repackages and overrides the test
execution, the as-client mode does as little as possible. It does not repackage your @Deployment
nor does it forward the test execution to a remote server. Your test case is running in your JVM as expected
and you're free to test the container from the outside, as your clients see it. The only thing Arquillian
does is to control the lifecycle of your @Deployment.

Tip

The effect of the different run modes depend on the DeployableContainer used.
Both modes might seem to behave the same in some Embedded containers, but you should avoid
mixing your internal and external tests. One thing is that they should test different
aspects of your application and different usecases, another is that you will miss the
benefits of switching DeployableContainers and run the same tests suite against
a remote server if you do.

While Arquillian tests can be easily executing using existing IDE, Ant and Maven test plugins, debugging tests are
not as straightforward (but by no means difficult). The extra steps documented in this chapter are only relevant
for tests which are not executed in the same JVM as the test runner. These steps to not apply to tests that are
run in a local bean container (e.g., Weld SE), which can be debugged just like any other unit test.

We'll assume in this chapter that you are already using Eclipse and you already have the test plugin installed for
the testing framework you are using (JUnit or TestNG).

7.1. Debugging in Eclipse

If you set a break point and execute the test in debug mode using a remote container, your break point won't be
hit. That's because when you debug an in-container test, you're actually debugging the container. The test
runner and the test are executing in different JVMs. Therefore, to setup debugging, you must first attach the
IDE debugger to the container, then execute the test in debug mode (i.e., debug as test). That puts the
debugger on both sides of the fence, so to speak, and allows the break point to be discovered.

Let's begin by looking at how to attach the IDE debugger to the container. This isn't specific to Arquillian.
It's the same setup you would use to debug a deployed application.

7.1.1. Attaching the IDE debugger to the container

There are two ways to attach the IDE debugger to the container. You can either start the container in debug
mode from within the IDE, or you can attach the debugger over a socket connection to a standalone container
running with JPDA enabled.

The Eclipse Server Tools, a subproject of the Eclipse Web Tools Project (WTP), has support for launching most
major application servers, including JBoss AS 5. However, if you are using JBoss AS, you should consider using
JBoss Tools instead, which offers tighter integration with JBoss technologies. See either the Server Tools documentation or the JBoss Tools documentation for
instructions on how to setup a container and start it in debug mode.

See this blog
entry to learn how to start JBoss AS with JPDA enabled and how to get the Eclipse debugger to
connect to the remote process.

7.1.1.1. Starting JBoss AS in debug mode

If you are using JBoss AS, the quickest way to setup debug mode is to add the following line to the end
of $JBOSS_AS_HOME/bin/run.conf (Unix/Linux):

or before the line :JAVA_OPTS_SET in $JBOSS_AS_HOME/bin/run.conf.bat (Windows)

set JAVA_OPTS="%JAVA_OPTS% -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"

Keep in mind your container will always run with debug mode enabled after making this change. You might
want to consider putting some logic in the run.conf* file.

7.1.2. Launching the test in debug mode

Once Eclipse is debugging the container, you can set a breakpoint in the test and debug it just like a unit
test. Let's give it a try.

Open an Arquillian test in the Java editor, right click in the editor view, and select Debug As > TestNG (or
JUnit) Test. When the IDE hits the breakpoint, it halts the JVM thread of the container rather than the
thread that launched the test. You are now debugging remotely.

7.1.3. Stepping into external libraries

If you plan to step into a class in an external library (code outside of your application), you must ensure
that the source is properly associated with the library. Below are the steps to follow to associate the
source of a library with the debug configuration:

Select the Run > Debug Configurations... menu from the main menubar

Select the name of the test class in the TestNG (or JUnit) category

Select the Source tab

Click the Add... button on the right

Select Java Project

Check the project the contains the class you want to debug

Click OK on the Project Selection window

Click Close on the Debug Configurations window

You'll have to complete those steps for any test class you are debugging, though you only have to do it once
(the debug configuration hangs around indefinitely).

Tip

These steps may not be necessary if you have a Maven project and the sources for the library are
available in the Maven repository.

7.2. Assertions in remote tests

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.

7.2.1. Enabling assertions in JBoss AS

If you are using JBoss AS, the quickest way to setup debug mode is to add the following line to the end of $JBOSS_AS_HOME/bin/run.conf (Unix/Linux):

JAVA_OPTS="$JAVA_OPTS -ea"

or before the line :JAVA_OPTS_SET in $JBOSS_AS_HOME/bin/run.conf.bat (Windows)

set "JAVA_OPTS=%JAVA_OPTS% -ea"

Keep in mind your container will always run with assertions enabled after making this change. You might want to consider putting some logic in the run.conf* file.

As an alternative, we recommend using the 'Assert' object that comes with your test framework instead to avoid
the whole issue. Also keep in mind that if you use System.out.println statements, the output is going to show
up in the log file of the container rather than in the test output.

Chapter 8. Extending Arquillian

Arquillian is designed to be very extensible. This is accomplished through the use of Service Provider Interfaces
(SPIs). The following diagram shows how the various SPIs in Arquillian tie into the test execution.

9.1. JBoss AS 5 - Remote

A DeployableContainer implementation that can connect and run against a remote(different JVM, different machine) running
JBoss AS 5 instance.
This implementation has no lifecycle support, so it can not be started or stopped.

Warning

This container needs a jndi.properties file on classpath to be able to connect to the remote running instance.

Table 9.1. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.1.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jbossas.remote_5

Table 9.2. Container Configuration Options

Name

Type

Default

Description

profileName

String

default

ProfileService profileKey. Used to load the correct profile into the DeploymentManager.

remoteServerAddress

String

localhost

Used by Servlet Protocol to connect to the remote server.

remoteServerHttpPort

int

8080

Used by Servlet Protocol to connect to the remote server.

localDeploymentBindAddress

String

localhost

Bind Address for the HTTP server serving deployments to the remote server. Address must be reachable from remote server.

localDeploymentBindPort

int

9999

Bind Port for the HTTP server serving deployments to the remote server. Port must be reachable from remote server.

9.2. JBoss AS 5.1 - Remote

A DeployableContainer implementation that can connect and run against a remote(different JVM, different machine) running
JBoss AS 5.1 instance.
This implementation has no lifecycle support, so it can not be started or stopped.

Warning

This container needs a jndi.properties file on classpath to be able to connect to the remote running instance.

Table 9.3. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.2.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jbossas.remote_5_1

Table 9.4. Container Configuration Options

Name

Type

Default

Description

profileName

String

default

ProfileService profileKey. Used to load the correct profile into the DeploymentManager.

remoteServerAddress

String

localhost

Used by Servlet Protocol to connect to the remote server.

remoteServerHttpPort

int

8080

Used by Servlet Protocol to connect to the remote server.

localDeploymentBindAddress

String

localhost

Bind Address for the HTTP server serving deployments to the remote server. Address must be reachable from remote server.

localDeploymentBindPort

int

9999

Bind Port for the HTTP server serving deployments to the remote server. Port must be reachable from remote server.

9.3. JBoss AS 5.1 - Managed

A DeployableContainer implementation that can run and connect to a remote(different JVM, same machine)
JBoss AS 5.1 instance.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.5. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.3.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jbossas.managed_5_1

Table 9.6. Container Configuration Options

Name

Type

Default

Description

profileName

String

default

ProfileService profileKey. Used to load the correct profile into the DeploymentManager.

9.4. JBoss AS 6.0 - Remote

A DeployableContainer implementation that can connect and run against a remote(different JVM, different machine) running
JBoss AS 6.0 instance.
This implementation has no lifecycle support, so it can not be started or stopped.

Warning

This container needs a jndi.properties file on classpath to be able to connect to the remote running instance.

Table 9.7. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.4.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jbossas.remote_6_0

Table 9.8. Container Configuration Options

Name

Type

Default

Description

profileName

String

default

ProfileService profileKey. Used to load the correct profile into the DeploymentManager.

remoteServerAddress

String

localhost

Used by Servlet Protocol to connect to the remote server.

remoteServerHttpPort

int

8080

Used by Servlet Protocol to connect to the remote server.

localDeploymentBindAddress

String

localhost

Bind Address for the HTTP server serving deployments to the remote server. Address must be reachable from remote server.

localDeploymentBindPort

int

9999

Bind Port for the HTTP server serving deployments to the remote server. Port must be reachable from remote server.

9.5. JBoss AS 6.0 - Managed

A DeployableContainer implementation that can run and connect to a remote(different JVM, same machine)
JBoss AS 6.0 instance.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.9. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.5.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jbossas.managed_6

Table 9.10. Container Configuration Options

Name

Type

Default

Description

profileName

String

default

ProfileService profileKey. Used to load the correct profile into the DeploymentManager.

9.6. JBoss AS 6.0 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
JBoss AS 6.0 instance.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.11. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.6.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jbossas.embedded_6

Table 9.12. Container Configuration Options

Name

Type

Default

Description

profileName

String

default

ProfileService profileKey. Used to load the correct profile into the DeploymentManager.

bindAddress

String

localhost

The Address the server should bind to.

httpPort

int

8080

Used by Servlet Protocol to connect to the server.

Example of Maven profile setup

<profile><id>jbossas-embedded-6</id><dependencies><dependency><groupId>org.jboss.arquillian.container</groupId><artifactId>arquillian-jbossas-embedded-6</artifactId><version>1.0.0.Alpha4</version></dependency><dependency><groupId>org.jboss.jbossas</groupId><artifactId>jboss-as-depchain</artifactId><version>6.0.0.20100721-M4</version><type>pom</type></dependency></dependencies><dependencyManagement><dependencies><dependency><groupId>org.jboss.jbossas</groupId><artifactId>jboss-as-depchain</artifactId><version>6.0.0.20100721-M4</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><build><plugins><plugin><artifactId>maven-surefire-plugin</artifactId><configuration><additionalClasspathElements><additionalClasspathElement>${env.JBOSS_HOME}/client/jbossws-native-client.jar</additionalClasspathElement><!-- Because jbossweb.sar contains shared web.xml, which must be visible from same CL as TomcatDeployer.class.getClassLoader --><additionalClasspathElement>${env.JBOSS_HOME}/server/default/deploy/jbossweb.sar</additionalClasspathElement></additionalClasspathElements><redirectTestOutputToFile>true</redirectTestOutputToFile><trimStackTrace>false</trimStackTrace><printSummary>true</printSummary><forkMode>once</forkMode><!-- MaxPermSize Required to bump the space for relective data like classes, methods, etc. EMB-41. Endorsed required for things like WS support (EMB-61) --><argLine>-Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Djava.endorsed.dirs=${env.JBOSS_HOME}/lib/endorsed -Djboss.home=${env.JBOSS_HOME} -Djboss.boot.server.log.dir=${env.JBOSS_HOME}</argLine></configuration></plugin></plugins></build></profile>

9.7. JBoss Reloaded 1.0 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
JBoss Reloaded(MicroContainer + VirtualDeploymentFramework) instance.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.13. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

9.8. GlassFish 3.0 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
GlassFish 3.0 instance.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

9.10. Tomcat 6.0 - Embedded

A DeployableContainer implementation that manages the complete lifecycle
of an embedded (same JVM) Tomcat 6 Servlet Container. (Keep in mind that
only select EE APIs are available in Tomcat 6, such as JNDI and Servlet
2.5). Test archives are adapted to Tomcat's StandardContext API by
ShrinkWrap and deployed programmatically.

Table 9.18. Container Injection Support Matrix

@Resource

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Warning

CDI support requires use of Weld Servlet and associated configuration. The WAR will
have to be unpacked as well in order for Weld to locate the classes. See the following configuration example.

Running an in-container test on Tomcat 6 currently requires that you add
the Arquillian Protocol Servlet to the test archive's web.xml, a temporary
measure until ARQ-217 is resolved. The listing
below shows a minimum web.xml containing the required Servlet mapping:

If you forget to add this Servlet mapping for a test using the
in-container run mode, you will get a failure with the message "Kept
getting 404s" because Arquillian can't communicate with the deployed
application.

9.10.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.tomcat.embedded_6

Table 9.19. Container Configuration Options

Name

Type

Default

Description

bindHttpPort

int

9090

The HTTP port the server should bind to.

bindAddress

String

localhost

The host the server should be run on.

tomcatHome

String

Optional location of a Tomcat installation to link against.

serverName

String

Optional name of the server

appBase

String

Optional relative or absolute path to the directory where applications are deployed (e.g., webapps).

workDir

String

Optional relative or absolute path to the directory where applications are expanded and session serialization data is stored (e.g., work).

9.11. Jetty 6.1 - Embedded

A DeployableContainer implementation that can run and connect to a
embedded (same JVM) Jetty 6.1 Servlet Container. The minimum recommended
version is Jetty 6.1.12, though you can use an earlier 6.1 version if you
aren't using JNDI resources. Only select EE APIs are available, such as
JNDI and Servlet 2.5. This implementation has lifecycle support, so the
container will be started and stopped as part of the test run.

Table 9.20. Container Injection Support Matrix

@Resource

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Warning

CDI support requires use of Weld Servlet.

9.11.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jetty.embedded_6_1

Table 9.21. Container Configuration Options

Name

Type

Default

Description

bindHttpPort

int

9090

The HTTP port the server should bind to.

bindAddress

String

localhost

The host the server should be run on.

jettyPlus

boolean

true

Activates the Jetty plus configuration to support JNDI resources (requires jetty-plus and jetty-naming artifacts on the classpath).

9.12. Jetty 7.0 - Embedded

A DeployableContainer implementation that can run and connect to a
embedded (same JVM) Jetty 7 Servlet Container. Only select EE APIs are
available, such as JNDI and parts of Servlet (support for
web-fragement.xml is the important bit). This implementation has
lifecycle support, so the container will be started and stopped as part
of the test run.

Table 9.22. Container Injection Support Matrix

@Resource

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Warning

CDI support requires use of Weld Servlet.

9.12.1. Configuration

Namespace: urn:arq:org.jboss.arquillian.container.jetty.embedded_7

Table 9.23. Container Configuration Options

Name

Type

Default

Description

bindHttpPort

int

9090

The HTTP port the server should bind to.

bindAddress

String

localhost

The host the server should be run on.

jettyPlus

boolean

true

Activates the Jetty plus configuration to support JNDI resources (requires jetty-plus and jetty-naming artifacts on the classpath).

9.13. Weld SE 1.0 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
Weld(CDI reference implementation) SE edition. No EE APIs are available.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.24. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Warning

Local EJBs only, which get treated as managed beans. Transactions, security and EJB context injection are not applied.

9.14. Weld EE 1.1 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
Weld(CDI reference implementation) EE version. Mock EE APIs are available.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.25. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Warning

Local EJBs only, which get treated as managed beans. Transactions, security and EJB context injection are not applied.

To run Weld EE Embedded you also need the Java EE APIs.
These APIs might be provided to you by other dependencies like org.jboss.jbossas:jboss-as-client,
org.jboss.spec:jboss-javaee-6.0 or
org.glassfish.extras:glassfish-embedded-all.

9.15. IronJacamar 1.0 - Embedded

A DeployableContainer implementation that can run and connect to a
embedded (same JVM) Ironjacamar 1.0 JCA Container. Only the Java EE Connector
Architecture 1.6 API is available. This implementation has
lifecycle support, so the container will be started and stopped as part
of the test run.

Table 9.27. Container Injection Support Matrix

@Resource

The IronJacamar user guide contains information
on how to setup the IronJacamar/Embedded environment.

9.16. Apache OpenWebBeans 1.0 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
WeldApache OpenWebBeans(CDI) instance. No EE APIs are available.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.28. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (CDI)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Warning

Local EJBs only, which get treated as managed beans. Transactions, security and EJB context injection are not applied.

9.17. Apache OpenEJB 3.1 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
Apache OpenEJB instance. EJB 3.0 APIs are available, but no JMS.
This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

9.18. OSGi 4.2 - Embedded

A DeployableContainer implementation that can run and connect to a embedded(same JVM)
OSGi container. This implementation has lifecycle support, so the container will be started and stopped as part of
the test run.

Table 9.30. Container Injection Support Matrix

@EJB

@EJB (no-interface)

@Inject (JSR-330)

@Inject (MC)

@PersistenceContext @PersistenceUnit

Note

This container use @javax.inject.Inject as a injection point marker. Supports injection of Bundle and BundleContext.

Chapter 10. Complete Extension/Framework Reference

10.1. Performance

The performance extension to Arquillian is a simple way of checking that the code you want to test performs within the range you want it to. It's can also automatically catch any performance regressions that might be added to your applications.
- and as Arquillian itself, its very easy to use.

As you can see the only two additions needed are @Performance and
@PerformanceTest. They do different things and can be used seperately or combined.

@Performance require one argument, time (a double) which set the required maximum time that the test is allowed to spend in milliseconds. If the test exceeds that time it will fail with an exception explaining the cause.

@PerformanceTest will cause every testrun of that test to be saved and every new run will compare results with previous runs. If the new testrun exceeds the previous runs with a defined threshold an exception will be thrown. The threshold can be set with the parameter resultsThreshold. It is by default set to 1d.

How threshold is calculated: resultsThreshold * newTime < oldTime.

10.1.2. Maven setup example

The only extra dependency needed is to add arquillian-performance to your pom.xml. Take a look at the Chapter 3, Getting started to see how you set up arquillian using maven.

10.2.2. Maven setup example

The only dependencies needed is to add org.jboss.arquillian.framework:arquillian-framework-jsfunit and org.jboss.jsfunit:jboss-jsfunit-core to your pom.xml.
The rest is handled by Arquillian in the background.
Take a look at the Chapter 3, Getting started to see how you set up arquillian using maven.