Packages

sealed trait Status extends AnyRef

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, and runTest. 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. A Status is like a domain-specific Future[Boolean], where:

  • an activity in which no test failed and no suite aborted is represented by Success(true)
  • an activity during which at least one test failed or one suite aborted, but all exceptions that occured were reported by a ScalaTest events (such as TestFailedException) is represented by Success(false)
  • an activity during which at least one test failed or one suite aborted and at least one exception occurred that was not reported via a ScalaTest event is represented by Failure(unreportedException)

Note that pending and canceled tests will not cause a Status to fail. Only failed tests and aborted suites will cause a Status to fail.

One use case of Status is to ensure that "after" code (such as an afterEach or afterAll 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.

Self Type
Status
Source
Status.scala
Linear Supertypes
AnyRef, Any
Known Subclasses
CompositeStatus, FailedStatus, StatefulStatus, SucceededStatus
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Status
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def isCompleted: Boolean

    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.

    returns

    true if the test or suite run is already completed, false otherwise.

  2. abstract def succeeds(): Boolean

    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.

    returns

    after waiting until completion, true if no tests failed and no suites aborted, false otherwise

    Exceptions thrown

    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.

  3. abstract def waitUntilCompleted(): Unit

    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.

    Exceptions thrown

    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.

  4. abstract def whenCompleted(callback: (Try[Boolean]) ⇒ Unit): Unit

    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.

    callback

    the callback function to execute once this Status has completed

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  6. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  7. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  8. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  9. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
  10. def hashCode(): Int
    Definition Classes
    AnyRef → Any
  11. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  12. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  13. final def notify(): Unit
    Definition Classes
    AnyRef
  14. final def notifyAll(): Unit
    Definition Classes
    AnyRef
  15. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  16. final def thenRun(f: ⇒ Status): Status

    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.

    returns

    a Status that represents the status of executing the by-name function passed to this method.

  17. final def toFuture: Future[Boolean]

    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.

    returns

    a Future[Boolean] representing this Status.

  18. def toString(): String
    Definition Classes
    AnyRef → Any
  19. def unreportedException: Option[Throwable]

    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.Errors.

    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.

    returns

    a optional unreported Throwable

  20. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  21. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  22. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  23. final def withAfterEffect(f: ⇒ Unit): Status

    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.

    f

    A by-name function to invoke after this Status has completed.

    returns

    a Status that represents this Status, modified by any exception thrown by the passed by-name function.

Inherited from AnyRef

Inherited from Any

Ungrouped