Non-blocking call that indicates whether the entity represented by this
Status
(one test, one suite, or all of a suite's tests or nested suites) has completed.
Non-blocking call that indicates whether the entity represented by this
Status
(one test, one suite, or all of a suite's tests or nested suites) has completed. Because this is non-blocking,
you can use this to poll the completion status.
Note: this method will not indicate whether a test has failed, suite has aborted, or an unreported exception has been installed.
It just indicates whether the Status
has completed or not by returning true
or false
.
true
if the test or suite run is already completed, false
otherwise.
Blocking call that waits until the entity represented by this Status
(one test, one suite, or all of
a suite's tests or nested suites) has completed, then returns true
if no tests failed and no
suites aborted, else returns false
, or if an unreported exception has been installed, completes
abruptly with that exception.
Blocking call that waits until the entity represented by this Status
(one test, one suite, or all of
a suite's tests or nested suites) has completed, then returns true
if no tests failed and no
suites aborted, else returns false
, or if an unreported exception has been installed, completes
abruptly with that exception.
This method only reports false
if there was a failed test or aborted suite in the context of the "run" lifecycle method
from which it was returned.
For example, if you call succeeds
on a Status
returned by runTest
, succeeds
will (after that test has completed) return false
if the test whose name was passed to runTest
fails,
else it will return true
.
In other words, so long as the test doesn't fail —whether the test succeeds, is canceled, or is pending—succeeds
will return true
.
If you call succeeds
on a Status
returned by runTests
, by contrast, succeeds
will (after the suite's
tests have completed) return true
only if none of the tests in the suite fail. If any test in the suite fails,
succeeds
will return false
.
If you call succeeds
on a Status
returned by runNestedSuites
, succeeds
will
return true only if no tests fail and no suites abort when running all nested suites (and their nested suites, recursively).
Similarly, if you call succeeds
on a Status
returned by run
, succeeds
will
return true only if no tests fail and no suites abort when running all tests nested suites (and their nested suites, recursively).
If this Status
fails with an "unreported exception," an exception that occurred during the
activity represented by this Status
that was not reported to the Reporter
via a
ScalaTest event, the succeeds
method will complete abruptly with that exception. If the
original exception was a run-aborting exception, such as StackOverflowError
, the
unreportedException
method will return a java.util.ExecutionException
that contains
the original run-aborting exception as its cause. The succeeds
method will in that case
complete abruptly with the ExecutionException
that wraps the original run-aborting exception.
Note: because blocking is not possible on Scala.js, this method is not available on Scala.js.
after waiting until completion, true
if no tests failed and no suites aborted, false
otherwise
unreportedException
if an exception occurred during the activity represented by this Status
that was not reported
via a ScalaTest event and therefore was installed as an unreported exception on this Status
.
Blocking call that waits until the entity represented by this Status
(one test, one suite, or all of
a suite's tests or nested suites) has completed, then either returns normally, or if an unreported exception has
been installed, completes abruptly with that unreported exception.
Blocking call that waits until the entity represented by this Status
(one test, one suite, or all of
a suite's tests or nested suites) has completed, then either returns normally, or if an unreported exception has
been installed, completes abruptly with that unreported exception.
If this Status
fails with an "unreported exception," an exception that occurred during the
activity represented by this Status
that was not reported to the Reporter
via a
ScalaTest event, the waitUntilCompleted
method will complete abruptly with that exception. If the
original exception was a run-aborting exception, such as StackOverflowError
, the
unreportedException
method will return a java.util.ExecutionException
that contains
the original run-aborting exception as its cause. The waitUntilCompleted
method will in that case
complete abruptly with the ExecutionException
that wraps the original run-aborting exception.
Note: because blocking is not possible on Scala.js, this method is not available on Scala.js.
unreportedException
if an exception occurred during the activity represented by this Status
that was not reported
via a ScalaTest event and therefore was installed as an unreported exception on this Status
.
Registers the passed callback function to be executed when this status completes.
Registers the passed callback function to be executed when this status completes.
If an unreported exception has been installed on this Status
, the
Try
passed into the callback function will be a Failure
containing that exception. Otherwise
the Try
will be a Success
containing true if no tests failed
or suites aborted during the activity represented by this Status
, else false
.
The callback functions registered with whenCompleted
will be executed after the Status
has completed, in an undefined order. If the Status
has already completed, functions passed to this method will be
executed immediately by the calling thread before returning.
Any exception thrown by a callback function will be propagated back on the thread used to invoke the callback.
Internally ScalaTest uses this method to register callbacks that
fire completion events (TestSucceeded
, TestFailed
,
SuiteCompleted
, etc.) to the Reporter
.
the callback function to execute once this Status
has completed
Registers a Status
-producing by-name function to execute after this
Status
completes, returning a Status
that mirrors the Status
returned by the by-name.
Registers a Status
-producing by-name function to execute after this
Status
completes, returning a Status
that mirrors the Status
returned by the by-name.
The Status
returned by this method will complete when the status produced by the
Status
produced by the passed-by name completes. The returned Status
will complete with the same succeeds
and unreportedException
values.
But unlike the Status
produced by the by-name, the returned Status
will
be available immediately.
If the by-name function passed to this method completes abruptly with a non-run-aborting exception,
that exception will be caught and installed as the unreportedException
on the
Status
returned by this method. The Status
returned by this method
will then complete. The thread that attempted to evaluate the by-name function will be allowed
to continue (i.e.
, the non-run-aborting exception will not be rethrown
on that thread).
If the by-name function passed to this method completes abruptly with a run-aborting exception,
such as StackOverflowError
, that exception will be caught and a new
java.util.concurrent.ExecutionException
that contains the run-aborting exception as its
cause will be installed as the unreportedException
on the
Status
returned by this method. The Status
returned by this method
will then complete. The original run-aborting exception will then be rethrown on the
thread that attempted to evaluate the by-name function.
If an unreported exception is installed on this Status
, the passed by-name function will
not be executed. Instead, the same unreported exception will be installed on the Status
returned by this method.
Internally, ScalaTest uses this method in async styles to ensure that by default, each subsequent test in an async-style
suite begins execution only after the previous test has completed. This method is not used if
ParallelTestExection
is mixed into an async style. Instead, tests are allowed to begin
execution concurrently.
a Status
that represents the status of executing the by-name function passed to this method.
Converts this Status
to a Future[Boolean]
where Success(true)
means
no tests failed and suites aborted, Success(false)
, means at least one test failed or one
suite aborted and any thrown exception was was reported to the Reporter
via a ScalaTest
event, Failure(unreportedException)
means
an exception, unreportedException
, was thrown that was not reported to the Reporter
via a ScalaTest event.
Converts this Status
to a Future[Boolean]
where Success(true)
means
no tests failed and suites aborted, Success(false)
, means at least one test failed or one
suite aborted and any thrown exception was was reported to the Reporter
via a ScalaTest
event, Failure(unreportedException)
means
an exception, unreportedException
, was thrown that was not reported to the Reporter
via a ScalaTest event.
a Future[Boolean]
representing this Status
.
An exception that was thrown during the activity represented by this Status
that
was not reported via a ScalaTest event fired to the Reporter
.
An exception that was thrown during the activity represented by this Status
that
was not reported via a ScalaTest event fired to the Reporter
.
When a test executes, "non-run-aborting" thrown exceptions are reported by events
fired to the reporter. A TestPendingException
is reported via a
TestPending
event. A TestCanceledException
is reported via a
TestCanceled
event. Any other non-run-aborting exceptions, including
TestFailedException
will be reported via a
TestFailed
event.
Run-aborting exceptions indicate critical
problems, such as OutOfMemoryError
, that instead of being reported via a test completion event
should instead cause the entire suite to abort. In synchronous testing styles, this exception will be allowed
to just propagate up the call stack. But in async styles, the thread or threads executing the test will often
be taken from the async suite's execution context. Instead of propagating these run-aborting exceptions up
the call stack, they will be installed as an "unreported exception" in the test's Status
.
They are "unreported" because no test completion event will be fired to report them. For more explanation and
a list of run-aborting exception types, see Treatment of java.lang.Error
s.
Another way for an unreported exception to occur is if an exception of any type is thrown outside of the
body of an actual test. For example, traits BeforeAndAfter
, BeforeAndAfterEach
,
and BeforeAndAfterEachTestData
execute code before and after tests. Traits
BeforeAndAfterAll
and BeforeAndAfterAllConfigMap
execute code before
and after all tests and nested suites of a suite. If any "before" or "after"
code completes abruptly with an exception (of any type, not just run-aborting types) on a thread taken
from an async suite's execution context, this exception will
installed as an unreportedException
of the relevant Status
.
In addition, ScalaTest Suite
exposes four "run" lifecycle methods--run
,
runNestedSuites
, runTests
, and runTest
--that users can override to customize
the framework. If a "run" lifecycle methods completes abruptly with an exception, that exception occurs outside
the context of a test body. As a result, such exceptions will be
installed as an unreportedException
of the relevant Status
.
The toFuture
method on Status
returns a Future[Boolean]
. If the Future
succeeds with the Boolean
value of true
, that indicates no tests failed and no suites aborted
during the activity represented
by this Status
. If a test failed or suite aborted, and that event was reported by a fired ScalaTest
Event
, the
Future
will succeed with the value false
. If an unreported exception has been installed
on the Status
, however, the Future
will fail with that exception.
a optional unreported Throwable
Registers a by-name function (producing an optional exception) to execute
after this Status
completes.
Registers a by-name function (producing an optional exception) to execute
after this Status
completes.
If the by-name function passed to this method completes abruptly with a non-run-aborting exception,
that exception will be caught and installed as the unreportedException
on the
Status
returned by this method. The Status
returned by this method
will then complete. The thread that attempted to evaluate the by-name function will be allowed
to continue (i.e.
, the non-run-aborting exception will not be rethrown
on that thread).
If the by-name function passed to this method completes abruptly with a run-aborting exception,
such as StackOverflowError
, that exception will be caught and a new
java.util.concurrent.ExecutionException
that contains the run-aborting exception as its
cause will be installed as the unreportedException
on the
Status
returned by this method. The Status
returned by this method
will then complete. The original run-aborting exception will then be rethrown on the
thread that attempted to evaluate the by-name function.
If an unreported exception is installed on this Status
, the passed by-name function will
not be executed. Instead, the same unreported exception will be installed on the Status
returned by this method.
Internally, ScalaTest uses this method in traits BeforeAndAfter
,
BeforeAndAfterEach
, and BeforeAndAfterEachTestData
to ensure "after" code is
executed after the relevant test has completed, and in traits BeforeAndAfterAll
and
BeforeAndAfterAllConfigMap
to ensure "after" code is executed after the
relevant tests and nested suites have completed.
A by-name function to invoke after this Status
has completed.
a Status
that represents this Status
,
modified by any exception thrown by the passed by-name function.
The result status of running a test or a suite, which is used to support parallel and asynchronous execution of tests.
This trait is the result type of the "run" lifecycle methods of trait
Suite
:run
,runNestedSuites
,runTests
, andrunTest
. It can be used to determine whether a test or suite has completed, and if so, whether it succeeded, and if not, whether an exception was thrown that was not yet reported via a ScalaTest event. AStatus
is like a domain-specificFuture[Boolean]
, where:Success(true)
TestFailedException
) is represented bySuccess(false)
Failure(unreportedException)
Note that pending and canceled tests will not cause a
Status
to fail. Only failed tests and aborted suites will cause aStatus
to fail.One use case of
Status
is to ensure that "after" code (such as anafterEach
orafterAll
method) does not execute until after the relevant entity (one test, one suite, or all of a suite's tests or nested suites) has completed. Another use case is to implement the default behavior of asynchronous styles, in which subsequent each test does not begin execution until after the previous test has completed.