Reasons for running FitNesse tests from the command line.

• It's debuggable. All the tests run in a single process unlike the web server test executions.
• Can be included in build scripts like ANT
• It removes the need to start a local FitNesse server to run tests.
• Can generate HTML output to a file
• Can generate XML output to a file

Using the TestRunner

usage: java fitnesse.runner.TestRunner [options] host port page-name
        -v                              verbose: prints test progress to stdout
        -results <filename|'stdout'>    save raw test results to a file or dump to standard output
        -html <filename|'stdout'>       format results as HTML and save to a file or dump to standard output
        -debug                          prints FitServer protocol actions to stdout
        -nopath                         prevents downloaded path elements from being added to classpath
        -suiteFilter <filter>           runs only those tests of a suite which have been marked with the respective filter

There are three required arguments: host port page-name. The command to run all the FitNesse test suite on you local instance of FitNesse is:

java -cp fitnesse.jar fitnesse.runner.TestRunner localhost 80 FitNesse.SuiteAcceptanceTests

The TestRunner, regardless of options, exits with the number of failures + exceptions that occured during execution. An exit value of 0 means all the tests passed. However, without option the program lacks excitement. Adding the -v will give you somthing to watch. There are also other forms of output that are discussed below. The page designated by page-name may be either a suite or test page.

More details about suite filters can be found here.

Dynamic Classpath

By default, the TestRunner will attempt to dynamically modify the classpath of the JVM that invoked the TestRunner class. This can avoid the annoyance of manually building a classpath. However, it must be used properly to be effective.
The dynamically modified classpath is generated by FitNesse in the same way it build the classpath for in-wiki executions; all of the inherited !path elements are accumulated. If these !path elements are fully qualified paths and the TestRunner is invoked on the same machine as the FitNesse server then the tests will probably run fine. If the !path elements are relative path then the TestRunner should be invoked from the working directory of the FitNesse server. If the TestRunner is invoked from another computer, good luck.

Output Formats

The TestRunner offers 3 different formats for output. HTML, XML, and a plain text format called Result format. The Result format is an intermediate format used to store the data while the test is executing. Unless otherwise directed, the results will simply go in a temporary file. After the tests are completed the results will be submitted back to FitNesse for formatting.