org.scalatest.events

Event used to provide alert notifications.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire an AlertProvided event like this:

report(AlertProvided(ordinal, message, Some(NameInfo(suiteName, suiteId, Some(thisSuite.getClass.getName), Some(testName)))))

AlertProvided differs from InfoProvided in that unlike InfoProvided, AlertProvided isn't a RecordableEvent. If fired becase of an alert call from a test, for example, the AlertProvided will immediately be sent to the reporters rather than being stored and sent in the recordedEvents field of the test completion event. Thus, AlertProvided enables "status notifications" to be provided while tests are happening. The difference between AlertProvided and NoteProvided, which is also a "status notification" fired immediately during tests, is that AlertProvided is intended for warnings, where as NoteProvided is just for information. As an illustration, AlertProvided messages are displayed in yellow, NoteProvided in green, in the stdout, stderr, and file reporters.

An AlertProvided event may be fired from anywhere. In this respect AlertProvided is different from events for which it is defined whether they are fired in the context of a suite or test. If fired in the context of a test, the AlertProvided event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the AlertProvided event should include a NameInfo in which testName is not defined. If fired within the context of neither a suite nor a test, the nameInfo of the AlertProvided event (an Option[NameInfo]) should be None.

Event that indicates a runner has completed searching for suites.

Event that indicates a runner is beginning search for suites to run.

A base class for the events that can be passed to the report function passed to the execute method of a Suite.

Marker trait for test failed and test canceled events.

Abstract class for the optional formatter objects that must be passed to the Events reported during a ScalaTest run.

A Formatter providing information that enables reporters to create more stylized output.

An example is that specification-style suites, such as FunSpec, generate output that reads more like a specification, for instance:

A Stack (when newly created)
- should be empty
- should complain when popped

This output might be generated by ScalaTest's standard out reporter. Each of these lines would be taken from the IndentedText's formattedText parameter. Were this same run to be reported in HTML or in a GUI, the output would be based on the rawText and the indentationLevel. Here's what the IndentedText values would be for each event:

• InfoProvided reported with an:

 IndentedText(
   formattedText = "A Stack (when newly created)",
   rawText = "A Stack (when newly created)",
   indentationLevel = 0
 )

• TestSucceeded reported with an:

 IndentedText(
   formattedText = "- should be empty",
   rawText = "should be empty",
   indentationLevel = 1
 )

• TestSucceeded reported with an:

 IndentedText(
   formattedText = "- should complain when popped",
   rawText = "should complain when popped",
   indentationLevel = 1
 )

One possible way this information could be presented in HTML, for example, is this:

A Stack (when newly created)

• should be empty

• should complain when popped

Event used to provide information that is not appropriate to report via any other Event.

To create instances of this class you may use the factory method provided in its companion object. For example, given a report function named report, you could fire a InfoProvided event like this:

report(InfoProvided(ordinal, message, Some(NameInfo(suiteName, suiteId, Some(thisSuite.getClass.getName), Some(testName)))))

An InfoProvided event may be fired from anywhere. In this respect InfoProvided is different from events for which it is defined whether they are fired in the context of a suite or test. If fired in the context of a test, the InfoProvided event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the InfoProvided event should include a NameInfo in which testName is not defined. If fired within the context of neither a suite nor a test, the nameInfo of the InfoProvided event (an Option[NameInfo]) should be None.

An arbitrary line number in a named source file.

Location in source code indicating where in the source code an event originated.

Event used to provide markup text for document-style reports.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a MarkupProvided event like this:

report(MarkupProvided(ordinal, text, Some(NameInfo(suiteName, suiteId, Some(thisSuite.getClass.getName), Some(testName)))))

A MarkupProvided event may be fired from anywhere. In this respect MarkupProvided is different from the other events, for which it is defined whether they are fired in the context of a suite or test. If fired in the context of a test, the MarkupProvided event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the MarkupProvided event should include a NameInfo in which testName is not defined. If fired within the context of neither a suite nor a test, the nameInfo of the MarkupProvided event (an Option[NameInfo]) should be None.

