JBoss.orgCommunity Documentation
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).
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.
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.
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
-Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"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.
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.
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).
These steps may not be necessary if you have a Maven project and the sources for the library are available in the Maven repository.
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.
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.