Arquillian - Test in the Container with GlassFish 3.1-b04 Embedded

I am playing around with JBoss Arquillian these days. Arquillian provides a easy mechanism to test your application code inside a remote or embedded container or by interacting as a client of the container. Having all those integration testing issues since years really makes me wanting all those stuff. And this week there was time to get my hands on that.

Download and first information
It's simple. Grep your copy of the Arquillian Examples from Github and start using it. You can either download or even checkout the repository. It's also a very good idea to make yourself familiar with the reference guide.
The examples are based on the latest Arquillian 1.0.0.Alpha4 and this probably is the first hint for what to expect. It's an alpha. Even if the reference guide gives very helpfull information there is still a lack of public solutions to many things you come across. So you are up to the help of the guys who created it. Thank god, they are available and very responsive. (Thanks to @aslakknutsen and @mojavelinux for the latest help and ideas!) If you are having problems, the first place to look is the user forum. It's there since September and already contains 127 threads to look for solutions.

Getting Started
Extract the arquillian-arquillian-examples-XXXXX.zip archive to a suitable location. All you need is a recent JDK (1.6.0_21) and Maven (3.0). The best place to start is the ejb31-gfembedded example. In most cases this will not work out of the box. I had  to adjust a couple of things to get this running.

1) Repositories
You need access to some JBoss maven repositories in order to build your example. Add the JBoss public repository as a repository and additional as pluginRepository in your projects pom.xml.
2) Offline/Proxy issues with GF
If you are working behind a corporate proxy, you need to add a build section with the maven-surefire-plugin to your pom.xml. Add both systemProperties relevant: http.proxyHost and http.proxyPort. Offline testing is not possible at the moment. Because Arquillian only runs with GF 3.1-b04 which has an issue trying to download schema ressources from sun.com.
3) Arquillian configuration files
If you are not adding an arquillian.xml to your project you will get into trouble with temp gf folders. It's best to exactly configure where you have your instance_root. This is done via the arquillian.xml file. Add a src\test\resources folder and put it in there. Configure the instanceRoot to be at src/test/glassfish and create the folder. Next is to add a testResource pointing to src\test\resources in your pom.xml

Executing your tests
Done. Now you are set. Get a cmd line and enter mvn test -Pglassfish-embedded-3. You see a couple of log messages streamed to your console. The most important one:


INFO: GlassFish3.1-b04 (java_re-private) startup time : Embedded(406ms) startup services(312ms) tota
l(718ms)

followed by

INFO: Portable JNDI names for EJB HelloEJB : [java:global/test/HelloEJB, java:global/test/HelloEJB!o
rg.jboss.arquillian.examples.gfembedded.HelloEJB]

which both tells you, that the embedded server started and your HelloEJB was bound to the JNDI tree. And finally you have the test-results.

-------------------------------------------------------------------------------
Test set: org.jboss.arquillian.examples.gfembedded.HelloEJBTest
-------------------------------------------------------------------------------
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 9.563 sec

You can find an output per testcase in the target/surefire-reports folder. This also contains an XML with all the testsuite properties used and the testcase itself.

Some more hints
It took quite some time to get this up and running. There are some examples in the initial distribution also (arquillian-1.0.0.Alpha4\examples\junit) but I was not able to get them to work. Still not giving up, but it's hard because missing qualified error output. You only get logfiles and they collect errors no matter from where they are. If you are looking for the actuall deployment that Arquillian tries to deploy, you can add an engine entry to your arquillian.xml

<engine>
<deploymentExportPath>target/temp</deploymentExportPath>
</engine>

This puts the generated jar to the target directory. Helpfull, if you are tracking down things in the server.
Also don't try to use a later GlassFish build than b04. This leads to a couple of problems and exceptions, that needed to be tracked down further. Seems as if some older TLDScanner things came up again.

Where next
This was a very short howto about running a simple example with Arquillian. Now you have a working environment to make yourself compfortable with this awesome tool and you should actually start looking at the executed testcase and try to write some yourself. I have never ever seen a tool before which could run my integration tests with that ease. I am really looking forward to the next versions and I still hope, that the guys at JBoss start having a more frequent look at
a) their examples and
b) the integration with the Java EE 6 Reference Implementation.