A Formatter that indicates reporters may wish to suppress reporting of an Event. "Suppress" means that the event won't be reported to the user.

An example is that specification-style suites, such as FunSpec, generate output that reads more like a specification. One aspect of this is that generally only a single event should be reported for each test, so that output can appear like this:

A Stack (when newly created)
- should be empty
- should complain when popped

ScalaTest suites should generate two events per test, a TestStarting event and either a TestSucceeded or a TestFailed event. The FunSpec trait does report both events, but passes a MotionToSuppress along with the TestStarting event. As a result, The TestStarting events have no effect on the output. Each TestSucceeded or TestFailed event, which is sent with an IndentedText formatter instead of a MotionToSuppress, will generate output, such as "- should be empty".

Reporters may choose to ignore a MotionToSuppress. For example, an XML reporter may want to report everything about every event that is fired during a concurrent run, so that the events can be reordered later by reading the complete, but unordered, information from an XML file. In this case, the XML reporter would actually report events that were fired with a MotionToSuppress, including indicating that the report included a motion to suppress.

Class that holds information about names for the information events InfoProvided, MarkupProvided, ScopeOpened, ScopeClosed, ScopePending, AlertProvided and NoteProvided.

An information event may be fired from anywhere. In this respect these events are different from the other events, for which it is defined whether they are fired in the context of a suite or test. If fired in the context of a test, an information event event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the InfoProvided event should include a NameInfo in which testName is not defined. If fired within the context of neither a suite nor a test, the nameInfo of the InfoProvided event (an Option[NameInfo]) should be None.

If either suiteClassName or testName is defined, then suiteName and suiteId must be defined. The suite class name parameter is optional even if a suite name is provided by passing a Some as suiteName, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event used to provide notifications.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a NoteProvided event like this:

report(NoteProvided(ordinal, message, Some(NameInfo(suiteName, suiteId, Some(thisSuite.getClass.getName), Some(testName)))))

NoteProvided differs from InfoProvided in that unlike InfoProvided, NoteProvided isn't a RecordableEvent. If fired because of a note call from a test, for example, the NoteProvided will immediately be sent to the reporters rather than being stored and sent in the recordedEvents field of the test completion event. Thus, NoteProvided enables "status notifications" to be provided while tests are happening. The difference between NoteProvided and AlertProvided, which is also a "status notification" fired immediately during tests, is that AlertProvided is intended for warnings, where as NoteProvided is just for information. As an illustration, AlertProvided messages are displayed in yellow, NoteProvided in green, in the stdout, stderr, and file reporters.

An NoteProvided event may be fired from anywhere. In this respect NoteProvided is different from events for which it is defined whether they are fired in the context of a suite or test. If fired in the context of a test, the NoteProvided event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the NoteProvided event should include a NameInfo in which testName is not defined. If fired within the context of neither a suite nor a test, the nameInfo of the NoteProvided event (an Option[NameInfo]) should be None.

Marker trait for the "notification" events NoteProvided and AlertProvided.

Class used to specify a sequential order for events reported during a test run, so they can be arranged in that order in a report even if the events were fired in some other order during concurrent or distributed execution.

An Ordinal is an immutable object holding a run stamp and a sequence of stamps. The run stamp is an integer that identifies a particular run. All events reported during the same run should share the same run stamp. By contrast, each event reported during a particular run should have a different stamp sequence. One use case for the run stamp is that the initial run from ScalaTest's GUI will have run stamp 0. Subsequent reruns will have run stamps 1, 2, 3, etc., so that reports in the GUI can simply be sorted in "ordinal" order. Another use case is a set of servers used to run multiple tests simultaneously in a distributed fashion. The run stamp can be used to identify the run to which an event belongs.

