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-SucceededOutcome: 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.
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:
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
Attributes
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.
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:
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
Attributes
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.
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:
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
Attributes
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.
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:
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:
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
Attributes
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.
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:
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
Attributes
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.
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:
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
Attributes
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.
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:
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
Attributes
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.
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.
Attributes
Returns
a Some containing an Or value that indicates the result of this FutureOutcome if it has completed; None otherwise.