In most contexts, when something doesn’t work, you just Google the error and you’re basically done. One good thing about working for organizations that lag behind technology-wise is that it generally is more challenging and you’re bound to be creative. Me, I’m stuck on JBoss 5.1 EAP, but that doesn’t stop me for trying to use modern approach in software engineering. In the quality domain, one such try is to be able to provide my developers a way to test their code in-container. Since we are newcomers in the EJB3 realm, that means they will have a need for true integration testing.
Given the stacks available at the time of this writing, I’ve decided for Arquillian, which seems the best (and only?) tool to achieve this. With this framework (as well as my faithful TestNG), I was set to test Java EE components on JBoss 5.1 EAP. This article describes how to do just that (as well as mentioning the pitfalls I had to overcome).
Arquillian basics
Arquillian basically provides a way for developers to manage the lifecycle of an application server and deploy a JavaEE artifact in it, in an automated way and integrated with your favorite testing engine (read TestNG - or JUnit if you must). Arquillian architecture is based on a generic engine, and adapters for specific application servers. If no adapter is available for your application server, that’s tough luck. If you’re feeling playful, try searching for a WebSphere adapter… the develop one. The first difficulty was that at the time of my work, there was no JBoss EAP 5.1 adapter, but I read from the web that it’s between a 5.0 GA and a 6.0 GA: a lengthy trial-and-error process took place (now, there’s at least some documentation, thanks to Arquillian guys hearing my plea on Twitter - thanks!).
Server type and version are not enough to get the right adapter, you’ll also need to choose how you will interact with the application server:
- Embedded: you download all dependencies, provides a configuration and presto, Arquillian magically creates a running embedded application server. Pro: you don’t have to install the app server on each of you devs computer; cons: configuring may well be a nightmare, and there may be huge differences with the final platform, defeating the purpose of integration testing.
- Remote: use an existing and running application server. Choose wisely between a dedicated server for all devs (who will share the same configuration, but also the same resources) and a single app server per dev (who said maintenace nightmare?).
- Managed: same as remote, but tests will start and stop the server. Better suited for one app server per dev.
- Local: I’ve found traces of this one, even though it seems to be buried deep. This seems to be the same as managed, but it uses the filesystem instead of the wire to do its job (starting/stopping by calling scripts, deploying by copying archives to the expected location, …), thus the term local.
Each adapter can be configured according to your needs through the arquilian.xml file.
For Maven users, it takes place at the root of src/test/resources.
Don’t worry, each adapter is aptly documented for configuration parameters.
Mine looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<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">
<container qualifier="jboss" default="true">
<configuration>
<property name="javaHome">${jdk.home}</property>
<property name="jbossHome">${jboss.home}</property>
<property name="httpPort">8080</property>
<property name="rmiPort">1099</property>
<property name="javaVmArguments">-Xmx512m -Xmx768m -XX:MaxPermSize=256m
-Djava.net.preferIPv4Stack=true
-Djava.util.logging.manager=org.jboss.logmanager.LogManager
-Djava.endorsed.dirs=${jboss.home}/lib/endorsed
-Djboss.boot.server.log.dir=${jboss.home}
-Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
</property>
</configuration>
</container>
</arquillian>Finally, the test class itself has to extend org.jboss.arquillian.testng.Arquillian (or if you stick with JUnit, use @RunWith).
The following snippet shows an example of a TestNG test class using Arquillian:
public class WebIT extends Arquillian {
@Test
public void testMethod() { ... }
@Deployment
public static WebArchive createDeployment() { ... }
}Creating the archive
Arquillian tactics regarding in-container testing is to deploy only what you need. As such, it comes with a tool named ShrinkWrap that let you package only the relevant parts of what is to be tested.
For example, the following example creates an archive named web-test.war, bundling the ListPersonServlet class and the web deployment descriptor.
More advanced uses would include libraries.
WebArchive archive = ShrinkWrap.create(WebArchive.class, "web-test.war")
.addClass(ListPersonServlet.class)
.setWebXML(new File("src/main/webapp/WEB-INF/web.xml"));The Arquillian framework will look for a static method, annotated with @Deployment that returns such an archive, in order to deploy it to the application server (through the adapter).
Tip: use the toString() method on the archive to see what it contains if you have errors.
Icing on the Maven cake
Even if you’re no Maven fan, I think this point deserves some attention. IMHO, integration tests shouldn’t be part of the build process since they are by essence more fragile: a simple configuration error on the application server and your build fails without real cause.
Thus, I would recommend putting your tests in a separate module that is not called by its parent.
Besides, I also use the Maven Failsafe plugin, instead of the Surefire one so that I get clean separation of unit tests and integration tests, even with separated modules, so that I get different metrics for both (in Sonar for example).
In order to get that separation out-of-the-box, just ensure your test classes end with IT (like Integration Test).
Note that integration tests are bound to the integration-test lifecycle phase, just before install.
Here comes JBoss EAP
Now comes the hard part, actual deployment on JBoss 5.1 EAP.
This stage will probably last for a long long time, and involve a lot of going back and forth.
In order to be as productive as possible, the first thing to do is to locate the logs.
If you kept the above configurations, they are in the JBoss <profile>/logs directory.
If you feel the logs are too verbose for your own tastes (I did), just change the root priority from ${jboss.server.log.threshold} to INFO in the <profile>/conf/jboss-log4j.xml file.
On my machine, I kept getting JVM bind port errors. Thus, I changed the guilty connector port in the server.xml file (FYI, it was the AJP connector and JBoss stopped complaining when I changed 8009 to 8010).
One last step for EAP is to disable security.
Since it’s enterprise oriented, security is enabled by default in EAP: in testing contexts, I couldn’t care less about authenticating to deploy my artifacts.
Open the <profile>/deploy/profileservice-jboss-beans.xml configuration file and search for "comment this list to disable auth checks for the profileservice".
Do as you’re told 🙂
Alternatively, you could also walk the hard path and configure authentication:
detailed instructions are available on the adapter page.
Getting things done, on your own
Until this point, we more or less followed instructions here and there. Now, we have to sully our nails and use some of our gray matter.
- The first thing to address is some strange `java.lang.IllegalStateException`when launching a test.
Strangely enough, this is caused by Arquillian missing some libraries that have to be ShrinkWrapped along with your real code.
In my case, I had to had the following snippet to my web archive:
MavenDependencyResolver resolver = DependencyResolvers.use(MavenDependencyResolver.class); archive.addAsLibraries( resolver.artifact("org.jboss.arquillian.testng:arquillian-testng-container:1.0.0.Final") .artifact("org.jboss.arquillian.testng:arquillian-testng-core:1.0.0.Final") .artifact("org.testng:testng:6.5.2").resolveAsFiles()); - The next error is much more vicious and comes from Arquillian inner workings.
java.util.NoSuchElementException at java.util.LinkedHashMap$LinkedHashIterator.nextEntry(LinkedHashMap.java:375) at java.util.LinkedHashMap$KeyIterator.next(LinkedHashMap.java:384) at org.jboss.arquillian.container.test.spi.util.TestRunners.getTestRunner(TestRunners.java:60)
When you look at the code, you see Arquillian uses the Service Provider feature (for more info, see here).
But much to my chagrin, it doesn’t configure the implementation the org.jboss.arquillian.container.test.spi.TestRunner service should use and thus fails miserably.
We have to create such a configuration manually: the file should only contain org.jboss.arquillian.testng.container.TestNGTestRunner (for such is the power of the Service Provider).Don’t forget to package it along the archive to have any chance at success:
archive.addAsResource(new File("src/test/resources/META-INF/services"), "META-INF/services");Update [28th May]: the two points above can be abandoned if you use the correct Maven dependency (the Arquillian BOM). Check the POMs in the attached project.
At the end, everything should work fine except a final message log in the test:
Shutting down server: default Writing server thread dump to /path/to/jboss-as/server/default/log/threadDump.log
This means Arquillian cannot shutdown the server because it can’t authenticate.
This would have no consequence whatsoever but it marks the test as failed and thus needs to be corrected.
Edit the <profile>/conf/props/jmx-console-users.properties file and uncomment the admin = admin line.
Conclusion
The full previous steps took me about about half a week work spread over a week (it seems I’m more productive when not working full-time as my brain launches some background threads to solve problems). This was not easy but I’m proud to have beaten the damn thing. Moreover, a couple of proprietary configuration settings were omitted in this article. In conclusion, Arquillian seems to be a nice in-container testing framework but seems to have to be polished around some corners: I think using TestNG may be the cultprit here.
You can find the sources for this article here, in Eclipse/Maven format.