The stamp sequence is designed to allow a sequential order of events to be specified during concurrent execution of ScalaTest suites. ScalaTest's model for concurrent execution is that the suites that make up a run may be executed concurrently, but the tests within a single suite will be executed sequentially. In addition to tests, suites may contain nested suites. The default implementation of execute in class Suite will first invoke runNestedSuites and then runTests. If no Distributor is passed to execute, the runNestedSuites method will execute the nested suites sequentially via the same thread that invoked runNestedSuites. As a result, suites will by default executed in depth first order when executed sequentially. If a Distributor is passed to execute, the runNestedSuites method will simply put its nested suites into the Distributor and return. Some other threads or processes must then execute those nested suites. Given the default implementations of execute and runNestedSuites described here, the Ordinal will allow the events from a concurrent run to be sorted in the same depth-first order that the events from a corresponding sequential run would arrive.

Each event reported during a run should be given a unique Ordinal. An Ordinal is required by all Event subclasses, instances of which are used to send information to the report function passed to a Suite's execute method. The first Ordinal for a run can be produced by passing a run stamp to Ordinal's lone public constructor:

val firstOrdinal = new Ordinal(99)

The run stamp can be any integer. The Ordinal created in this way can be passed along with the first reported event of the run, such as a RunStarting event. Thereafter, new Ordinals for the same run can be obtained by calling either next or nextNewOldPair on the previously obtained Ordinal. In other words, given an Ordinal, you can obtain the next Ordinal by invoking one of these two "next" methods on the Ordinal you have in hand. Before executing a new Suite, the nextNewOldPair method should be invoked. This will return two new Ordinals, one for the new Suite about to be executed, and one for the currently executing entity (either a Suite or some sort of test runner). At any other time, the next Ordinal can be obtained by simply invoking next on the current Ordinal.

You can convert an Ordinal to a List by invoking toList on it. The resulting List will contain the run stamp as its first element, and the contents of its stamps sequence as the subsequent elements. The stamps sequence will initially be composed of a single element with the value 0. Thus, toList invoked on the firstOrdinal shown above will result in:

firstOrdinal.toList // results in: List(99, 0)

Each time next is invoked, the rightmost integer returned by toList will increment:

val secondOrdinal = firstOrdinal.next
secondOrdinal.toList // results in: List(99, 1)

val thirdOrdinal = secondOrdinal.next
thirdOrdinal.toList  // result is : List(99, 2)

When nextNewOldPair is invoked the result will be a tuple whose first element is the first Ordinal for the new Suite about to be executed (for example, a nested Suite of the currently executing Suite). The second element is the next Ordinal for the currently executing Suite or other entity:

val (nextForNewSuite, nextForThisRunner) = thirdOrdinal.nextNewOldPair
nextForNewSuite.toList   // results in: (99, 2, 0)
nextForThisRunner.toList // results in: (99, 3)

The toList method of the Ordinal for the new suite starts with the same sequence of elements as the Ordinal from which it was created, but has one more element, a 0, appended at the end. Subsequent invocations of next on this series of Ordinals will increment that last element:

val newSuiteOrdinal2 = nextForNewSuite.next
newSuiteOrdinal2.toList // results in: List(99, 2, 1)

val newSuiteOrdinal3 = newSuiteOrdinal2.next
newSuiteOrdinal3.toList  // result is : List(99, 2, 2)

This behavior allows events fired by Suite running concurrently to be reordered in a pre-determined sequence after all the events have been reported. The ordering of two Ordinals can be determined by first comparing the first element of the Lists obtained by invoking toList on both Ordinals. These values represent the runStamp. If one run stamp is a lower number than the other, that Ordinal comes first. For example, an Ordinal with a run stamp of 98 is ordered before an Ordinal with a run stamp of 99. If the run stamps are equal, the next number in the list is inspected. As with the run stamps, an Ordinal with a lower number is ordered before an Ordinal with a higher number. If two corresponding elements are equal, the next pair of elements will be inspected. This will continue no down the length of the Lists until a position is found where the element values are not equal, or the end of one or both of the Lists are reached. If the two Lists are identical all the way to the end, and both Lists have the same lengths, then the Ordinals are equal. (Equal Ordinals will not happen if correctly used by creating a new Ordinal for each fired event and each new Suite.). If the two Lists are identical all the way to the end of one, but the other List is longer (has more elements), then the shorter list is ordered before the longer one.

