Aiming to Make Testing Easier
Integration Tests with Arquillian - Part 2
If you want to start with Arquillian today, you should be aware that this is still an alpha release. You can download a complete archive from git or build it from sources. The following examples use the Arquillian Examples project, which is based on Arquillian 1.0.0.Alpha4. If you are trying out this alpha release you are not an early follower but a leader. You need the complete stack of brand new technologies.
In addition to Maven 3.0 a current 1.6 Java Development Kit (JDK) is also required. The best way to install the necessary parts is to install the complete development environment and extract the ZIP file with the examples into any directory. The most interesting use case certainly is the testing of Enterprise Java Beans (EJBs). In conjunction with the GlassFish Embedded Server 3.1 this is already included as a pre-configured example. Find it in the folder ejb31-gfembedded. All examples run with Maven. To use the embedded GlassFish as a container, create the required profile called "glassfish-embedded-3" in the projects pom.xml. The example is executed using the "mvn test-Pglassfish-embedded-3" command. A simple one-liner responds any runs or errors. If everything runs smoothly you will see: Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 9828 seconds. If this does not work right away, you have to check for some potential problems and solve them. The number one reason for any errors are unknown or missing Maven repository entries. The Arquillian libraries are in the Public JBoss Repository. This should be referenced from your pom.xml or even settings.xml. If you are experiencing any java.net.ConnectExceptions the reason could be a known bug in Embedded GlassFish. It prevents builds greater than 3.1 b04 from working offline because it is checking for required xml schema files. The same will happen, if you sit behind a proxy or firewall. In this case you need to add some configuration parameters via the Surefire plugin (SystemProperties, http.proxyHost and http.proxyPort). But there are other circumstances, that prevent the most recent Arquillian Alpha from running with the latest GlassFish bits.
During development of GlassFish 3.1 the embedded API changed. This should be reflected with the next Arquillian release. So if you are in need of more recent builds, you should wait a little bit longer for Arquillian to provide an updated version.
If you experience other errors, you are basically helpless at first. Arquillian log messages are generally rare. So you need to dig a little deeper into the configuration. By default, the root directory of GlassFish stays in the target folder which was created by Maven. Each test run creates a new directory there. You can change this behavior by making changes to the arquillian.xml configuration file. It belongs to the src\test\resources folder and should look like this:
Using this configuration, the GlassFish directory used each time a test is run, is always in the same place. You are now free to make any additional entries to the embedded GlassFish configuration by changing the domain.xml. But are you still missing the verbose logging? Then you have to get your hands on the logging.properties file. Simply copy it from an existing GlassFish domain and add it to your development project (For example src\test\gf). Parse it on as a system property (java.util.logging.config.file) to the Surefire plugin. If you now rerun your tests you can see the container log messages.
Another very helpful artifact would be to have a version of the packaged archive that Arquillian is deploying. This is simple, too. Add the following entry to the arquillian.xml.
Besides satisfying your curiosity, this can be especially helpful in future debugging. Particularly if the generated archive can be successfully deployed to a standalone glassfish, it ensures that you are most likely stumbling over some problems that aren't the project developer's fault.
First Simple Testcase
When all preparations are complete, it is time to devote time to the actual test functionality. To test a component in the container, it must be present. A simple Stateless Session Bean HelloEJB should be enough as the first example:
The world's best known example EJB is now being reviewed with a corresponding test case:
The @RunWith JUnit annotation ensures that the Arquillian test runner is used. After that you simply inject the HelloEJB. The @Deployment annotation declares the method that wraps the actual EJB archive. The actual test case is initiated by the annotation @Test in JUnit by known style. The assertEquals checks the return value against a fixed input string. If the two strings match, the test is a success. All other cases produce an error. This simple error doesn't say much about the error in general at a first glance. So you have to check the target\surefire-reports folder for details. Each testcase produces a result in text and xml files. This isn't very handy, but you have to blame Surefire for that, not Arquillian. If you change the EJB call into anything to force an error (e.g. sayHelloEJB ("Markus") you can find the specific error: