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>))
Throwable
- Good(Failed(<the exception>))
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
.
a transformation function to execute if and when this FutureOutcome
completes with an Outcome
an execution context that provides a strategy for executing the transformation function
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.
Indicates whether this FutureOutcome
has completed.
Indicates whether this FutureOutcome
has completed.
This method does not block.
true
if this FutureOutcome
has completed; false
otherwise.
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>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute if and when this FutureOutcome
completes with an abort.
an execution context that provides a strategy for executing the callback function
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:
TestPendingException
- Good(Pending)
TestCanceledException
- Good(Canceled(<the exception>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute if and when this FutureOutcome
completes with Canceled
an execution context that provides a strategy for executing the callback function
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:
TestPendingException
- Good(Pending)
TestCanceledException
- Good(Canceled(<the exception>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute when this FutureOutcome
completes
an execution context that provides a strategy for executing the callback function
a new FutureOutcome
that will complete only after this FutureOutcome
and, subsequently, the passed callback function have completed 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.
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>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute if and when this FutureOutcome
completes with Failed
an execution context that provides a strategy for executing the callback function
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:
TestPendingException
- Good(Pending)
TestCanceledException
- Good(Canceled(<the exception>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute if and when this FutureOutcome
completes with an Outcome
(i.e., not an abort)
an execution context that provides a strategy for executing the callback function
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:
TestPendingException
- Good(Pending)
TestCanceledException
- Good(Canceled(<the exception>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute if and when this FutureOutcome
completes with Pending
an execution context that provides a strategy for executing the callback function
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:
TestPendingException
- Good(Pending)
TestCanceledException
- Good(Canceled(<the exception>))
Throwable
- Good(Failed(<the exception>))
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
.
a side-effecting function to execute if and when this FutureOutcome
completes with Succeeded
an execution context that provides a strategy for executing the callback function
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.
Converts this FutureOutcome
to a Future[Outcome]
.
Converts this FutureOutcome
to a Future[Outcome]
.
the underlying Future[Outcome]
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
.
a Some
containing an Or
value that indicates the result of this
FutureOutcome
if it has completed; None
otherwise.
Wrapper class for
Future[Outcome]
that presents a more convenient API for manipulation inwithFixture
methods in async styles.This type serves as the result type of both test functions and
withFixture
methods in ScalaTest's async styles. AFuture[Outcome]
is not used as this result type for two reasons. First,Outcome
treats exceptions specially, and as a result methods onFuture
would usually not yield the desiredFuture[Outcome]
result. Only run-aborting exceptions should result in a failedFuture[Outcome]
. Any other thrown exception other thanTestCanceledException
orTestPendingException
should result in a successfulFuture
containing aorg.scalatest.Failed
. A thrownTestCanceledException
should result in a successfulFuture
containing anorg.scalatest.Canceled
; A thrownTestPendingException
should result in a successfulFuture
containing aorg.scalatest.Pending
. If manipulating aFuture[Outcome]
directly, by contrast, any thrown exception would result in a failedFuture
.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, soFutureOutcome
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 likescala.util.Success(org.scalatest.Failed)
. For this purpose aorg.scalactic.Or
is used instead of ascala.util.Try
to describe results ofFutureOutcome
.A
FutureOutcome
represents a computation that can result in anOutcome
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 ofFailed
,Canceled
, orPending
.The methods of
FutureOutcome
include the following callback registration methods:onSucceededThen
- registers a callback to be executed if the future outcome isSucceeded
.onFailedThen
- registers a callback to be executed if the future outcome isFailed
.onCanceledThen
- registers a callback to be executed if the future outcome isCanceled
.onPendingThen
- registers a callback to be executed if the future outcome isPending
.onOutcomeThen
- registers a callback to be executed if the future outcome is actually anOutcome
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 anOutcome
into a differentOutcome
asynchronously, use thechange
registration method, which takes a function fromOutcome
toOutcome
. The other methods onFutureOutcome
,isCompleted
andvalue
, allow you to poll aFutureOutcome
. None of the methods onFutureOutcome
block. Lastly, because an implicitFuturistic
instance is provided forFutureOutcome
, you can usecomplete
-lastly
syntax withFutureOutcome
.