As an example, here are some Ordinal List forms in order:

List(99, 0)
List(99, 1)
List(99, 2)
List(99, 2, 0)
List(99, 2, 1)
List(99, 2, 2)
List(99, 2, 2, 0)
List(99, 2, 2, 1)
List(99, 2, 2, 2)
List(99, 2, 3)
List(99, 2, 4)
List(99, 2, 4, 0)
List(99, 2, 4, 1)
List(99, 2, 4, 2)
List(99, 3)
List(99, 4)
List(99, 4, 0)
List(99, 4, 1)
List(99, 5)

Marker trait for test completed event's recordedEvents.

Event that indicates a runner encountered an error while attempting to run a suite of tests.

For example, object Runner reports RunAborted if the execute method of any of the run's starting Suites completes abruptly with a Throwable.

ScalaTest's Runner fires a RunAborted report with an empty summary, because the reporter is responsible for keeping track of the total number of tests reported as succeeded, failed, ignored, and pending. ScalaTest's internal reporter replaces the RunAborted with a new one that is identical except that is has a defined summary.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a RunAborted event like this:

report(RunAborted(ordinal, message, Some(exception)))

Event that indicates a runner has completed running a suite of tests.

Suite's execute method takes a Stopper, whose stopRequested method indicates a stop was requested. If true is returned by stopRequested while a suite of tests is running, the execute method should promptly return even if that suite hasn't finished running all of its tests.

If a stop was requested via the Stopper. Runner will report RunStopped when the execute method of the run's starting Suite returns. If a stop is not requested, Runner will report RunCompleted when the last execute method of the run's starting Suites returns.

ScalaTest's Runner fires a RunCompleted report with an empty summary, because the reporter is responsible for keeping track of the total number of tests reported as succeeded, failed, ignored, pending and canceled. ScalaTest's internal reporter replaces the RunCompleted with a new one that is identical except that is has a defined summary.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a RunCompleted event like this:

report(RunCompleted(ordinal))

Event that indicates a runner is about run a suite of tests.

For example, object Runner reports RunStarting to indicate that the first execute method of a run's initial Suite is about to be invoked.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a RunStarting event like this:

report(RunStarting(ordinal, testCount))

Event that indicates a runner has stopped running a suite of tests prior to completion, likely because of a stop request.

Suite's execute method takes a Stopper, whose stopRequested method indicates a stop was requested. If true is returned by stopRequested while a suite of tests is running, the execute method should promptly return even if that suite hasn't finished running all of its tests.

If a stop was requested via the Stopper. Runner will report RunStopped when the execute method of the run's starting Suite returns. If a stop is not requested, Runner will report RunCompleted when the last execute method of the run's starting Suites returns.

ScalaTest's Runner fires a RunStopped report with an empty summary, because the reporter is responsible for keeping track of the total number of tests reported as succeeded, failed, ignored, pending and canceled. ScalaTest's internal reporter replaces the RunStopped with a new one that is identical except that is has a defined summary.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a RunStopped event like this:

report(RunStopped(ordinal))

Event that indicates a scope has been closed.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a ScopeClosed event like this:

report(ScopeClosed(ordinal, message, Some(NameInfo(suiteName, suiteId, Some(thisSuite.getClass.getName), Some(testName)))))

A ScopeClosed event may be fired from within suites or tests. If fired in the context of a test, the ScopeClosed event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the ScopeClosed event should include a NameInfo in which testName is not defined.

Event that indicates a new scope has been opened.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a ScopeOpened event like this:

