Debugging Fitnesse Tests from Intellij IDEA

This is probably of limited interest, since test fixtures should be simple enough that you don’t need to debug them very often.  Plus with Fit, you can edit tests to give yourself visibility to data so actually seeing things run shouldn’t be a primary issue.

However, I’ve found this useful, especially as I try to understand how various fixtures work, or if I’m not getting the behavior I’d expect, when I’m pretty confident the system under test is working properly.

Setting this up is pretty easy.  Basically, you’re trying to get IDEA to connect to the Fitnesse test execution JVM as a remote debugger, so it’s very similar to setting up IDEA to debug Tomcat:

1. Configure the Fitnesse REMOTE_DEBUG_COMMAND variable to listen to the desired port.
2. Create a Remote Debug configuration in IDEA that connects to the configured port.
3. Start the Fitnesse test.
4. Start the Remote Debug configuration in IDEA.

Configure the Fitnesse REMOTE_DEBUG_COMMAND variable

This variable defines how Fitnesse will launch the JVM when executing tests in debug mode.  Per the Fitnesse website, the REMOTE_DEBUG_COMMAND variable is set by default to:

java -Xdebug 
     -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 
     -cp %p %m

If you don’t have something else on port 8000, this might be good enough.  I like to override the default value so I can declare a custom Log4j configuration file location, but YMMV.  Note: Pay attention to the suspend=y value, and don’t change it.  This is very important; I’ll explain below.

In order to set this variable, add this to the test’s page (or the Fitnesse root page).  In the sample below, I change the debug port to 81.  The curly braces are needed so Fitnesse properly interprets the parameters:

!define REMOTE_DEBUG_COMMAND {java -Xdebug 
                                   -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=81 
                                   -cp %p %m}

Create a Remote Debug configuration in IDEA

You need to create a Remote configuration which can connect to the JVM launch by Fitnesse according to the REMOTE_DEBUG_COMMAND you specified already.

1. Select Run: Edit Configurations from the menus.
2. Create a new Remote configuration with the following values:
   • Name: Fitness Debugger
   • Transport: Socket
   • Debugger Mode: Attach
   • Host: Whatever Fitnesse server you’re trying to debug
   • Port: Whatever port you specified in REMOTE_DEBUG_COMMAND

Here is a screen capture of a configuration that would match my sample parameter above, assuming I’m running Fitnesse locally:

If you look closely, you’ll see that the command line arguments that IDEA suggests you use on the system being connected to is almost the same as what I specified for REMOTE_DEBUG_COMMAND, except they say use suspend=n.  Do not do this! Use suspend=y instead, as Fitnesse does by default.  This will cause Fitnesse to wait for a remote debugger to connect before executing the test, which is what you want.  If the suspend parameter is not set to y, then the remote JVM will immediately begin execution, rather than waiting for the IDEA remote debugger to connect to it.

Since the JVM is temporary (it starts at the beginning of test execution), you can’t connect to it before the test begins.  But it takes a bit of time to start up the debugger, so if suspend=n it’s very likely that the test will have completed execution before the debugger can even connect to it.

I use IDEA 8, but setting up the remote configuration in other releases should be similar.

Start the Fitnesse test

There isn’t a button to launch a test in debug mode, but you can do this manually by adding ?responder=test&remote_debug=true to the URL of the page containing the test.

When you do this, the test will begin, but the test page will stay blank.  Fitnesse is waiting for a remote debugger to connect…

Start the Remote Debug configuration in IDEA

In IDEA, select the Fitnesse Debugger configuration and start it in Debug mode.

Now, the test will begin to execute, and it will stop at any breakpoints you’ve set in IDEA, just like if you’re debugging IDEA locally.

Notes of Interest

• This process assumes that Fitnesse is using the same versions of the classes that are currently in IDEA.  If you’re running Fitnesse locally, you can set this up to be done automatically, just by adding classpath references to your IDEA build directory (or directories, if you have different ones for different source directories) to the Fitnesse test.
• If you don’t want to keep manually adjusting the URL to run tests in remote debug mode, here are a couple options to simplify the process:
  • If you set the COMMAND_PATTERN variable to the same value that’s specified above for REMOTE_DEBUG_COMMAND, then using the Test button in the navigation pane will launch the test in remote debug mode every time.
  • The following text added to any page will create a link that will run that page as a test in remote debug mode.  For real simplicity, you could add this to a PageFooter page so it’s included in any subpage…
    • [[Debug Test][${PAGE_NAME}?responder=test&remote_debug=true]]