package fixture
Type Members
- trait AsyncConfigMapFixture extends AnyRef
Trait that when mixed into a
fixture.AsyncTestSuite
passes the config map passed torunTest
as a fixture into each test.Trait that when mixed into a
fixture.AsyncTestSuite
passes the config map passed torunTest
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 AsyncTestDataFixture extends AnyRef
Trait that when mixed into a
fixture.AsyncTestSuite
passes theTestData
passed towithFixture
as a fixture into each test.Trait that when mixed into a
fixture.AsyncTestSuite
passes theTestData
passed towithFixture
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 AsyncTestRegistration extends AnyRef
Trait declaring methods that can be used to register test functions that accept a fixture parameter and have result type
Future[Assertion]
. - trait AsyncTestSuite extends Suite with scalatest.AsyncTestSuite
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 supertraitfixture.Suite
, because thewithFixture(OneArgTest)
lifecycle method assumes synchronous testing. Here is its signature:def withFixture(test: OneArgTest): Outcome
The test function interface,
OneArgTest
, offers anapply
method that takes aFixtureParam
and returnsOutcome
:// 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 ofSucceeded
,Failed
,Canceled
, or Pending. This is also true whenwithFixture(OneArgTest)
returns: because the result type ofwithFixture(OneArgTest)
isOutcome
, 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 callwithFixture(OneArgAsyncTest)
instead ofwithFixture(OneArgTest)
, wherewithFixture(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
likewithFixture
, thewithFixture
method returns aFutureOutcome
. Similarly, theapply
method of test function interface,OneArgAsyncTest
, returnsFutureOutcome
:// 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 supertraitorg.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 letwithFixture(NoArgAsyncTest)
invoke the test function instead of invoking the test function directly. To do so, you'll need to convert theOneArgAsyncTest
to aNoArgAsyncTest
. You can do that by passing the fixture object to thetoNoArgAsyncTest
method ofOneArgAsyncTest
. In other words, instead of writing “test(theFixture)
”, you'd delegate responsibility for invoking the test function to thewithFixture(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 ofFuture
registration methods:onComplete
,onSuccess
, oronFailure
. Note that if a test fails, that will be treated as ascala.util.Success(org.scalatest.Failure)
. So if you want to perform an action if a test fails, for example, you'd register the callaback usingonSuccess
, 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 themap
ortransform
methods ofFuture
, 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
'sapply
method will only return aFailure
if the test completes abruptly with an exception (such asOutOfMemoryError
) that should cause the suite to abort rather than the test to fail. Thus usually you would usemap
to transform future outcomes, nottransform
, so that such suite-aborting exceptions pass through unchanged. The suite will abort asynchronously with any exception returned in aFailure
. - trait ConfigMapFixture extends AnyRef
Trait that when mixed into a
fixture.Suite
passes the config map passed torunTest
as a fixture into each test.Trait that when mixed into a
fixture.Suite
passes the config map passed torunTest
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
- trait NoArg extends DelayedInit with () => Unit
A function that takes no parameters (i.e., a
Function0
or "no-arg" function) and results inUnit
, 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 inUnit
, which when invoked executes the body of the constructor of the class into which this trait is mixed.This trait extends
DelayedInit
and defines adelayedInit
method that saves the body of the constructor (passed todelayedInit
) for later execution whenapply
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 invokingapply
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 anActorSystem
, which must have a unique name. To run a suite of tests in parallel, each test must get its ownActorSystem
, to ensure the tests run in isolation. At the end of each test, theActorSystem
must be shutdown. WithNoArg
, you can achieve this by first defining a class that extendsTestKit
and mixes inNoArg
. 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 invokeshutdown
after the constructor code is executed, you can run each test in a suite in a subclass ofTestKit
, giving each test'sTestKit
anActorSystem
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, thefixture.WordSpec
feature enabling tests to be defined as functions from fixture objects of typeFixtureParam
toUnit
is not being used. Rather, only the secondary feature that enables tests to be defined as functions from no parameters toUnit
is being used. This secondary feature is described in the second-to-last paragraph on the main Scaladoc documentation offixture.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,runTest
will not invokewithFixture(OneArgTest)
. It will instead directly invokewithFixture(NoArgTest)
.Since
FixtureParam
is unused in this use case, it could be anything. Making itUnit
will hopefully help readers more easily recognize that it is not being used.Note: As of Scala 2.11,
DelayedInit
(which is used byNoArg
) 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 thatDelayedInit
will not be removed from Scala unless an alternate way to achieve the same goal is provided. Thus it should be safe to useNoArg
, but if you'd rather not you can achieve the same effect with a bit more boilerplate by extending (() => Unit
) instead ofNoArg
and placing your code in an explicitbody
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 explicitbody
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) } } } }
- trait Suite extends scalatest.Suite
Base trait for a family of style traits that can pass a fixture object into tests.
- trait TestDataFixture extends AnyRef
Trait that when mixed into a
fixture.Suite
passes theTestData
passed towithFixture
as a fixture into each test.Trait that when mixed into a
fixture.Suite
passes theTestData
passed towithFixture
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 TestRegistration extends AnyRef
Trait declaring methods that can be used to register test functions that accept a fixture parameter and have any result type.
- trait TestSuite extends Suite with scalatest.TestSuite
- trait UnitFixture extends AnyRef
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 traitNoArg
.
Deprecated Type Members
- abstract class AsyncFeatureSpec extends AsyncFeatureSpecLike
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.
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.featurespec.FixtureAsyncFeatureSpec instead
- type AsyncFeatureSpecLike = FixtureAsyncFeatureSpecLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.featurespec.FixtureAsyncFeatureSpecLike instead
- abstract class AsyncFlatSpec extends AsyncFlatSpecLike
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.
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.flatspec.FixtureAsyncFlatSpec instead
- type AsyncFlatSpecLike = FixtureAsyncFlatSpecLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.flatspec.FixtureAsyncFlatSpecLike instead
- abstract class AsyncFreeSpec extends AsyncFreeSpecLike
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.
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.freespec.FixtureAsyncFreeSpec instead
- type AsyncFreeSpecLike = FixtureAsyncFreeSpecLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.freespec.FixtureAsyncFreeSpecLike instead
- abstract class AsyncFunSpec extends AsyncFunSpecLike
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.
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.funspec.FixtureAsyncFunSpec instead
- type AsyncFunSpecLike = FixtureAsyncFunSpecLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.funspec.FixtureAsyncFunSpecLike instead
- abstract class AsyncFunSuite extends FixtureAsyncFunSuiteLike
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.
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.funsuite.FixtureAsyncFunSuite instead
- type AsyncFunSuiteLike = FixtureAsyncFunSuiteLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.funsuite.FixtureAsyncFunSuiteLike instead
- abstract class AsyncWordSpec extends AsyncWordSpecLike
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.
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.wordspec.FixtureAsyncWordSpec instead
- type AsyncWordSpecLike = FixtureAsyncWordSpecLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.wordspec.FixtureAsyncWordSpecLike instead
- abstract class FeatureSpec extends FeatureSpecLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.featurespec.FixtureAnyFeatureSpec instead
- type FeatureSpecLike = FixtureAnyFeatureSpecLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.featurespec.FixtureAnyFeatureSpec instead
- abstract class FlatSpec extends FlatSpecLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.flatspec.FixtureAnyFlatSpec instead
- type FlatSpecLike = FixtureAnyFlatSpec
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.flatspec.FixtureAnyFlatSpec instead
- abstract class FreeSpec extends FreeSpecLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.freespec.FixtureAnyFreeSpec instead
- type FreeSpecLike = FixtureAnyFreeSpec
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.freespec.FixtureAnyFreeSpec instead
- abstract class FunSpec extends FunSpecLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.funspec.FixtureAnyFunSpec instead
- type FunSpecLike = FixtureAnyFunSpec
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.funsuite.FixtureAnyFunSpec instead
- abstract class FunSuite extends FunSuiteLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.funsuite.FixtureAnyFunSuite instead
- type FunSuiteLike = FixtureAnyFunSuiteLike
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.funsuite.FixtureAnyFunSuite instead
- abstract class PropSpec extends PropSpecLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.propspec.FixtureAnyPropSpec instead
- type PropSpecLike = FixtureAnyPropSpec
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.propspec.FixtureAnyPropSpec instead
- abstract class WordSpec extends WordSpecLike
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.
- Annotations
- @Finders() @deprecated
- Deprecated
Please use org.scalatest.wordspec.FixtureAnyWordSpec instead
- type WordSpecLike = FixtureAnyWordSpec
- Annotations
- @deprecated
- Deprecated
Please use org.scalatest.wordspec.FixtureAnyWordSpec instead