scalatestCoreDotty/org.scalatest/FutureOutcome

FutureOutcome

class FutureOutcome(val underlying: Future[Outcome])

Wrapper class for Future[Outcome] that presents a more convenient API for manipulation in withFixture methods in async styles.

This type serves as the result type of both test functions and withFixture methods in ScalaTest's async styles. A Future[Outcome] is not used as this result type for two reasons. First, Outcome treats exceptions specially, and as a result methods on Future would usually not yield the desired Future[Outcome] result. Only run-aborting exceptions should result in a failed Future[Outcome]. Any other thrown exception other than TestCanceledException or TestPendingException should result in a successfulFuture containing a org.scalatest.Failed. A thrown TestCanceledException should result in a successful Future containing an org.scalatest.Canceled; A thrown TestPendingException should result in a successful Future containing a org.scalatest.Pending. If manipulating a Future[Outcome] directly, by contrast, any thrown exception would result in a failed Future.

Additionally, to be consistent with corresponding transformations in traditional testing styles, methods registering callbacks should return a new future outcome that doesn't complete until both the original future outcome has completed and the subsequent callback has completed execution. Additionally, if the callback itself throws an exception, that exception should determine the result of the future outcome returned by the callback registration method. This behavior is rather inconvenient to obtain on the current Future API, so FutureOutcome provides well-named methods that have this behavior.

Lastly, the FutureOutcome is intended to help prevent confusion by eliminating the need to work with types like scala.util.Success(org.scalatest.Failed). For this purpose a org.scalactic.Or is used instead of a scala.util.Try to describe results of FutureOutcome.

A FutureOutcome represents a computation that can result in an Outcome or an "abort." An abort means that a run-aborting exception occurred during the computation. Any other, non-run-aborting exception will be represented as an non-Succeeded Outcome: one of Failed, Canceled, or Pending.

The methods of FutureOutcome include the following callback registration methods:

  • onSucceededThen - registers a callback to be executed if the future outcome is Succeeded.

  • onFailedThen - registers a callback to be executed if the future outcome is Failed.

  • onCanceledThen - registers a callback to be executed if the future outcome is Canceled.

  • onPendingThen - registers a callback to be executed if the future outcome is Pending.

  • onOutcomeThen - registers a callback to be executed if the future outcome is actually an Outcome and not an abort.

  • onAbortedThen - registers a callback to be executed if the future outcome aborts.

  • onCompletedThen - registers a callback to be executed upon completion no matter how the future outcome completes.

The callback methods listed previously can be used to perform a side effect once a FutureOutcome completes. To change an Outcome into a different Outcome asynchronously, use the change registration method, which takes a function from Outcome to Outcome. The other methods on FutureOutcome, isCompleted and value, allow you to poll a FutureOutcome. None of the methods on FutureOutcome block. Lastly, because an implicit Futuristic instance is provided for FutureOutcome, you can use complete-lastly syntax with FutureOutcome.

Companion:
object
class Object
trait Matchable
class Any

Value members

Concrete methods

def change(f: Outcome => Outcome)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a transformation function to be executed if this future completes with any Outcome (i.e., no run-aborting exception is thrown), returning a new FutureOutcome representing the result of passing this FutureOutcome's Outcome result to the given transformation function.

Registers a transformation function to be executed if this future completes with any Outcome (i.e., no run-aborting exception is thrown), returning a new FutureOutcome representing the result of passing this FutureOutcome's Outcome result to the given transformation function.

If the passed function completes abruptly with an exception, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
executionContext

an execution context that provides a strategy for executing the transformation function

f

a transformation function to execute if and when this FutureOutcome completes with an Outcome

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with a valid Outcome, the passed callback function has completed execution.

def isCompleted: Boolean

Indicates whether this FutureOutcome has completed.

Indicates whether this FutureOutcome has completed.

This method does not block.

Returns:

true if this FutureOutcome has completed; false otherwise.

def onAbortedThen(callback: Throwable => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed if this future completes because a run-aborting exception was thrown, returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed if this future completes because a run-aborting exception was thrown, returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute if and when this FutureOutcome completes with an abort.

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes abnormally with a run-aborting exception, the passed callback function has completed execution.

def onCanceledThen(callback: TestCanceledException => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed if this future completes with Canceled, returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed if this future completes with Canceled, returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute if and when this FutureOutcome completes with Canceled

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Canceled, the passed callback function has completed execution.

def onCompletedThen(callback: Or[Outcome, Throwable] => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed after this future completes, returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed after this future completes, returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute when this FutureOutcome completes

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome and, subsequently, the passed callback function have completed execution.

def onFailedThen(callback: Throwable => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed if this future completes with Failed, returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed if this future completes with Failed, returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute if and when this FutureOutcome completes with Failed

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Failed, the passed callback function has completed execution.

def onOutcomeThen(callback: Outcome => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed if this future completes with any Outcome (i.e., no run-aborting exception is thrown), returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed if this future completes with any Outcome (i.e., no run-aborting exception is thrown), returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute if and when this FutureOutcome completes with an Outcome (i.e., not an abort)

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with a valid Outcome, the passed callback function has completed execution.

def onPendingThen(callback: => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed if this future completes with Pending, returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed if this future completes with Pending, returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute if and when this FutureOutcome completes with Pending

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Pending, the passed callback function has completed execution.

def onSucceededThen(callback: => Unit)(implicit executionContext: ExecutionContext): FutureOutcome

Registers a callback function to be executed if this future completes with Succeeded, returning a new future that completes only after the callback has finished execution.

Registers a callback function to be executed if this future completes with Succeeded, returning a new future that completes only after the callback has finished execution.

The resulting FutureOutcome will have the same result as this FutureOutcome, unless the callback completes abruptly with an exception. In that case, the resulting FutureOutcome will be determined by the type of the thrown exception:

  • TestPendingException - Good(Pending)

  • TestCanceledException - Good(Canceled(<the exception>))

  • Any non-run-aborting Throwable - Good(Failed(<the exception>))

  • A run-aborting Throwable - Bad(<the run-aborting exception>)

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Value parameters:
callback

a side-effecting function to execute if and when this FutureOutcome completes with Succeeded

executionContext

an execution context that provides a strategy for executing the callback function

Returns:

a new FutureOutcome that will complete only after this FutureOutcome has completed and, if this FutureOutcome completes with Succeeded, the passed callback function has completed execution.

def toFuture: Future[Outcome]

Converts this FutureOutcome to a Future[Outcome].

Converts this FutureOutcome to a Future[Outcome].

Returns:

the underlying Future[Outcome]

def value: Option[Or[Outcome, Throwable]]

Returns a value that indicates whether this FutureOutcome has completed, and if so, indicates its result.

Returns a value that indicates whether this FutureOutcome has completed, and if so, indicates its result.

If this FutureOutcome has not yet completed, this method will return None. Otherwise, this method will return a Some that contains either a Good[Outcome], if this FutureOutcome completed with a valid Outcome result, or if it completed with a thrown run-aborting exception, a Bad[Throwable].

For more information on run-aborting exceptions, see the Run-aborting exceptions section in the main Scaladoc for trait Suite.

Returns:

a Some containing an Or value that indicates the result of this FutureOutcome if it has completed; None otherwise.