Trait that defines an abstract patienceConfig
method that is implemented in PatienceConfiguration
and can
be overriden in stackable modification traits such as IntegrationPatience
.
Trait that defines an abstract patienceConfig
method that is implemented in PatienceConfiguration
and can
be overriden in stackable modification traits such as IntegrationPatience
.
The main purpose of AbstractPatienceConfiguration
is to differentiate core PatienceConfiguration
traits, such as Eventually
and Waiters
, from stackable
modification traits for PatienceConfiguration
s such as IntegrationPatience
.
Because these stackable traits extend AbstractPatienceConfiguration
instead of Suite
, you can't simply mix in a stackable trait:
class ExampleSpec extends FunSpec with IntegrationPatience // Won't compile
The previous code is undesirable because IntegrationPatience
would have no affect on the class. Instead, you need to mix
in a core PatienceConfiguration
trait and mix the stackable IntegrationPatience
trait
into that, like this:
class ExampleSpec extends FunSpec with Eventually with IntegrationPatience // Compiles fine
The previous code is better because IntegrationPatience
does have an effect: it modifies the behavior
of Eventually
.
Trait that facilitates testing with futures.
Trait that facilitates testing with futures.
This trait defines a FutureConcept
trait that can be used to implicitly wrap
different kinds of futures, thereby providing a uniform testing API for futures.
The three ways this trait enables you to test futures are:
1. Invoking isReadyWithin
, to assert that a future is ready within a a specified time period.
Here's an example:
assert(result.isReadyWithin(100 millis))
2. Invoking futureValue
, to obtain a futures result within a specified or implicit time period,
like this:
assert(result.futureValue === 7) // Or, if you expect the future to fail: assert(result.failed.futureValue.isInstanceOf[ArithmeticException])
3. Passing the future to whenReady
, and performing assertions on the result value passed
to the given function, as in:
whenReady(result) { s => s should be ("hello") }
The whenReady
construct periodically inspects the passed
future, until it is either ready or the configured timeout has been surpassed. If the future becomes
ready before the timeout, whenReady
passes the future's value to the specified function.
To make whenReady
more broadly applicable, the type of future it accepts is a FutureConcept[T]
,
where T
is the type of value promised by the future. Passing a future to whenReady
requires
an implicit conversion from the type of future you wish to pass (the modeled type) to
FutureConcept[T]
. Subtrait JavaFutures
provides an implicit conversion from
java.util.concurrent.Future[T]
to FutureConcept[T]
.
For example, the following invocation of whenReady
would succeed (not throw an exception):
import org.scalatest._ import Matchers._ import concurrent.Futures._ import java.util.concurrent._ val exec = Executors.newSingleThreadExecutor val task = new Callable[String] { def call() = { Thread.sleep(50); "hi" } } whenReady(exec.submit(task)) { s => s should be ("hi") }
However, because the default timeout is 150 milliseconds, the following invocation of
whenReady
would ultimately produce a TestFailedException
:
val task = new Callable[String] { def call() = { Thread.sleep(500); "hi" } } whenReady(exec.submit(task)) { s => s should be ("hi") }
Assuming the default configuration parameters, a timeout
of 150 milliseconds and an
interval
of 15 milliseconds,
were passed implicitly to whenReady
, the detail message of the thrown
TestFailedException
would look like:
The future passed to whenReady was never ready, so whenReady timed out. Queried 95 times, sleeping 10 milliseconds between each query.
whenReady
The whenReady
methods of this trait can be flexibly configured.
The two configuration parameters for whenReady
along with their
default values and meanings are described in the following table:
Configuration Parameter | Default Value | Meaning |
---|---|---|
timeout | scaled(150 milliseconds) |
the maximum amount of time to allow unsuccessful queries before giving up and throwing TestFailedException
|
interval | scaled(15 milliseconds) | the amount of time to sleep between each query |
The default values of both timeout and interval are passed to the scaled
method, inherited
from ScaledTimeSpans
, so that the defaults can be scaled up
or down together with other scaled time spans. See the documentation for trait ScaledTimeSpans
for more information.
The whenReady
methods of trait Futures
each take a PatienceConfig
object as an implicit parameter. This object provides values for the two configuration parameters. Trait
Futures
provides an implicit val
named defaultPatience
with each
configuration parameter set to its default value.
If you want to set one or more configuration parameters to a different value for all invocations of
whenReady
in a suite you can override this
val (or hide it, for example, if you are importing the members of the Futures
companion object rather
than mixing in the trait). For example, if
you always want the default timeout
to be 2 seconds and the default interval
to be 5 milliseconds, you
can override defaultPatience
, like this:
implicit override val defaultPatience = PatienceConfig(timeout = Span(2, Seconds), interval = Span(5, Millis))
Or, hide it by declaring a variable of the same name in whatever scope you want the changed values to be in effect:
implicit val defaultPatience = PatienceConfig(timeout = Span(2, Seconds), interval = Span(5, Millis))
In addition to taking a PatienceConfig
object as an implicit parameter, the whenReady
methods of trait
Futures
include overloaded forms that take one or two PatienceConfigParam
objects that you can use to override the values provided by the implicit PatienceConfig
for a single whenReady
invocation. For example, if you want to set timeout
to 6 seconds for just one particular whenReady
invocation,
you can do so like this:
whenReady (exec.submit(task), timeout(Span(6, Seconds))) { s => s should be ("hi") }
This invocation of eventually
will use 6000 for timeout
and whatever value is specified by the
implicitly passed PatienceConfig
object for the interval
configuration parameter.
If you want to set both configuration parameters in this way, just list them separated by commas:
whenReady (exec.submit(task), timeout(Span(6, Seconds)), interval(Span(500, Millis))) { s => s should be ("hi") }
You can also import or mix in the members of SpanSugar
if
you want a more concise DSL for expressing time spans:
whenReady (exec.submit(task), timeout(6 seconds), interval(500 millis)) { s => s should be ("hi") }
Note: The whenReady
construct was in part inspired by the whenDelivered
matcher of the
BlueEyes project, a lightweight, asynchronous web framework for Scala.
Stackable modification trait for PatienceConfiguration
that provides default timeout and interval
values appropriate for integration testing.
Stackable modification trait for PatienceConfiguration
that provides default timeout and interval
values appropriate for integration testing.
The default values for the parameters are:
Configuration Parameter | Default Value |
---|---|
timeout
|
scaled(15 seconds)
|
interval
|
scaled(150 milliseconds)
|
The default values of both timeout and interval are passed to the scaled
method, inherited
from ScaledTimeSpans
, so that the defaults can be scaled up
or down together with other scaled time spans. See the documentation for trait ScaledTimeSpans
for more information.
Mix this trait into any class that uses PatienceConfiguration
(such as classes that mix in Eventually
or Waiters
) to get timeouts tuned towards integration testing, like this:
class ExampleSpec extends FeatureSpec with Eventually with IntegrationPatience { // ... }
Trait providing methods and classes used to configure timeouts and, where relevant, the interval between retries.
Trait providing methods and classes used to configure timeouts and, where relevant, the interval between retries.
This trait is called PatienceConfiguration
because it allows configuration of two
values related to patience: The timeout specifies how much time asynchronous operations will be given
to succeed before giving up. The interval specifies how much time to wait between checks to determine
success when polling.
The default values for timeout and interval provided by trait PatienceConfiguration
are tuned for unit testing,
where running tests as fast as
possible is a high priority and subsystems requiring asynchronous operations are therefore often replaced
by mocks. This table shows the default values:
Configuration Parameter | Default Value |
---|---|
timeout
|
scaled(150 milliseconds)
|
interval
|
scaled(15 milliseconds)
|
Values more appropriate to integration testing, where asynchronous operations tend to take longer because the tests are run
against the actual subsytems (not mocks), can be obtained by mixing in trait IntegrationPatience
.
The default values of both timeout and interval are passed to the scaled
method, inherited
from ScaledTimeSpans
, so that the defaults can be scaled up
or down together with other scaled time spans. See the documentation for trait ScaledTimeSpans
for more information.
Timeouts are used by the eventually
methods of trait
Eventually
and the await
method of class
Waiter
, a member of trait
Waiters
. Intervals are used by
the eventually
methods.
Provides an implicit conversion from scala.concurrent.Future[T]
to
FutureConcept[T]
.
Provides an implicit conversion from scala.concurrent.Future[T]
to
FutureConcept[T]
.
This trait enables you to invoke the methods defined on FutureConcept
on a Scala Future
, as well as to pass a Scala future
to the whenReady
methods of supertrait Futures
.
The three ways this trait enables you to test futures are:
1. Invoking isReadyWithin
, to assert that a future is ready within a a specified time period.
Here's an example:
assert(result.isReadyWithin(100 millis))
2. Invoking futureValue
, to obtain a futures result within a specified or implicit time period,
like this:
assert(result.futureValue === 7) // Or, if you expect the future to fail: assert(result.failed.futureValue.isInstanceOf[ArithmeticException])
3. Passing the future to whenReady
, and performing assertions on the result value passed
to the given function, as in:
whenReady(result) { s => s should be ("hello") }
The whenReady
construct periodically inspects the passed
future, until it is either ready or the configured timeout has been surpassed. If the future becomes
ready before the timeout, whenReady
passes the future's value to the specified function.
To make whenReady
more broadly applicable, the type of future it accepts is a FutureConcept[T]
,
where T
is the type of value promised by the future. Passing a future to whenReady
requires
an implicit conversion from the type of future you wish to pass (the modeled type) to
FutureConcept[T]
. Subtrait JavaFutures
provides an implicit conversion from
java.util.concurrent.Future[T]
to FutureConcept[T]
.
For example, the following invocation of whenReady
would succeed (not throw an exception):
import org.scalatest._ import Matchers._ import concurrent.Futures._ import java.util.concurrent._ val exec = Executors.newSingleThreadExecutor val task = new Callable[String] { def call() = { Thread.sleep(50); "hi" } } whenReady(exec.submit(task)) { s => s should be ("hi") }
However, because the default timeout is 150 milliseconds, the following invocation of
whenReady
would ultimately produce a TestFailedException
:
val task = new Callable[String] { def call() = { Thread.sleep(500); "hi" } } whenReady(exec.submit(task)) { s => s should be ("hi") }
Assuming the default configuration parameters, a timeout
of 150 milliseconds and an
interval
of 15 milliseconds,
were passed implicitly to whenReady
, the detail message of the thrown
TestFailedException
would look like:
The future passed to whenReady was never ready, so whenReady timed out. Queried 95 times, sleeping 10 milliseconds between each query.
whenReady
The whenReady
methods of this trait can be flexibly configured.
The two configuration parameters for whenReady
along with their
default values and meanings are described in the following table:
Configuration Parameter | Default Value | Meaning |
---|---|---|
timeout | scaled(150 milliseconds) |
the maximum amount of time to allow unsuccessful queries before giving up and throwing TestFailedException
|
interval | scaled(15 milliseconds) | the amount of time to sleep between each query |
The default values of both timeout and interval are passed to the scaled
method, inherited
from ScaledTimeSpans
, so that the defaults can be scaled up
or down together with other scaled time spans. See the documentation for trait ScaledTimeSpans
for more information.
The whenReady
methods of trait Futures
each take a PatienceConfig
object as an implicit parameter. This object provides values for the two configuration parameters. Trait
Futures
provides an implicit val
named defaultPatience
with each
configuration parameter set to its default value.
If you want to set one or more configuration parameters to a different value for all invocations of
whenReady
in a suite you can override this
val (or hide it, for example, if you are importing the members of the Futures
companion object rather
than mixing in the trait). For example, if
you always want the default timeout
to be 2 seconds and the default interval
to be 5 milliseconds, you
can override defaultPatience
, like this:
implicit override val defaultPatience = PatienceConfig(timeout = Span(2, Seconds), interval = Span(5, Millis))
Or, hide it by declaring a variable of the same name in whatever scope you want the changed values to be in effect:
implicit val defaultPatience = PatienceConfig(timeout = Span(2, Seconds), interval = Span(5, Millis))
In addition to taking a PatienceConfig
object as an implicit parameter, the whenReady
methods of trait
Futures
include overloaded forms that take one or two PatienceConfigParam
objects that you can use to override the values provided by the implicit PatienceConfig
for a single whenReady
invocation. For example, if you want to set timeout
to 6 seconds for just one particular whenReady
invocation,
you can do so like this:
whenReady (exec.submit(task), timeout(Span(6, Seconds))) { s => s should be ("hi") }
This invocation of eventually
will use 6000 for timeout
and whatever value is specified by the
implicitly passed PatienceConfig
object for the interval
configuration parameter.
If you want to set both configuration parameters in this way, just list them separated by commas:
whenReady (exec.submit(task), timeout(Span(6, Seconds)), interval(Span(500, Millis))) { s => s should be ("hi") }
You can also import or mix in the members of SpanSugar
if
you want a more concise DSL for expressing time spans:
whenReady (exec.submit(task), timeout(6 seconds), interval(500 millis)) { s => s should be ("hi") }
Note: The whenReady
construct was in part inspired by the whenDelivered
matcher of the
BlueEyes project, a lightweight, asynchronous web framework for Scala.
Trait providing a scaled
method that can be used to scale time
Span
s used during the testing of asynchronous operations.
Trait providing a scaled
method that can be used to scale time
Span
s used during the testing of asynchronous operations.
The scaled
method allows tests of asynchronous operations to be tuned
according to need. For example, Span
s can be scaled larger when running
tests on slower continuous integration servers or smaller when running on faster
development machines.
The Double
factor by which to scale the Span
s passed to
scaled
is obtained from the spanScaleFactor
method, also declared
in this trait. By default this method returns 1.0, but can be configured to return
a different value by passing a -F
argument to Runner
(or
an equivalent mechanism in an ant, sbt, or Maven build file).
The default timeouts and intervals defined for traits Eventually
and
Waiters
invoke scaled
, so those defaults
will be scaled automatically. Other than such defaults, however, to get a Span
to scale you'll need to explicitly pass it to scaled
.
For example, here's how you would scale a Span
you supply to
the failAfter
method from trait Timeouts
:
failAfter(scaled(150 millis)) { // ... }
The reason Span
s are not scaled automatically in the general case is
to make code obvious. If a reader sees failAfter(1 second)
, it will
mean exactly that: fail after one second. And if a Span
will be scaled,
the reader will clearly see that as well: failAfter(scaled(1 second))
.
spanScaleFactor
You can override the spanScaleFactor
method to configure the factor by a
different means. For example, to configure the factor from Akka
TestKit's test time factor you might create a trait like this:
import org.scalatest.concurrent.ScaledTimeSpans import akka.actor.ActorSystem import akka.testkit.TestKitExtension trait AkkaSpanScaleFactor extends ScaledTimeSpans { override def spanScaleFactor: Double = TestKitExtension.get(ActorSystem()).TestTimeFactor }
This trait overrides spanScaleFactor
so that it takes its
scale factor from Akka's application.conf
file.
You could then scale Span
s tenfold in Akka's configuration file
like this:
akka { test { timefactor = 10.0 } }
Armed with this trait and configuration file, you can simply mix trait
AkkaSpanScaleFactor
into any test class whose Span
s
you want to scale, like this:
class MySpec extends FunSpec with Eventually with AkkaSpanScaleFactor { // .. }
Strategy for interrupting an operation in which wakeup
is called on the java.nio.channels.Selector
passed to
the constructor.
Strategy for interrupting an operation in which wakeup
is called on the java.nio.channels.Selector
passed to
the constructor.
This class can be used for configuration when using traits Timeouts
and TimeLimitedTests
.
Strategy for interrupting an operation after a timeout expires.
Strategy for interrupting an operation after a timeout expires.
An instance of this trait is used for configuration when using traits
Timeouts
and TimeLimitedTests
.
Strategy for interrupting an operation in which close
is called on the java.net.Socket
passed to
the constructor.
Strategy for interrupting an operation in which close
is called on the java.net.Socket
passed to
the constructor.
This class can be used for configuration when using traits Timeouts
and TimeLimitedTests
.
Trait that when mixed into a suite class establishes a time limit for its tests.
Trait that when mixed into a suite class establishes a time limit for its tests.
This trait overrides withFixture
, wrapping a super.withFixture(test)
call
in a failAfter
invocation, specifying a timeout obtained by invoking timeLimit
and an Interruptor
by invoking defaultTestInterruptor
:
failAfter(timeLimit) { super.withFixture(test) } (defaultTestInterruptor)
Note that the failAfter
method executes the body of the by-name passed to it using the same
thread that invoked failAfter
. This means that the same thread will run the withFixture
method
as well as each test, so no extra synchronization is required. A second thread is used to run a timer, and if the timeout
expires, that second thread will attempt to interrupt the main test thread via the defaultTestInterruptor
.
The timeLimit
field is abstract in this trait. Thus you must specify a time limit when you use it.
For example, the following code specifies that each test must complete within 200 milliseconds:
import org.scalatest.FunSpec import org.scalatest.concurrent.TimeLimitedTests import org.scalatest.time.SpanSugar._ class ExampleSpec extends FunSpec with TimeLimitedTests { // Note: You may need to either write 200.millis or (200 millis), or // place a semicolon or blank line after plain old 200 millis, to // avoid the semicolon inference problems of postfix operator notation. val timeLimit = 200 millis describe("A time-limited test") { it("should succeed if it completes within the time limit") { Thread.sleep(100) } it("should fail if it is taking too darn long") { Thread.sleep(300) } } }
If you run the above ExampleSpec
, the second test will fail with the error message:
The test did not complete within the specified 200 millisecond time limit.
The failAfter
method uses an Interruptor
to attempt to interrupt the main test thread if the timeout
expires. The default Interruptor
returned by the defaultTestInterruptor
method is a
ThreadInterruptor
, which calls interrupt
on the main test thread. If you wish to change this
interruption strategy, override defaultTestInterruptor
to return a different Interruptor
. For example,
here's how you'd change the default to DoNotInterrupt
, a very patient interruption strategy that does nothing to
interrupt the main test thread:
import org.scalatest.FunSpec import org.scalatest.concurrent.TimeLimitedTests import org.scalatest.time.SpanSugar._ class ExampleSpec extends FunSpec with TimeLimitedTests { val timeLimit = 200 millis override val defaultTestInterruptor = DoNotInterrupt describe("A time-limited test") { it("should succeed if it completes within the time limit") { Thread.sleep(100) } it("should fail if it is taking too darn long") { Thread.sleep(300) } } }
Like the previous incarnation of ExampleSuite
, the second test will fail with an error message that indicates
a timeout expired. But whereas in the previous case, the Thread.sleep
would be interrupted after 200 milliseconds,
in this case it is never interrupted. In the previous case, the failed test requires a little over 200 milliseconds to run.
In this case, because the sleep(300)
is never interrupted, the failed test requires a little over 300 milliseconds
to run.
Trait that provides a failAfter
and cancelAfter
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.
Trait that provides a failAfter
and cancelAfter
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 an Signaler
, a strategy for interrupting the operation, is
passed as an implicit third parameter. Here's a simple example of its use:
failAfter(Span(100, Millis)) { Thread.sleep(200) }
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 of failAfter
, a TestCanceledException
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:
import org.scalatest.time.SpanSugar._ failAfter(100 millis) { Thread.sleep(200) } failAfter(1 second) { Thread.sleep(2000) }
The code passed via the by-name parameter to failAfter
or cancelAfter
will be executed by the thread that invoked
failAfter
or cancelAfter
, so that no synchronization is necessary to access variables declared outside the by-name.
var result = -1 // No need to make this volatile failAfter(100 millis) { result = accessNetService() } result should be (99)
The failAfter
or cancelAfter
method will create a timer that runs on a different thread than the thread that
invoked failAfter
or cancelAfter
, 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, the failAfter
or cancelAfter
method accepts an implicit third parameter of type Signaler
that is responsible for interrupting
the main thread.
failAfter
or cancelAfter
with an Signaler
This trait declares an implicit val
named defaultSignaler
,
initialized with a ThreadSignaler
, which attempts to interrupt the main thread by invoking
Thread.interrupt
. If you wish to use a different strategy, you can override this val
(or hide
it, for example if you imported the members of Timeouts
rather than mixing it in). Here's an example
in which the default interruption method is changed to DoNotInterrupt
, which does not attempt to
interrupt the main thread in any way:
override val defaultSignaler = DoNotInterrupt failAfter(100 millis) { Thread.sleep(500) }
As with the default Signaler
, the above code will eventually produce a
TestFailedDueToTimeoutException
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
and cancelAfter
: it will throw a
TestFailedDueToTimeoutException
(or TestCanceledException
in case of cancelAfter
)
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 Signaler
implementations:
Signaler implementation
|
Usage |
---|---|
ThreadSignaler |
The default interruptor, invokes interrupt 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
an InterruptedException .
|
DoNotInterrupt | Does not attempt to interrupt the main test thread in any way |
SelectorSignaler |
Invokes wakeup on the passed java.nio.channels.Selector , which
will cause the main thread, if blocked in Selector.select , to complete abruptly with a
ClosedSelectorException .
|
SocketSignaler |
Invokes close on the java.io.Socket , which
will cause the main thread, if blocked in a read or write of an java.io.InputStream or
java.io.OutputStream that uses the Socket , to complete abruptly with a
SocketException .
|
You may wish to create your own Signaler
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 an Signaler
that
sets that flag so that the next time around, the loop would exit.
Interruption strategy in which nothing is done to try and interrupt an operation.
Interruption strategy in which nothing is done to try and interrupt an operation.
This object can be used for configuration when using traits Timeouts
and TimeLimitedTests
.
Companion object that facilitates the importing of ScalaFutures
members as
an alternative to mixing in the trait.
Companion object that facilitates the importing of ScalaFutures
members as
an alternative to mixing in the trait. One use case is to import ScalaFutures
's members so you can use
them in the Scala interpreter.
Companion object that provides a factory method for a SelectorSignaler
.
Companion object that provides a factory method for a SelectorSignaler
.
Companion object that provides a factory method for an Interruptor
defined
in terms of a function from a function of type Thread
to Unit.
Companion object that provides a factory method for an Interruptor
defined
in terms of a function from a function of type Thread
to Unit.
Companion object that provides a factory method for a SocketSignaler
.
Companion object that provides a factory method for a SocketSignaler
.
Strategy for interrupting an operation in which interrupt
is called on the Thread
passed
to apply
.
Strategy for interrupting an operation in which interrupt
is called on the Thread
passed
to apply
.
This object can be used for configuration when using traits Timeouts
and TimeLimitedTests
.
Companion object that facilitates the importing of Timeouts
members as
an alternative to mixing in the trait.
Companion object that facilitates the importing of Timeouts
members as
an alternative to mixing in the trait. One use case is to import Timeouts
's members so you can use
them in the Scala interpreter.
ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.