The Artima Developer Community
Sponsored Link

Artima SuiteRunner Tutorial
Building Conformance and Unit Tests with Artima SuiteRunner
by Bill Venners
February 10, 2003

<<  Page 2 of 8  >>


Artima SuiteRunner: The Main Concepts

Artima SuiteRunner is both an API and an application. You can use the API to create tests and the application to run them. The Artima SuiteRunner API consists of one package, org.suiterunner. The main concepts in this API are represented by these three types:

To create a test suite, you subclass org.suiterunner.Suite (Suite) and define test methods. A test method is public, returns void, and has a name that starts with "test". For example, class AccountSuite from the account example is a subclass of Suite. Its test methods include testDeposit and testWithdraw.

A Suite can hold references to other Suites. I call the referenced Suites sub-Suites of the referencing Suite. You organize a large test by building a tree of Suites. The base Suite in the tree has sub-Suites, each of which may have sub-Suites, and so on. When you execute the base Suite, it makes sure all Suites in the tree are executed.

Executing a suite of tests involves the three methods shown in Table 1, which are declared in class Suite:

Table 1. Methods used to execute a suite of tests.

Suite Method The Method's Contract
public void execute(Reporter) Execute this suite object.
protected void executeTestMethods(Reporter) Execute zero to many of this suite object's test methods.
protected void executeSubSuites(Reporter) Execute zero to many of this suite object's sub-suites.

Each of the three methods listed in Table 1 accept a org.suiterunner.Reporter (Reporter) as a parameter. Information about the executing suite of tests will be sent to the specified Reporter. Suite.execute simply invokes two other methods declared in Suite: executeTestMethods and executeSubSuites, passing along the specified Reporter. Suite.executeTestMethods discovers test methods with reflection, invokes them, and sends results to the specified Reporter. Suite.executeSubSuites invokes execute on each sub-Suite. The three methods shown in Table 1 can be overridden in Suite subclasses if different behavior is desired.

The Reporter interface declares several methods that are used to report information about a running test. Classes that implement Reporter decide how to present reported information to the user. For example, reported information could be displayed in a graphical user interface, written to a file, printed to the standard output or error streams, inserted into a database, organized into web pages, and so on. Table 2 shows the methods declared in interface Reporter that are used to report information about a running suite of tests.

Table 2. Methods used to report information about a running suite of tests.

Reporter Method The Method's Contract
void runStarting(int) Indicates a runner is about run a suite of tests, passing in the expected number of tests.
void suiteStarting(Report) Indicates a suite of tests is about to start executing.
void testStarting(Report) Indicates a suite (or other entity) is about to start a test.
void testFailed(Report) Indicates a suite (or other entity) has completed running a test that failed.
void testSucceeded(Report) Indicates a suite (or other entity) has completed running a test that succeeded.
void suiteAborted(Report) Indicates the execution of a suite of tests has aborted, likely because of an error, prior to completion.
void suiteCompleted(Report) Indicates a suite of tests has completed executing.
void infoProvided(Report) Provides information that is not appropriate to report via any other Reporter method.
void runAborted(Report) Indicates a runner encountered an error while attempting to run a suite of tests.
void runStopped(Report) Indicates a runner has stopped running a suite of tests prior to completion, likely because of a stop request.
void runCompleted(Report) Indicates a runner has completed running a suite of tests.

Most of the Reporter methods shown in Table 3 accept an instance of class org.suiterunner.Report. Class Report is a bundle of information including an Object source, a String name, a String message, a Date, a Thread, and an optional Throwable. You can subclass Report if you wish to send additional information to custom Reporter classes that know how to use the additional information.

By simply invoking execute on the base Suite in a tree of Suites, you cause all test methods in all Suites in the tree to be invoked. (This default behavior can be modified by overriding the execute methods shown in Table 1.) Since the Reporter is passed along to all execute methods, the results of all the test methods will be sent to the Reporter. You can inspect the test results presented by the Reporter.

To run a Suite, you specify the class name of the Suite to the org.suiterunner.Runner (Runner) application. Runner loads the class, instantiates it, and invokes execute on the resulting Suite object, passing in a Reporter. Runner decides which Suite or Suites to execute and which Reporter or Reporters to pass based on either command line parameters or a recipe file. A recipe file contains properties that define information that describes a single run of a particular suite of tests. If you specify multiple Suites, Runner executes them sequentially. If you specify multiple Reporters, Runner adds them to a single dispatch Reporter that forwards all method invocations to each specified Reporter. Runner then passes the dispatch Reporter to the specified Suite's execute method. Runner also provides a graphical user interface that gives you many more ways to run suites of tests and inspect their results.

<<  Page 2 of 8  >>

Sponsored Links

Copyright © 1996-2018 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use