Package sbt.testing

Interface Runner

public interface Runner

Represents one run of a suite of tests.

The run represented by a Runner has a lifecycle. The run begins when the Runner is instantiated by the framework and returned to the client during a Framework.runner invocation. The run continues until the client invokes done on the Runner. Before invoking done, the client can invoke the tasks method as many times at it wants, but once done has been invoked, the Runner enters "spent" mode. Any subsequent invocations of tasks will be met with an IllegalStateException.

Method Summary

Modifier and Type	Method	Description
java.lang.String[]	args()	Returns thge arguments that were used to create this Runner.
java.lang.String	done()	Indicates the client is done with this Runner instance.
java.lang.String[]	remoteArgs()	Remote args that will be passed to Runner in a sub-process as remoteArgs.
Task[]	tasks(TaskDef[] taskDefs)	Returns an array of tasks that when executed will run tests and suites determined by the passed TaskDefs.

Method Detail

tasks

Task[] tasks(TaskDef[] taskDefs)

Returns an array of tasks that when executed will run tests and suites determined by the passed TaskDefs.

Each returned task, when executed, will run tests and suites determined by the test class name, fingerprints, "explicitly specified" field, and selectors of one of the passed TaskDefs.

This tasks method may be called with TaskDefs containing the same value for testClassName but different fingerprints. For example, if both a class and its companion object were test classes, the tasks method could be passed an array containing TaskDefs with the same name but with a different value for fingerprint.isModule.

A test framework may "reject" a requested task by returning no Task for that TaskDef.

Parameters:

taskDefs - the TaskDefs for requested tasks

Returns:

an array of Tasks

Throws:

java.lang.IllegalStateException - if invoked after done has been invoked.

done

java.lang.String done()

Indicates the client is done with this Runner instance.

After invoking the done method on a Runner instance, the client should no longer invoke the task methods on that instance. (If the client does invoke task after done, it will be rewarded with an IllegalStateException.)

Similarly, after returning from done, the test framework should no longer write any messages to the Logger, nor fire any more events to the EventHandler, passed to Framework.runner. If the test framework has not completed writing log messages or firing events when the client invokes done, the framework should not return from done until it is finished sending messages and events, and may block the thread that invoked done until it is actually done.

In short, by invoking done, the client indicates it is done invoking the task methods for this run. By returning from done, the test framework indicates it is done writing log messages and firing events for this run.

If the client invokes done more than once on the same Runner instance, the test framework should on subsequent invocations should throw IllegalStateException.

The test framework may send a summary (i.e., a message giving total tests succeeded, failed, and so on) to the user via a log message. If so, it should return the summary from done. If not, it should return an empty string. The client may use the return value of done to decide whether to display its own summary message.

The test framework may return a multi-lines string (i.e., a message giving total tests succeeded, failed and so on) to the client.

Returns:

a possibly multi-line summary string, or the enpty string if no summary is provided

remoteArgs

java.lang.String[] remoteArgs()

Remote args that will be passed to Runner in a sub-process as remoteArgs.

Returns:

an array of strings that will be passed to Runner in a sub-process as remoteArgs.

args

java.lang.String[] args()

Returns thge arguments that were used to create this Runner.

Returns:

an array of argument that is used to create this Runner.