Executes the passed function, enforcing the passed time limit by attempting to interrupt the function if the
time limit is exceeded, and throwing TestCanceledException
if the time limit has been
exceeded after the function completes.
Executes the passed function, enforcing the passed time limit by attempting to interrupt the function if the
time limit is exceeded, and throwing TestCanceledException
if the time limit has been
exceeded after the function completes.
If the function completes before the timeout expires:
If the function completes after the timeout expires:
TestCanceledException
.TestCanceledException
that includes the exception thrown by the function as its cause.If the interrupted status of the main test thread (the thread that invoked cancelAfter
) was not invoked
when cancelAfter
was invoked, but is set after the operation times out, it is reset by this method before
it completes abruptly with a TestCanceledException
. The interrupted status will be set by
ThreadInterruptor
, the default Interruptor
implementation.
the maximimum amount of time allowed for the passed operation
the operation on which to enforce the passed timeout
a strategy for interrupting the passed operation
Implicit Interruptor
value defining a default interruption strategy for the failAfter
and cancelAfter
method.
Implicit Interruptor
value defining a default interruption strategy for the failAfter
and cancelAfter
method.
To change the default Interruptor
configuration, override or hide this val
with another implicit
Interruptor
.
Executes the passed function, enforcing the passed time limit by attempting to interrupt the function if the
time limit is exceeded, and throwing TestFailedDueToTimeoutException
if the time limit has been
exceeded after the function completes.
Executes the passed function, enforcing the passed time limit by attempting to interrupt the function if the
time limit is exceeded, and throwing TestFailedDueToTimeoutException
if the time limit has been
exceeded after the function completes.
If the function completes before the timeout expires:
If the function completes after the timeout expires:
TestFailedDueToTimeoutException
.TestFailedDueToTimeoutException
that includes the exception thrown by the function as its cause.If the interrupted status of the main test thread (the thread that invoked failAfter
) was not invoked
when failAfter
was invoked, but is set after the operation times out, it is reset by this method before
it completes abruptly with a TestFailedDueToTimeoutException
. The interrupted status will be set by
ThreadInterruptor
, the default Interruptor
implementation.
the maximimum amount of time allowed for the passed operation
the operation on which to enforce the passed timeout
a strategy for interrupting the passed operation
This trait has been deprecated and will be removed in a later version of ScalaTest. Please use trait TimeLimits instead.
TimeLimits
differs fromTimeouts
in two ways. First, its behavior is driven by aTimed
typeclass, so that it can treatFuture
s (andFutureOutcome
s) differently than non-Future
s. Second, whereTimeouts
failAfter
andcancelAfter
take an implicitInterruptor
strategy, the corresponding methods inTimeLimits
take an implicitSignaler
strategy. Although theSignaler
hierarchy corresponds exactly to theInterruptor
hierarchy, the default is different. ForTimeouts
, the default isThreadInterruptor
; ForSignaler
, the default isDoNotSignal
.Trait that provides a
failAfter
andcancelAfter
construct, which allows you to specify a time limit for an operation passed as a by-name parameter, as well as a way to interrupt it if the operation exceeds its time limit.The time limit is passed as the first parameter, as a
Span
. The operation is passed as the second parameter. And anInterruptor
, a strategy for interrupting the operation, is passed as an implicit third parameter. Here's a simple example of its use:The above code, after 100 milliseconds, will produce a
TestFailedDueToTimeoutException
with a message that indicates a timeout expired:The code passed to failAfter did not complete within 100 milliseconds.
If you use
cancelAfter
in place offailAfter
, aTestCanceledException
with a message that indicates a timeout expired:The code passed to cancelAfter did not complete within 100 milliseconds.
If you prefer you can mix in or import the members of
SpanSugar
and place a units value after the integer timeout. Here are some examples:The code passed via the by-name parameter to
failAfter
orcancelAfter
will be executed by the thread that invokedfailAfter
orcancelAfter
, so that no synchronization is necessary to access variables declared outside the by-name.The
failAfter
orcancelAfter
method will create a timer that runs on a different thread than the thread that invokedfailAfter
orcancelAfter
, so that it can detect when the timeout has expired and attempt to interrupt the main thread. Because different operations can require different interruption strategies, thefailAfter
orcancelAfter
method accepts an implicit third parameter of typeInterruptor
that is responsible for interrupting the main thread.Configuring
failAfter
orcancelAfter
with anInterruptor
This trait declares an implicit
val
nameddefaultInterruptor
, initialized with aThreadInterruptor
, which attempts to interrupt the main thread by invokingThread.interrupt
. If you wish to use a different strategy, you can override thisval
(or hide it, for example if you imported the members ofTimeouts
rather than mixing it in). Here's an example in which the default interruption method is changed toDoNotInterrupt
, which does not attempt to interrupt the main thread in any way:As with the default
Interruptor
, the above code will eventually produce aTestFailedDueToTimeoutException
with a message that indicates a timeout expired. However, instead of throwing the exception after approximately 100 milliseconds, it will throw it after approximately 500 milliseconds.This illustrates an important feature of
failAfter
andcancelAfter
: it will throw aTestFailedDueToTimeoutException
(orTestCanceledException
in case ofcancelAfter
) if the code passed as the by-name parameter takes longer than the specified timeout to execute, even if it is allowed to run to completion beyond the specified timeout and returns normally.ScalaTest provides the following
Interruptor
implementations:Interruptor
implementationinterrupt
on the main test thread. This will set the interrupted status for the main test thread and, if the main thread is blocked, will in some cases cause the main thread to complete abruptly with anInterruptedException
.wakeup
on the passedjava.nio.channels.Selector
, which will cause the main thread, if blocked inSelector.select
, to complete abruptly with aClosedSelectorException
.close
on thejava.io.Socket
, which will cause the main thread, if blocked in a read or write of anjava.io.InputStream
orjava.io.OutputStream
that uses theSocket
, to complete abruptly with aSocketException
.You may wish to create your own
Interruptor
in some situations. For example, if your operation is performing a loop and can check a volatile flag each pass through the loop. You could in that case write anInterruptor
that sets that flag so that the next time around, the loop would exit.Please use org.scalatest.concurrent.TimeLimits instead