report(ScopeOpened(ordinal, message, Some(NameInfo(suiteName, suiteId, Some(thisSuite.getClass.getName), Some(testName)))))

A ScopeOpened event may be fired from within suites or tests. If fired in the context of a test, the ScopeOpened event should include a NameInfo in which testName is defined. If fired in the context of a suite, but not a test, the ScopeOpened event should include a NameInfo in which testName is not defined.

Event that indicates a scope is pending.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a ScopePending event like this:

report(ScopePending(ordinal, message, Some(NameInfo(suiteName, Some(thisSuite.getClass.getName), Some(testName)))))

A ScopePending event is fired from within suites, and not tests. The ScopePending event should include a NameInfo in which testName is not defined.

Indicates the location should be taken from the stack depth exception, included elsewhere in the event that contained this location.

Event that indicates the execution of a suite of tests has aborted, likely because of an error, prior to completion.

For example, trait Suite and object Runner use SuiteAborted to report that the execute method of a Suite has completed abruptly with a RuntimeException.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a SuiteAborted event like this:

report(SuiteAborted(ordinal, userFriendlyName, message, suiteName, Some(thisSuite.getClass.getName)))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a suite of tests has completed executing.

For example, trait Suite and object Runner use SuiteCompleted to report that the execute method of a Suite has returned normally (without throwing a RuntimeException).

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a SuiteCompleted event like this:

report(SuiteCompleted(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName)))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a suite of tests is about to start executing.

For example, trait Suite and object Runner use SuiteStarting to report that the execute method of a Suite is about to be invoked.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a SuiteStarting event like this:

report(SuiteStarting(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName)))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Class each of whose instances hold summary information about one ScalaTest run.

Event that indicates a test was canceled, i.e., it couldn't run because some precondition was not met.

To create instances of this class you may use the factory methods. For example, given a report function named report, you could fire a TestCanceled event like this:

report(TestCanceled(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName), testName))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a suite (or other entity) has completed running a test that failed.

For example, trait Suite uses TestFailed to report that a test method of a Suite completed abruptly with an Exception.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a TestFailed event like this:

report(TestFailed(ordinal, userFriendlyName, message, suiteName, Some(thisSuite.getClass.getName), testName))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a suite (or other entity) has ignored a test.

For example, trait Suite uses TestIgnored to report that a test method of a Suite was ignored because it was annotated with @Ignore. Ignored tests will not be run, but will usually be reported as reminder to fix the broken test.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a TestIgnored event like this:

report(TestIgnored(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName), testName))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a test is pending, i.e., it hasn't yet been implemented.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a TestPending event like this:

report(TestPending(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName), testName))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a suite (or other entity) is about to start running a test.

For example, trait Suite uses TestStarting to report that a test method of a Suite is about to be invoked.

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a TestStarting event like this:

report(TestStarting(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName), testName))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

Event that indicates a suite (or other entity) has completed running a test that succeeded.

For example, trait Suite uses TestSucceeded to report that a test method of a Suite returned normally (without throwing an Exception).

To create instances of this class you may use the factory method. For example, given a report function named report, you could fire a TestSucceeded event like this:

report(TestSucceeded(ordinal, userFriendlyName, suiteName, Some(thisSuite.getClass.getName), testName))

The suite class name parameter is optional, because suites in ScalaTest are an abstraction that need not necessarily correspond to one class. Nevertheless, in most cases each suite will correspond to a class, and when it does, the fully qualified name of that class should be reported by passing a Some for suiteClassName. One use for this bit of information is JUnit integration, because the "name" provided to a JUnit org.junit.runner.Description appears to usually include a fully qualified class name by convention.

The location in a source file where the class whose by the fully qualified name is passed as className is declared.

The location in a source file where the method identified by the passed methodId in the class whose fully qualified name is pased as className is declared. The methodId is obtained by calling toGenericString on the java.lang.reflect.Method object representing the method.