fixture
Trait that when mixed into a fixture.AsyncTestSuite passes
the config map passed to runTest as a fixture into each test.
Trait that when mixed into a fixture.AsyncTestSuite passes
the config map passed to runTest as a fixture into each test.
Here's an example in which tests just check to make sure "hello" and "world"
are defined keys in the config map:
package org.scalatest.examples.fixture.configmapfixture
import org.scalatest._
class ExampleAsyncSpec extends fixture.AsyncFlatSpec with fixture.AsyncConfigMapFixture with Matchers {
"The config map" should "contain hello" in { configMap =>
// Use the configMap passed to runTest in the test
configMap should contain key "hello"
}
it should "contain world" in { configMap =>
configMap should contain key "world"
}
}
If you run this class without defining "hello" and "world"
in the confg map, the tests will fail:
scala> org.scalatest.run(new ExampleSpec) ExampleSpec: The config map - should contain hello *** FAILED *** Map() did not contain key "hello" (:20) - should contain world *** FAILED *** Map() did not contain key "world" ( :24)
If you do define "hello" and "world" keys
in the confg map, the tests will success:
scala> org.scalatest.run(new ExampleSpec, configMap = Map("hello" -> "hi", "world" -> "globe"))
ExampleSpec:
The config map
- should contain hello
- should contain world
Trait that when mixed into a fixture.AsyncTestSuite passes the
TestData passed to withFixture as a fixture into each test.
Trait that when mixed into a fixture.AsyncTestSuite passes the
TestData passed to withFixture as a fixture into each test.
For example, here's how you could access the test's name in each test using AsyncTestDataFixture:
package org.scalatest.examples.fixture.testdatafixture
import org.scalatest._
class ExampleAsyncSpec extends fixture.AsyncFlatSpec with fixture.AsyncTestDataFixture {
"Accessing the test data" should "be easy!" in { td =>
assert(td.name == "Accessing the test data should be easy!")
}
it should "be fun!" in { td =>
assert(td.name == "Accessing the test data should be fun!")
}
}
Trait declaring methods that can be used to register test functions that accept
a fixture parameter and have result type Future[Assertion].
Trait declaring methods that can be used to register test functions that accept
a fixture parameter and have result type Future[Assertion].
The base trait of ScalaTest's "fixture" async testing styles, which enable you to pass fixture objects into tests.
The base trait of ScalaTest's "fixture" async testing styles, which enable you to pass fixture objects into tests.
This trait provides a final override of withFixture(OneArgTest), declared in
supertrait fixture.Suite, because the withFixture(OneArgTest) lifecycle
method assumes synchronous testing. Here is its signature:
def withFixture(test: OneArgTest): Outcome
The test function interface, OneArgTest, offers an apply method
that takes a FixtureParam and returns Outcome:
// In trait OneArgTest: def apply(fixture: FixtureParam): Outcome
Because the result of a test is an Outcome, when the test function returns, the test body must have determined an outcome already. It
will already be one of Succeeded, Failed, Canceled, or Pending. This is
also true when withFixture(OneArgTest) returns: because the result type of withFixture(OneArgTest) is Outcome,
the test body has by definition has already finished execution.
This trait overrides and makes abstract the runTest method. Subtraits must
must implement this method to call withFixture(OneArgAsyncTest) instead of withFixture(OneArgTest),
where withFixture(OneArgAsyncTest) is a new method declared in this trait with the following
signature and implementation:
def withFixture(test: OneArgAsyncTest): FutureOutcome = {
test()
}
Instead of returning Outcome like withFixture, the withFixture method
returns a FutureOutcome. Similarly, the apply method of test function interface,
OneArgAsyncTest, returns FutureOutcome:
// In trait OneArgAsyncTest: def apply(fixture: FixtureParam): FutureOutcome
The withFixture method supports async testing, because when the test function returns,
the test body has not necessarily finished execution.
The recommended way to ensure cleanup is performed after a test body finishes execution is
to use the complete-lastly syntax, defined in supertrait
org.scalatest.CompleteLastly, which will ensure that
cleanup will occur whether future-producing code completes abruptly by throwing an exception, or returns
normally yielding a future. In the latter case, complete-lastly will register the cleanup code
to execute asynchronously when the future completes.
To enable the stacking of traits that define withFixture(NoArgAsyncTest), it is a good idea to let
withFixture(NoArgAsyncTest) invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgAsyncTest to a NoArgAsyncTest. You can do that by passing
the fixture object to the toNoArgAsyncTest method of OneArgAsyncTest. In other words, instead of
writing “test(theFixture)”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgAsyncTest) method of the same instance by writing:
withFixture(test.toNoArgAsyncTest(theFixture))
Thus, the recommended structure of a withFixture implementation that performs cleanup looks like this:
// Your implementation
override def withFixture(test: OneArgAsyncTest) = {
// Perform setup here
val theFixture = ...
complete {
withFixture(test.toNoArgAsyncTest(theFixture)) // Invoke the test function
} lastly {
// Perform cleanup here
}
}
If you have no cleanup to perform, you can write withFixture like this instead:
// Your implementation
override def withFixture(test: OneArgAsyncTest) = {
// Perform setup here
val theFixture = ...
withFixture(test.toNoArgAsyncTest(theFixture)) // Invoke the test function
}
If you want to perform an action only for certain outcomes, you'll need to
register code performing that action as a callback on the Future using
one of Future registration methods: onComplete, onSuccess,
or onFailure. Note that if a test fails, that will be treated as a
scala.util.Success(org.scalatest.Failure). So if you want to perform an
action if a test fails, for example, you'd register the callaback using onSuccess,
like this:
// Your implementation
override def withFixture(test: OneArgAsyncTest) = {
// Perform setup here
val theFixture = ...
val futureOutcome =
withFixture(test.toNoArgAsyncTest(theFixture)) // Invoke the test function
futureOutcome onFailedThen { _ =>
// perform action that you want to occur
// only if a test fails here
}
}
Lastly, if you want to transform the outcome in some way in withFixture, you'll need to use either the
map or transform methods of Future, like this:
// Your implementation
override def withFixture(test: OneArgAsyncTest) = {
// Perform setup here
val theFixture = ...
val futureOutcome =
withFixture(test.toNoArgAsyncTest(theFixture)) // Invoke the test function
futureOutcome change { outcome =>
// transform the outcome into a new outcome here
}
}
Note that a NoArgAsyncTest's apply method will only return a Failure if
the test completes abruptly with an exception (such as OutOfMemoryError) that should
cause the suite to abort rather than the test to fail. Thus usually you would use map
to transform future outcomes, not transform, so that such suite-aborting exceptions pass through
unchanged. The suite will abort asynchronously with any exception returned in a Failure.
Trait that when mixed into a fixture.Suite passes
the config map passed to runTest as a fixture into each test.
Trait that when mixed into a fixture.Suite passes
the config map passed to runTest as a fixture into each test.
Here's an example in which tests just check to make sure "hello" and "world"
are defined keys in the config map:
package org.scalatest.examples.fixture.configmapfixture
import org.scalatest._
class ExampleSpec extends fixture.FlatSpec with fixture.ConfigMapFixture with Matchers {
"The config map" should "contain hello" in { configMap =>
// Use the configMap passed to runTest in the test
configMap should contain key "hello"
}
it should "contain world" in { configMap =>
configMap should contain key "world"
}
}
If you run this class without defining "hello" and "world"
in the confg map, the tests will fail:
scala> org.scalatest.run(new ExampleSpec) ExampleSpec: The config map - should contain hello *** FAILED *** Map() did not contain key "hello" (:20) - should contain world *** FAILED *** Map() did not contain key "world" ( :24)
If you do define "hello" and "world" keys
in the confg map, the tests will success:
scala> org.scalatest.run(new ExampleSpec, configMap = Map("hello" -> "hi", "world" -> "globe"))
ExampleSpec:
The config map
- should contain hello
- should contain world
A function that takes no parameters (i.e., a Function0 or "no-arg" function) and results in Unit, which when
invoked executes the body of the constructor of the class into which this trait is mixed.
A function that takes no parameters (i.e., a Function0 or "no-arg" function) and results in Unit, which when
invoked executes the body of the constructor of the class into which this trait is mixed.
This trait extends DelayedInit and defines a delayedInit method that
saves the body of the constructor (passed to delayedInit) for later execution when apply is invoked.
This trait is somewhat magical and therefore may be challenging for your collegues to understand, so please use it as a last resort only when the
simpler options described in the "shared fixtures" section of your chosen style trait won't do
the job. NoArg is
intended to address a specific use case that will likely be rare, and is unlikely to be useful outside of its intended use case, but
it is quite handy for its intended use case (described in the next paragraph).
One potential gotcha, for example, is that a subclass's constructor body could in theory be executed multiple times by simply invoking apply multiple
times. In the intended use case for this trait, however, the body will be executed only once.
The intended use case for this method is (relatively rare) situations in which you want to extend a different instance of the same class for each test, with the body of the test inheriting the members of that class, and with code executed before and/or after the body of the test.
For example, Akka's TestKit class takes an ActorSystem,
which must have a unique name. To run a suite of tests in parallel, each test must get its own ActorSystem, to
ensure the tests run in isolation. At the end of each test, the ActorSystem must be shutdown. With NoArg,
you can achieve this by first defining a class that extends TestKit and mixes in NoArg.
Here's an example taken with permission from the book Akka Concurrency, by Derek Wyatt:
import akka.actor.ActorSystem
import akka.testkit.{TestKit, ImplicitSender}
import java.util.concurrent.atomic.AtomicInteger
import org.scalatest.fixture.NoArg
object ActorSys {
val uniqueId = new AtomicInteger(0)
}
class ActorSys(name: String) extends
TestKit(ActorSystem(name))
with ImplicitSender
with NoArg {
def this() = this(
"TestSystem%05d".format(
ActorSys.uniqueId.getAndIncrement()))
def shutdown(): Unit = system.shutdown()
override def apply() {
try super.apply()
finally shutdown()
}
}
Given this implementation of ActorSys, which will invoke shutdown after the constructor code
is executed, you can run each test in a suite in a subclass of TestKit, giving each test's TestKit
an ActorSystem with a unique name, allowing you to safely run those tests in parallel. Here's an example
from Akka Concurrency:
class MyActorSpec extends fixture.WordSpec
with Matchers
with UnitFixture
with ParallelTestExecution {
def makeActor(): ActorRef =
system.actorOf(Props[MyActor], "MyActor")
"My Actor" should {
"throw when made with the wrong name" in new ActorSys {
an [Exception] should be thrownBy {
// use a generated name
val a = system.actorOf(Props[MyActor])
}
}
"construct without exception" in new ActorSys {
val a = makeActor()
// The throw will cause the test to fail
}
"respond with a Pong to a Ping" in new ActorSys {
val a = makeActor()
a ! Ping
expectMsg(Pong)
}
}
}
UnitFixture is used in this example, because in this case, the fixture.WordSpec feature enabling tests to be defined as
functions from fixture objects of type FixtureParam to Unit is not being used. Rather, only the secondary feature that enables
tests to be defined as functions from no parameters to Unit is being used. This secondary feature is described in the second-to-last
paragraph on the main Scaladoc documentation of fixture.WordSpec, which says:
If a test doesn't need the fixture, you can indicate that by providing a no-arg instead of a one-arg function, ... In other words, instead of starting your function literal with something like “db =>”, you'd start it with “() =>”. For such tests,runTestwill not invokewithFixture(OneArgTest). It will instead directly invokewithFixture(NoArgTest).
Since FixtureParam is unused in this use case, it could
be anything. Making it Unit will hopefully help readers more easily recognize that it is not being used.
Note: As of Scala 2.11, DelayedInit (which is used by NoArg) has been deprecated, to indicate it is buggy and should be avoided
if possible. Those in charge of the Scala compiler and standard library have promised that DelayedInit will not be removed from Scala
unless an alternate way to achieve the same goal is provided. Thus it should be safe to use NoArg, but if you'd rather
not you can achieve the same effect with a bit more boilerplate by extending (() => Unit) instead of NoArg and placing
your code in an explicit body method. Here's an example:
import akka.actor.ActorSystem
import akka.testkit.{TestKit, ImplicitSender}
import java.util.concurrent.atomic.AtomicInteger
import org.scalatest.fixture.NoArg
object ActorSys {
val uniqueId = new AtomicInteger(0)
}
class ActorSys(name: String) extends
TestKit(ActorSystem(name))
with ImplicitSender
with (() => Unit) {
def this() = this(
"TestSystem%05d".format(
ActorSys.uniqueId.getAndIncrement()))
def shutdown(): Unit = system.shutdown()
def body(): Unit
override def apply() = {
try body()
finally shutdown()
}
}
Using this version of ActorSys will require an explicit
body method in the tests:
class MyActorSpec extends fixture.WordSpec
with Matchers
with UnitFixture
with ParallelTestExecution {
def makeActor(): ActorRef =
system.actorOf(Props[MyActor], "MyActor")
"My Actor" should {
"throw when made with the wrong name" in new ActorSys {
def body() =
an [Exception] should be thrownBy {
// use a generated name
val a = system.actorOf(Props[MyActor])
}
}
"construct without exception" in new ActorSys {
def body() = {
val a = makeActor()
// The throw will cause the test to fail
}
}
"respond with a Pong to a Ping" in new ActorSys {
def body() = {
val a = makeActor()
a ! Ping
expectMsg(Pong)
}
}
}
}
Base trait for a family of style traits that can pass a fixture object into tests.
Trait that when mixed into a fixture.Suite passes the
TestData passed to withFixture as a fixture into each test.
Trait that when mixed into a fixture.Suite passes the
TestData passed to withFixture as a fixture into each test.
For example, here's how you could access the test's name in each test using TestDataFixture:
package org.scalatest.examples.fixture.testdatafixture
import org.scalatest._
class ExampleSpec extends fixture.FlatSpec with fixture.TestDataFixture {
"Accessing the test data" should "be easy!" in { td =>
assert(td.name == "Accessing the test data should be easy!")
}
it should "be fun!" in { td =>
assert(td.name == "Accessing the test data should be fun!")
}
}
Trait declaring methods that can be used to register test functions that accept a fixture parameter and have any result type.
Trait that when mixed into a fixture.Suite passes
the unit value as a fixture into each test.
Trait that when mixed into a fixture.Suite passes
the unit value as a fixture into each test.
Since a unit value is unlikely to be of much use to a test, this trait is useful
when the unit value fixture is actually never passed into any tests. Instead
each test in the fixture.Suite is defined as a no-arg function; no tests are defined as one-arg functions.
This should be quite rare, but occasionally can be useful.
For an example, see the main documentation for trait NoArg.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAsyncFunSuite instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAsyncFunSuite instead.
Please use org.scalatest.featurespec.FixtureAsyncFeatureSpec instead
Please use org.scalatest.featurespec.FixtureAsyncFeatureSpecLike instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.flatspec.FixtureAsyncFlatSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.flatspec.FixtureAsyncFlatSpec instead.
Please use org.scalatest.flatspec.FixtureAsyncFlatSpec instead
Please use org.scalatest.flatspec.FixtureAsyncFlatSpecLike instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.freespec.FixtureAsyncFreeSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.freespec.FixtureAsyncFreeSpec instead.
Please use org.scalatest.freespec.FixtureAsyncFreeSpec instead
Please use org.scalatest.freespec.FixtureAsyncFreeSpecLike instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funspec.FixtureAsyncFunSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funspec.FixtureAsyncFunSpec instead.
Please use org.scalatest.funspec.FixtureAsyncFunSpec instead
Please use org.scalatest.funspec.FixtureAsyncFunSpecLike instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAsyncFunSuite instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAsyncFunSuite instead.
Please use org.scalatest.funsuite.FixtureAsyncFunSuite instead
Please use org.scalatest.funsuite.FixtureAsyncFunSuiteLike instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.wordspec.FixtureAsyncWordSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.wordspec.FixtureAsyncWordSpec instead.
Please use org.scalatest.wordspec.FixtureAsyncWordSpec instead
Please use org.scalatest.wordspec.FixtureAsyncWordSpecLike instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAnyFunSuite instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAnyFunSuite instead.
Please use org.scalatest.featurespec.FixtureAnyFeatureSpec instead
Please use org.scalatest.featurespec.FixtureAnyFeatureSpec instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.flatspec.FixtureAnyFlatSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.flatspec.FixtureAnyFlatSpec instead.
Please use org.scalatest.flatspec.FixtureAnyFlatSpec instead
Please use org.scalatest.flatspec.FixtureAnyFlatSpec instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.freespec.FixtureAnyFreeSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.freespec.FixtureAnyFreeSpec instead.
Please use org.scalatest.freespec.FixtureAnyFreeSpec instead
Please use org.scalatest.freespec.FixtureAnyFreeSpec instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funspec.FixtureAnyFunSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funspec.FixtureAnyFunSpec instead.
Please use org.scalatest.funspec.FixtureAnyFunSpec instead
Please use org.scalatest.funsuite.FixtureAnyFunSpec instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAnyFunSuite instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAnyFunSuite instead.
Please use org.scalatest.funsuite.FixtureAnyFunSuite instead
Please use org.scalatest.funsuite.FixtureAnyFunSuite instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAnyFunSuite instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.funsuite.FixtureAnyFunSuite instead.
Please use org.scalatest.propspec.FixtureAnyPropSpec instead
Please use org.scalatest.propspec.FixtureAnyPropSpec instead
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.wordspec.FixtureAnyWordSpec instead.
This class is deprecated and will be removed in future version of ScalaTest, please use org.scalatest.wordspec.FixtureAnyWordSpec instead.
Please use org.scalatest.wordspec.FixtureAnyWordSpec instead
Please use org.scalatest.wordspec.FixtureAnyWordSpec instead
Package fixture deprecated types.