sbt.testing.Runner Maven / Gradle / Ivy
package sbt.testing;
/**
* 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 task methods as many times at it wants, but once
* done has been invoked, the Runner enters "spent" mode. Any
* subsequent invocations of task methods will be met with an
* IllegalStateException.
*
*/
public interface Runner {
/**
* Returns a task that when executed will run tests and suites determined by the
* passed test class name, fingerprints, "explicitly specified" flag, and selectors.
*
*
* "Explicitly specified" means the user supplied a complete fully qualified test name, such as with the command:
*
*
*
* > test-only com.mycompany.myproject.WholeNameSpec
*
*
*
* as opposed to commands like:
*
*
*
* > test-only *WholeNameSpec
*
*
*
* or simply:
*
*
*
* > test
*
*
*
* The explicitlySpecified flag will be true for in the first case, and false in the last two cases, because only
* in the first case was the fully qualified test class name completely specified by the user. The test framework can use this information
* to decide whether to ignore an annotation requesting a class not be discovered.
*
*
*
* The fingerprint parameter indicates how the test suite was identified as a test suite. This task
* method may be called with the same value for testClassName but different fingerprints. For example, if both a
* class and its companion object were test classes, this method would be called with the same name but with a different value
* for fingerprint.isModule.
*
*
*
* A test framework may "reject" a requested task by returning a Task that does nothing.
*
*
* @param fullyQualifiedName the fully qualified name of the test class to be run by the returned task
* @param fingerprint indicates how the test suite was identified as a test suite.
* @param explicitlySpecified indicates whether the test class is explicitly specified by user.
* @param selectors a possibly empty array Selectors determining suites and tests to run
* @return a task that when executed will run the selected test and/or suite "members" of the passed test class
* @throws IllegalStateException if invoked after done has been invoked.
*/
public Task[] tasks(TaskDef[] taskDefs);
/**
* 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 sbt
*
*
* @return string for sbt to print out as summary
*/
public String done();
/**
* Remote args that will be passed to Runner in sub-process as remoteArgs. This method must not return null.
*
* @return an array of argument that will be passed to Runner in sub-process as remoteArgs.
*/
public String[] remoteArgs();
/**
* Return arguments that is used to create this Runner.
*
* @return an array of argument that is used to create this Runner.
*/
public String[] args();
}