Trait providing an apply
method to which alert messages about a running suite of tests can be reported.
Trait providing an apply
method to which alert messages about a running suite of tests can be reported.
An Alerter
is essentially
used to wrap a Reporter
and provide easy ways to send alert messages
to that Reporter
via an AlertProvided
event.
Alerter
contains an apply
method that takes a string and
an optional payload object of type Any
.
The Alerter
will forward the passed alert message
string to the
Reporter
as the message
parameter, and the optional
payload object as the payload
parameter, of an AlertProvided
event.
For insight into the differences between Alerter
, Notifier
, and Informer
, see the
main documentation for trait Alerting
.
Trait that contains the alert
method, which can be used to send an alert to the reporter.
Trait that contains the alert
method, which can be used to send an alert to the reporter.
One difference between alert
and the info
method of Informer
is that
info
messages provided during a test are recorded and sent as part of test completion event, whereas
alert
messages are sent right away as AlertProvided
messages. For long-running tests,
alert
allows you to send "alert notifications" to the reporter right away, so users can be made aware
of potential problems being experienced by long-running tests. By contrast, info
messages will only be seen by the user after the
test has completed, and are more geared towards specification (such as Given/When/Then messages) than notification.
The difference between alert
and the update
method of Updating
is
that alert
is intended to be used
for warnings or notifications of potential problems, whereas update
is just for status updates.
In string reporters for which ANSI color is enabled, update
notifications are shown in green and alert
notifications
in yellow.
Trait providing an implicit conversion that allows clues to be placed after a block of code.
Trait providing an implicit conversion that allows clues to be placed after a block of code.
You can use the withClue
construct provided by Assertions
, which is
extended by every style trait in ScalaTest, to add extra information to reports of failed or canceled tests.
The withClue
from Assertions
places the "clue string" at the front, both
in the code and in the resulting message:
withClue("This is a prepended clue;") { 1 + 1 should equal (3) }
The above expression will yield the failure message:
This is a prepended clue; 2 did not equal 3
If you mix in this trait, or import its members via its companion object, you can alternatively place the clue string at the end, like this:
{ 1 + 1 should equal (3) } withClue "now the clue comes after"
The above expression will yield the failure message:
2 did not equal 3 now the clue comes after
If no space is already present, either at the beginning of the clue string or at the end
of the current message, a space will be placed between the two, unless the clue string
starts with one of the punctuation characters: comma (,
), period (.
),
or semicolon (;
). For example, the failure message in the above example
includes an extra space inserted between 3 and now.
By contrast this code, which has a clue string starting with comma:
{ 1 + 1 should equal (3) } withClue ", now the clue comes after"
Will yield a failure message with no extra inserted space:
2 did not equal 3, now the clue comes after
The withClue
method will only append the clue string to the detail
message of exception types that mix in the ModifiableMessage
trait.
See the documentation for ModifiableMessage
for more
information.
Note: the reason this functionality is not provided by Assertions
directly, like the
prepended withClue
construct, is because appended clues require an implicit conversion.
ScalaTest only gives you one implicit conversion by default in any test class to minimize the
potential for conflicts with other implicit conversions you may be using. All other implicit conversions,
including the one provided by this trait, you must explicitly invite into your code through inheritance
or an import.
Arguments bundle passed to four of ScalaTest's lifecycle methods: run
, runNestedSuites
,
runTests
, and runTest
.
Arguments bundle passed to four of ScalaTest's lifecycle methods: run
, runNestedSuites
,
runTests
, and runTest
.
The signatures of these methods, defined in trait Suite
, are:
def run(testName: Option[String], args: Args) def runNestedSuites(args: Args) def runTests(testName: Option[String], args: Args) def runTest(testName: String, args: Args)
The purpose of bundling these arguments into an Args
object instead of passing them in individually is to make the signature
of these four lifecycle methods easier to read, write, and remember, as well as to make the methods more pleasant to override in user code.
the Reporter
to which results will be reported
the Stopper
that will be consulted to determine whether to stop execution early.
a Filter
with which to filter tests based on their tags
a ConfigMap
of key-value pairs that can be used by the executing Suite
of tests.
an optional Distributor
, into which to put nested Suite
s to be executed
by another entity, such as concurrently by a pool of threads. If None
, nested Suite
s will be executed sequentially.
a Tracker
tracking Ordinal
s being fired by the current thread.
a (possibly empty) Set
of String
s specifying the run's chosen styles
a flag used to pass information between run methods
in OneInstancePerTest
and ParallelTestExecution
.
an optional DistributedTestSorter
used by ParallelTestExecution
to sort the events
for the parallel-executed tests of one suite back into sequential order on the fly, with a timeout in case a test takes too long to complete
an optional DistributedSuiteSorter
used by ParallelTestExecution
to ensure the events
for the parallel-executed suites are sorted back into sequential order, with a timeout in case a suite takes to long to complete, even when tests are executed in parallel
if any passed parameter is null
.
Trait that contains ScalaTest's basic assertion methods.
Trait that contains ScalaTest's basic assertion methods.
You can use the assertions provided by this trait in any ScalaTest Suite
,
because Suite
mixes in this trait. This trait is designed to be used independently of anything else in ScalaTest, though, so you
can mix it into anything. (You can alternatively import the methods defined in this trait. For details, see the documentation
for the Assertions
companion object.
In any Scala program, you can write assertions by invoking assert
and passing in a Boolean
expression,
such as:
val left = 2 val right = 1 assert(left == right)
If the passed expression is true
, assert
will return normally. If false
,
Scala's assert
will complete abruptly with an AssertionError
. This behavior is provided by
the assert
method defined in object Predef
, whose members are implicitly imported into every
Scala source file. This Assertions
trait defines another assert
method that hides the
one in Predef
. It behaves the same, except that if false
is passed it throws
TestFailedException
instead of AssertionError
.
Why? Because unlike AssertionError
, TestFailedException
carries information about exactly
which item in the stack trace represents
the line of test code that failed, which can help users more quickly find an offending line of code in a failing test.
If you pass the previous Boolean
expression, left == right
to assert
in a ScalaTest test,
a failure will be reported that, because assert
is implemented as a macro,
includes reporting the left and right values.
For example, given the same code as above but using ScalaTest assertions:
import org.scalatest.Assertions._ val left = 2 val right = 1 assert(left == right)
The detail message in the thrown TestFailedException
from this assert
will be: "2 did not equal 1".
ScalaTest's assert
macro works by recognizing patterns in the AST of the expression passed to assert
and,
for a finite set of common expressions, giving an error message that an equivalent ScalaTest matcher
expression would give. Here are some examples, where a
is 1, b
is 2, c
is 3, d
is 4, xs
is List(a, b, c)
, and num
is 1.0:
assert(a == b || c >= d) // Error message: 1 did not equal 2, and 3 was not greater than or equal to 4For expressions that are not recognized, the macro currently prints out a string representation of the (desugared) AST and adds
assert(xs.exists(_ == 4)) // Error message: List(1, 2, 3) did not contain 4
assert("hello".startsWith("h") && "goodbye".endsWith("y")) // Error message: "hello" started with "h", but "goodbye" did not end with "y"
assert(num.isInstanceOf[Int]) // Error message: 1.0 was not instance of scala.Int
assert(Some(2).isEmpty) // Error message: Some(2) was not empty
"was false"
. Here are some examples of
error messages for unrecognized expressions:
assert(None.isDefined) // Error message: scala.None.isDefined was falseYou can augment the standard error message by providing a
assert(xs.exists(i => i > 10)) // Error message: xs.exists(((i: Int) => i.>(10))) was false
String
as a second argument
to assert
, like this:
val attempted = 2 assert(attempted == 1, "Execution was attempted " + left + " times instead of 1 time")Using this form of
assert
, the failure report will be more specific to your problem domain, thereby
helping you debug the problem. This Assertions
trait also mixes in the
TripleEquals
, which gives you a ===
operator
that allows you to customize Equality
, perform equality checks with numeric
Tolerance
, and enforce type constraints at compile time with
sibling traits TypeCheckedTripleEquals
and
ConversionCheckedTripleEquals
.
== Expected results ==
Although the assert
macro provides a natural, readable extension to Scala's assert
mechanism that
provides good error messages, as the operands become lengthy, the code becomes less readable. In addition, the error messages
generated for ==
and ===
comparisons
don't distinguish between actual and expected values. The operands are just called left
and right
,
because if one were named expected
and the other actual
, it would be difficult for people to
remember which was which. To help with these limitations of assertions, Suite
includes a method called assertResult
that
can be used as an alternative to assert
. To use assertResult
, you place
the expected value in parentheses after assertResult
, followed by curly braces containing code
that should result in the expected value. For example:
val a = 5 val b = 2 assertResult(2) { a - b }In this case, the expected value is
2
, and the code being tested is a - b
. This assertion will fail, and
the detail message in the TestFailedException
will read, "Expected 2, but got 3."
== Forcing failures ==
If you just need the test to fail, you can write:
fail()Or, if you want the test to fail with a message, write:
fail("I've got a bad feeling about this")
== Intercepted exceptions ==
Sometimes you need to test whether a method throws an expected exception under certain circumstances, such
as when invalid arguments are passed to the method. You can do this in the JUnit 3 style, like this:
val s = "hi" try { s.charAt(-1) fail() } catch { case _: IndexOutOfBoundsException => // Expected, so continue }If
charAt
throws IndexOutOfBoundsException
as expected, control will transfer
to the catch case, which does nothing. If, however, charAt
fails to throw an exception,
the next statement, fail()
, will be run. The fail
method always completes abruptly with
a TestFailedException
, thereby signaling a failed test.
To make this common use case easier to express and read, ScalaTest provides an intercept
method. You use it like this:
val s = "hi" intercept[IndexOutOfBoundsException] { s.charAt(-1) }This code behaves much like the previous example. If
charAt
throws an instance of IndexOutOfBoundsException
,
intercept
will return that exception. But if charAt
completes normally, or throws a different
exception, intercept
will complete abruptly with a TestFailedException
. intercept
returns the
caught exception so that you can inspect it further if you wish, for example, to ensure that data contained inside
the exception has the expected values.
== Checking that a snippet of code does or does not compile ==
Often when creating libraries you may wish to ensure that certain arrangements of code that
represent potential “user errors” do not compile, so that your library is more error resistant.
ScalaTest's Assertions
trait includes the following syntax for that purpose:
assertDoesNotCompile("val a: String = 1")
If you want to ensure that a snippet of code does not compile because of a type error (as opposed
to a syntax error), use:
assertTypeError("val a: String = 1")
Note that the assertTypeError
call will only succeed if the given snippet of code does not
compile because of a type error. A syntax error will still result on a thrown TestFailedException
.
If you want to state that a snippet of code does compile, you can make that
more obvious with:
assertCompiles("val a: Int = 1")
Although the previous three constructs are implemented with macros that determine at compile time whether
the snippet of code represented by the string does or does not compile, errors
are reported as test failures at runtime.
== Assumptions ==
Trait Assertions
also provides methods that allow you to cancel a test.
You would cancel a test if a resource required by the test was unavailable. For example, if a test
requires an external database to be online, and it isn't, the test could be canceled to indicate
it was unable to run because of the missing database. Such a test assumes a database is
available, and you can use the assume
method to indicate this at the beginning of
the test, like this:
assume(database.isAvailable)For each overloaded
assert
method, trait Assertions
provides an
overloaded assume
method with an identical signature and behavior, except the
assume
methods throw TestCanceledException
whereas the
assert
methods throw TestFailedException
. As with assert
,
assume
hides a Scala method in Predef
that performs a similar
function, but throws AssertionError
. And just as you can with assert
,
you will get an error message extracted by a macro from the AST passed to assume
, and can
optionally provide a clue string to augment this error message. Here are some examples:
assume(database.isAvailable, "The database was down again") assume(database.getAllUsers.count === 9)== Forcing cancelations == For each overloaded
fail
method, there's a corresponding cancel
method
with an identical signature and behavior, except the cancel
methods throw
TestCanceledException
whereas the fail
methods throw
TestFailedException
. Thus if you just need to cancel a test, you can write:
cancel()If you want to cancel the test with a message, just place the message in the parentheses:
cancel("Can't run the test because no internet connection was found")
== Getting a clue ==
If you want more information that is provided by default by the methods if this trait,
you can supply a "clue" string in one of several ways.
The extra information (or "clues") you provide will
be included in the detail message of the thrown exception. Both
assert
and assertResult
provide a way for a clue to be
included directly, intercept
does not.
Here's an example of clues provided directly in assert
:
assert(1 + 1 === 3, "this is a clue")and in
assertResult
:
assertResult(3, "this is a clue") { 1 + 1 }The exceptions thrown by the previous two statements will include the clue string,
"this is a clue"
, in the exception's detail message.
To get the same clue in the detail message of an exception thrown
by a failed intercept
call requires using withClue
:
withClue("this is a clue") { intercept[IndexOutOfBoundsException] { "hi".charAt(-1) } }The
withClue
method will only prepend the clue string to the detail
message of exception types that mix in the ModifiableMessage
trait.
See the documentation for ModifiableMessage
for more information.
If you wish to place a clue string after a block of code, see the documentation for
AppendedClues
.
Note: ScalaTest's assertTypeError
construct is in part inspired by the illTyped
macro
of shapeless.
Trait that can be mixed into suites that need code executed before and after running each test.
Trait that can be mixed into suites that need code executed before and after running each test.
Recommended Usage:
Use trait BeforeAndAfter when you need to perform the same side-effects before and/or after tests, rather than at the beginning
or end of tests. Note: For more insight into where BeforeAndAfter fits into the big picture, see the
Shared fixtures section in the documentation for your chosen style trait.
|
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
Trait BeforeAndAfter
offers one way to eliminate such code duplication:
a before
clause that will register code to be run before each test,
and an after
clause that will register code to be run after.
Here's an example:
package org.scalatest.examples.flatspec.beforeandafterThe
import org.scalatest._ import collection.mutable.ListBuffer
class ExampleSpec extends FlatSpec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
"Testing" should "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it should "be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } }
before
and after
methods can each only be called once per Suite
,
and cannot be invoked after run
has been invoked. If either of the registered before or after functions
complete abruptly with an exception, it will be reported as an aborted suite and no more tests will be attempted in that suite.
Note that the only way before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. Were you to mix ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead.
The advantage this trait has over BeforeAndAfterEach
is that its syntax is more concise.
The main disadvantage is that it is not stackable, whereas BeforeAndAfterEach
is. I.e.,
you can write several traits that extend BeforeAndAfterEach
and provide beforeEach
methods
that include a call to super.beforeEach
, and mix them together in various combinations. By contrast,
only one call to the before
registration function is allowed in a suite or spec that mixes
in BeforeAndAfter
. In addition, BeforeAndAfterEach
allows you to access
the config map and test name via the TestData
passed to its beforeEach
and
afterEach
methods, whereas BeforeAndAfter
gives you no access to the config map.
Trait that can be mixed into suites that need methods invoked before and after executing the suite.
Trait that can be mixed into suites that need methods invoked before and after executing the suite.
This trait allows code to be executed before and/or after all the tests and nested suites of a
suite are run. This trait overrides run
and calls the
beforeAll
method, then calls super.run
. After the super.run
invocation completes, whether it returns normally or completes abruptly with an exception,
this trait's run
method will invoke afterAll
.
Trait BeforeAndAfterAll
defines beforeAll
and afterAll
methods that take no parameters. This trait's implementation of these
methods do nothing.
For example, the following ExampleSpec
mixes in BeforeAndAfterAll
and
in beforeAll
, creates and writes to a temp file, taking the name of the temp file
from the configMap
. This same configMap
is then passed to the run
methods of the nested suites, OneSpec
, TwoSpec
, RedSpec
,
and BlueSpec
, so those suites can access the filename and, therefore, the file's
contents. After all of the nested suites have executed, afterAll
is invoked, which
again grabs the file name from the configMap
and deletes the file. Each of these five
test classes extend trait TempFileExistsSpec
, which defines a test that ensures the temp file exists.
(Note: if you're unfamiliar with the withFixture(OneArgTest)
approach to shared fixtures, check out
the documentation for trait fixture.FlatSpec
.)
package org.scalatest.examples.beforeandafterallRunning the above class in the interpreter will give an error if you don't supply a mapping for
import org.scalatest._ import java.io._
trait TempFileExistsSpec extends fixture.FlatSpecLike {
private val tempFileName = "tmp.txt"
type FixtureParam = File override def withFixture(test: OneArgTest) = { val file = new File(tempFileName) withFixture(test.toNoArgTest(file)) // loan the fixture to the test }
"The temp file" should ("exist in " + suiteName) in { file => assert(file.exists) } }
class OneSpec extends TempFileExistsSpec class TwoSpec extends TempFileExistsSpec class RedSpec extends TempFileExistsSpec class BlueSpec extends TempFileExistsSpec
class ExampleSpec extends Suites( new OneSpec, new TwoSpec, new RedSpec, new BlueSpec ) with TempFileExistsSpec with BeforeAndAfterAll {
// Set up the temp file needed by the test, taking // a file name from the config map override def beforeAll() { val writer = new FileWriter(tempFileName) try writer.write("Hello, suite of tests!") finally writer.close() }
// Delete the temp file override def afterAll() { val file = new File(tempFileName) file.delete() } }
"tempFileName"
in the config map:
scala> new ExampleSpec execute ExampleSpec: Exception encountered when invoking run on a suite. *** ABORTED *** Exception encountered when invoking run on a suite. (If you do supply a mapping for:30) *** RUN ABORTED *** An exception or error caused a run to abort: must place a temp file name in the config map under the key: tempFileName ( :30)
"tempFileName"
in the config map, you'll see that the temp file is available to all the tests:
scala> new ExampleSpec execute (configMap = ConfigMap("tempFileName" -> "tmp.txt"))
ExampleSpec:
OneSpec:
The temp file
- should exist in OneSpec
TwoSpec:
The temp file
- should exist in TwoSpec
RedSpec:
The temp file
- should exist in RedSpec
BlueSpec:
The temp file
- should exist in BlueSpec
The temp file
- should exist in ExampleSpec
Note: As of 2.0.M5, this trait uses the newly added Status
result of Suite
's "run" methods
to ensure that the code in afterAll
is executed after
all the tests and nested suites are executed even if a Distributor
is passed.
Note that it is not guaranteed that afterAll
is invoked from the same thread as beforeAll
,
so if there's any shared state between beforeAll
and afterAll
you'll need to make sure they are
synchronized correctly.
Trait that can be mixed into suites that need methods that make use of the config map invoked before and/or after executing the suite.
Trait that can be mixed into suites that need methods that make use of the config map invoked before and/or after executing the suite.
This trait allows code to be executed before and/or after all the tests and nested suites of a
suite are run. This trait overrides run
and calls the
beforeAll(ConfigMap)
method, then calls super.run
. After the super.run
invocation completes, whether it returns normally or completes abruptly with an exception,
this trait's run
method will invoke afterAll(ConfigMap)
.
Note that this trait differs from BeforeAndAfterAll
in that it gives
the beforeAll
and afterAll
code access to the config map. If you don't need
the config map, use BeforeAndAfterAll
instead.
Trait BeforeAndAfterAllConfigMap
defines beforeAll
and afterAll
methods that take a configMap
.
This trait's implemention of each method does nothing.
For example, the following ExampleSpec
mixes in BeforeAndAfterAllConfigMap
and
in beforeAll
, creates and writes to a temp file, taking the name of the temp file
from the configMap
. This same configMap
is then passed to the run
methods of the nested suites, OneSpec
, TwoSpec
, RedSpec
,
and BlueSpec
, so those suites can access the filename and, therefore, the file's
contents. After all of the nested suites have executed, afterAll
is invoked, which
again grabs the file name from the configMap
and deletes the file. Each of these five
test classes extend trait TempFileExistsSpec
, which defines a test that ensures the temp file exists.
(Note: if you're unfamiliar with the withFixture(OneArgTest)
approach to shared fixtures, check out
the documentation for trait fixture.FlatSpec
.)
package org.scalatest.examples.beforeandafterallconfigmapRunning the above class in the interpreter will give an error if you don't supply a mapping for
import org.scalatest._ import java.io._
trait TempFileExistsSpec extends fixture.FlatSpec {
type FixtureParam = File override def withFixture(test: OneArgTest) = { val fileName = test.configMap.getRequired[String]("tempFileName") val file = new File(fileName) withFixture(test.toNoArgTest(file)) // loan the fixture to the test }
"The temp file" should ("exist in " + suiteName) in { file => assert(file.exists) } }
class OneSpec extends TempFileExistsSpec class TwoSpec extends TempFileExistsSpec class RedSpec extends TempFileExistsSpec class BlueSpec extends TempFileExistsSpec
class ExampleSpec extends Specs( new OneSpec, new TwoSpec, new RedSpec, new BlueSpec ) with TempFileExistsSpec with BeforeAndAfterAll {
private val tempFileName = "tempFileName"
// Set up the temp file needed by the test, taking // a file name from the config map override def beforeAll(cm: ConfigMap) { assume( cm.isDefinedAt(tempFileName), "must place a temp file name in the config map under the key: " + tempFileName ) val fileName = cm.getRequired[String](tempFileName) val writer = new FileWriter(fileName) try writer.write("Hello, suite of tests!") finally writer.close() }
// Delete the temp file override def afterAll(cm: ConfigMap) { val fileName = cm.getRequired[String]("tempFileName") val file = new File(fileName) file.delete() } }
"tempFileName"
in the config map:
scala> new ExampleSpec execute ExampleSpec: Exception encountered when invoking run on a suite. *** ABORTED *** Exception encountered when invoking run on a suite. (If you do supply a mapping for:30) *** RUN ABORTED *** An exception or error caused a run to abort: must place a temp file name in the config map under the key: tempFileName ( :30)
"tempFileName"
in the config map, you'll see that the temp file is available to all the tests:
scala> new ExampleSpec execute (configMap = ConfigMap("tempFileName" -> "tmp.txt"))
ExampleSpec:
OneSpec:
The temp file
- should exist in OneSpec
TwoSpec:
The temp file
- should exist in TwoSpec
RedSpec:
The temp file
- should exist in RedSpec
BlueSpec:
The temp file
- should exist in BlueSpec
The temp file
- should exist in ExampleSpec
Note: As of 2.0.M5, this trait uses the newly added Status
result of Suite
's "run" methods
to ensure that the code in afterAll
is executed after
all the tests and nested suites are executed even if a Distributor
is passed.
Note that it is not guaranteed that afterAll
is invoked from the same thread as beforeAll
,
so if there's any shared state between beforeAll
and afterAll
you'll need to make sure they are
synchronized correctly.
Stackable trait that can be mixed into suites that need code executed before and/or after running each test.
Stackable trait that can be mixed into suites that need code executed before and/or after running each test.
Recommended Usage:
Use trait BeforeAndAfterEach when you want to stack traits that perform side-effects before and/or after tests, rather
than at the beginning or end of tests, or when you need access to the config map or test name in the before and/or after code.
Note: For more insight into where BeforeAndAfterEach fits into the big picture, see the
Shared fixtures section in the documentation for your chosen style trait.
|
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
Trait BeforeAndAfterEach
offers one way to eliminate such code duplication:
a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Here's an example:
package org.scalatest.examples.flatspec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try { super.afterEach() // To be stackable, must call super.afterEach } finally { builder.clear() } } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try { super.afterEach() // To be stackable, must call super.afterEach } finally { buffer.clear() } } }
class ExampleSpec extends FlatSpec with Builder with Buffer {
"Testing" should "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it should "be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The main advantage of BeforeAndAfterEach
over BeforeAndAfter
is that BeforeAndAfterEach
.
enables trait stacking.
The main disadvantage of BeforeAndAfterEach
compared to BeforeAndAfter
is that BeforeAndAfterEach
requires more boilerplate. If you don't need trait stacking, use BeforeAndAfter
instead
of BeforeAndAfterEach
.
If you want to make use of test data (the test name, config map, etc.) in your beforeEach
or afterEach
method, use trait BeforeAndAfterEachTestData
instead.
Stackable trait that can be mixed into suites that need code that makes use of test data (test name, tags, config map, etc.) executed before and/or after running each test.
Stackable trait that can be mixed into suites that need code that makes use of test data (test name, tags, config map, etc.) executed before and/or after running each test.
Recommended Usage:
Use trait BeforeAndAfterEachTestData when you want to stack traits that perform side-effects before and/or after tests, rather
than at the beginning or end of tests, when you need access to any test data (such as the config map) in the before and/or after code.
Note: For more insight into where BeforeAndAfterEachTestData fits into the big picture, see the
Shared fixtures section in the documentation for your chosen style trait.
|
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
Trait BeforeAndAfterEachTestData
offers one way to eliminate such code duplication:
a beforeEach(TestData)
method that will be run before each test (like JUnit's setUp
),
and an afterEach(TestData)
method that will be run after (like JUnit's tearDown
).
Here's an example:
package org.scalatest.examples.flatspec.composingbeforeandaftereachtestdataTo get the same ordering as
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEachTestData { this: Suite =>
val builder = new StringBuilder
override def beforeEach(td: TestData) { builder.append(td.name) super.beforeEach(td) // To be stackable, must call super.beforeEach(TestData) }
override def afterEach(td: TestData) { try { super.afterEach(td) // To be stackable, must call super.afterEach(TestData) } finally { builder.clear() } } }
trait Buffer extends BeforeAndAfterEachTestData { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach(td: TestData) { try { super.afterEach(td) // To be stackable, must call super.afterEach(TestData) } finally { buffer.clear() } } }
class ExampleSpec extends FlatSpec with Builder with Buffer {
"Testing" should "be easy" in { builder.append("!") assert(builder.toString === "Testing should be easy!") assert(buffer.isEmpty) buffer += "sweet" }
it should "be fun" in { builder.append("!") assert(builder.toString === "Testing should be fun!") assert(buffer.isEmpty) buffer += "clear" } }
withFixture
, place your super.beforeEach(TestData)
call at the end of each
beforeEach(TestData)
method, and the super.afterEach(TestData)
call at the beginning of each afterEach(TestData)
method, as shown in the previous example. It is a good idea to invoke super.afterEach(TestData)
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach(TestData)
throws an exception.
Besides enabling trait stacking, the other main advantage of BeforeAndAfterEachTestData
over BeforeAndAfter
is that BeforeAndAfterEachTestData
allows you to make use of test data (such as the test name and config map) in your before
and/or after code, whereas BeforeAndAfter
does not.
The main disadvantage of BeforeAndAfterEachTestData
compared to BeforeAndAfter
and BeforeAndAfterEach
is
that BeforeAndAfterEachTestData
requires more boilerplate. If you don't need trait stacking or access to the test data, use
BeforeAndAfter
instead
of BeforeAndAfterEachTestData
.
If you need trait stacking, but not access to the TestData
, use
BeforeAndAfterEach
instead.
Trait that when mixed into a Suite
cancels any remaining tests in that
Suite
instance after a test fails.
Trait that when mixed into a Suite
cancels any remaining tests in that
Suite
instance after a test fails.
The intended use case for this trait is if you have a suite of long-running tests that are related such that if one fails, you aren't interested in running the others, you can use this trait to simply cancel any remaining tests, so you need not wait long for them to complete.
Note that this trait only cancels tests in the same Suite
instance, because
it uses a private volatile instance variable as a flag to indicate whether or not a test has failed.
If you are running each test in its own instance, therefore, it would not cancel the
remaining tests, because they would not see the same flag. For this reason, this trait contains
a final implementation of a method defined in OneInstancePerTest
,
to prevent it from being mixed into any class that also mixes in OneInstancePerTest
,
including by mixing in ParallelTestExecution
or a path traits.
Outcome for a test that was canceled, containing an exception describing the cause of the cancelation.
Trait providing class Checkpoint
, which enables multiple assertions
to be performed within a test, with any failures accumulated and reported
together at the end of the test.
Trait providing class Checkpoint
, which enables multiple assertions
to be performed within a test, with any failures accumulated and reported
together at the end of the test.
Because ScalaTest uses exceptions to signal failed assertions, normally execution
of a test will stop as soon as the first failed assertion is encountered. Trait
Checkpoints
provides an option when you want to continue executing
the remainder of the test body, or part of it, even if an assertion has already failed in that test.
To use a Checkpoint
(once you've mixed in or imported the members of trait
Checkpoints
), you first need to create one, like this:
val cp = new Checkpoint
Then give the Checkpoint
assertions to execute by passing them (via a by-name parameter)
to its apply
method, like this:
val (x, y) = (1, 2) cp { x should be < 0 } cp { y should be > 9 }
Both of the above assertions will fail, but it won't be reported yet. The Checkpoint
will execute them
right away, each time its apply
method is invoked. But it will catch the TestFailedExceptions
and
save them, only reporting them later when reportAll
is invoked. Thus, at the end of the test, you must call
reportAll
, like this:
cp.reportAll()
This reportAll
invocation will complete abruptly with a TestFailedException
whose message
includes the message, source file, and line number of each of the checkpointed assertions that previously failed. For example:
1 was not less than 0 (in Checkpoint) at ExampleSpec.scala:12 2 was not greater than 9 (in Checkpoint) at ExampleSpec.scala:13
Make sure you invoke reportAll
before the test completes, otherwise any failures that were detected by the
Checkpoint
will not be reported.
Note that a Checkpoint
will catch and record for later reporting (via reportAll
) exceptions that mix in StackDepth
except for TestCanceledException
, TestRegistrationClosedException
, NotAllowedException
,
and DuplicateTestNameException
. If a block of code passed to a Checkpoint
's apply
method completes
abruptly with any of the StackDepth
exceptions in the previous list, or any non-StackDepth
exception, that invocation
of the apply
method will complete abruptly with the same exception immediately. Unless you put reportAll
in a finally
clause and handle this case, such an unexpected exception will cause you to lose any information about assertions that failed earlier in the test and were
recorded by the Checkpoint
.
Composite Status
that aggregates its completion and failed states of set of other Status
es passed to its constructor.
Composite Status
that aggregates its completion and failed states of set of other Status
es passed to its constructor.
A map of configuration data.
A map of configuration data.
A ConfigMap
can be populated from the Runner
command line via -D
arguments. Runner
passes it to many methods where you can use it to configure your
test runs. For example, Runner
passed the ConfigMap
to:
apply
method of Reporter
s via RunStarting
eventsrun
method of Suite
runNestedSuites
method of Suite
runTests
method of Suite
runTest
method of Suite
withFixture(NoArgTest)
method of Suite
withFixture(OneArgTest)
method of fixture.Suite
beforeEach(TestData)
method of BeforeAndAfterEachTestData
afterEach(TestData)
method of BeforeAndAfterEachTestData
In addition to accessing the ConfigMap
in overriden implementations of the above methods, you can also transform
and pass along a modified ConfigMap
.
A ConfigMap
maps string keys to values of any type, i.e., it is a Map[String, Any]
.
To get a configuration value in a variable of the actual type of that value, therefore, you'll need to perform an unsafe cast. If
this cast fails, you'll get an exception, which so long as the ConfigMap
is used only in tests, will
result in either a failed or canceled test or aborted suite. To give such exceptions nice stack depths and error messages, and to
eliminate the need for using asInstanceOf
in your test code, ConfigMap
provides three
methods for accessing values at expected types.
The getRequired
method returns the value bound to a key cast to a specified type, or throws TestCanceledException
if either the key is not bound or is bound to an incompatible type. Here's an example:
val tempFileName: String = configMap.getRequired[String]("tempFileName")
The getOptional
method returns the value bound to a key cast to a specified type, wrapped in a Some
,
returns None
if the key is not bound, or throws TestCanceledException if the key exists but is
bound to an incompatible type. Here's an example:
val tempFileName: Option[String] = configMap.getOptional[String]("tempFileName")
The getWithDefault
method returns the value bound to a key cast to a specified type,
returns a specified default value if the key is not bound, or throws TestCanceledException if the key exists but is
either not bound or is bound to an incompatible type. Here's an example:
val tempFileName: String = configMap.getWithDefault[String]("tempFileName", "tmp.txt")
Wrapper Suite
that passes an instance of the config map to the constructor of the
wrapped Suite
when run
is invoked.
Wrapper Suite
that passes an instance of the config map to the constructor of the
wrapped Suite
when run
is invoked.
Recommended Usage:
Trait ConfigMapWrapperSuite is primarily intended to be used with the "path" traits, which can't
use the usual approaches to accessing the config map because of the eager manner in which they run tests.
|
Each time run
is invoked on an instance of ConfigMapWrapperSuite
, this
suite will create a new instance of the suite to wrap, passing to the constructor the config map passed to
run
. This way, if the same ConfigMapWrapperSuite
instance is run multiple
times, each time with a different config map, an instance of the wrapped suite will be created
for each config map. In addition to being passed to the wrapped suite's constructor, the config map passed
to the ConfigMapWrapperSuite
's run
method will also be passed to the run
method of the newly created wrapped suite instance.
The config map is accessible inside a Suite
in many ways. It is passed to run
,
runNestedSuites
, runTests
, and runTest
. It is also passed to
withFixture
, accessible via a method on NoArgTest
and
OneArgTest
.
It is passed to an overloaded forms of the beforeEach
and afterEach
methods of trait
BeforeAndAfterEach
, as well as overloaded forms of the beforeAll
and
afterAll
methods of trait BeforeAndAfterAll
. Tests themselves can have information
taken from the config map, or the entire config map, through various means. The config map may be passed into
the test via a ConfigMapFixture
, for example. Class ConfigMapWrapperSuite
represents one more way to get at the config map inside a suite of test: ConfigMapWrapperSuite
will
pass the config map to the constructor of your suite class, bringing it easily into scope for tests and
helper methods alike.
Having the config map passed to the suite constructor might be more convenient in some cases, but in the case
of the org.scalatest.path
traits, it is necessary if a test needs
information from a config map. The reason is that in a path trait, the test code is executed eagerly,
before run
is invoked. The results of the tests are registered when the tests are executed, and those
results are merely reported once run
is invoked. Thus by the time run
has been invoked, it
is too late to get the config map to the tests, which have already been executed. Using a ConfigMapWrapperSuite
solves that problem.
By passing the config map to the constructor, it is available early enough for the running tests to use it.
Here's an example:
import org.scalatest._
@WrapWith(classOf[ConfigMapWrapperSuite]) class ExampleSpec(configMap: ConfigMap) extends path.FunSpec {
describe("A widget database") { it("should contain consistent values") { val dbName = configMap("WidgetDbName") // Can access config map // ... } } }
Sub-trait of Assertions
that override assert
and assume
methods to include
a diagram showing the values of expression in the error message when the assertion or assumption fails.
Sub-trait of Assertions
that override assert
and assume
methods to include
a diagram showing the values of expression in the error message when the assertion or assumption fails.
Here are some examples:
scala> import DiagrammedAssertions._ import DiagrammedAssertions._ scala> assert(a == b || c >= d) org.scalatest.exceptions.TestFailedException: assert(a == b || c >= d) | | | | | | | 1 | 2 | 3 | 4 | | false | false false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert(xs.exists(_ == 4)) org.scalatest.exceptions.TestFailedException: assert(xs.exists(_ == 4)) | | | false List(1, 2, 3) at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert("hello".startsWith("h") && "goodbye".endsWith("y")) org.scalatest.exceptions.TestFailedException: assert("hello".startsWith("h") && "goodbye".endsWith("y")) | | | | | | | "hello" true "h" | "goodbye" false "y" false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert(num.isInstanceOf[Int]) org.scalatest.exceptions.TestFailedException: assert(num.isInstanceOf[Int]) | | 1.0 false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert(Some(2).isEmpty) org.scalatest.exceptions.TestFailedException: assert(Some(2).isEmpty) | | | | 2 false Some(2) at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert(None.isDefined) org.scalatest.exceptions.TestFailedException: assert(None.isDefined) | | None false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert(xs.exists(i => i > 10)) org.scalatest.exceptions.TestFailedException: assert(xs.exists(i => i > 10)) | | | false List(1, 2, 3) at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ...
If the expression passed to assert
or assume
spans more than one line, DiagrammedAssertions
falls
back to the default style of error message, since drawing a diagram would be difficult. Here's an example showing how
DiagrammedAssertions
will treat a multi-line assertion (i.e., you don't get a diagram):
scala> assert("hello".startsWith("h") && | "goodbye".endsWith("y")) org.scalatest.exceptions.TestFailedException: "hello" started with "h", but "goodbye" did not end with "y" at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ...
Also, since an expression diagram essentially represents multi-line ascii art, if a clue string is provided, it appears above the diagram, not after it. It will often also show up in the diagram:
scala> assert(None.isDefined, "Don't do this at home") org.scalatest.exceptions.TestFailedException: Don't do this at home assert(None.isDefined, "Don't do this at home") | | None false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ... scala> assert(None.isDefined, | "Don't do this at home") org.scalatest.exceptions.TestFailedException: Don't do this at home assert(None.isDefined, | | None false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) ...
Trait DiagrammedAssertions
was inspired by Peter Niederwieser's work in Spock and Expecty.
A trait that represent an expression recorded by DiagrammedExprMacro
, which includes the following members:
A trait that represent an expression recorded by DiagrammedExprMacro
, which includes the following members:
DiagrammedExpr
is used by code generated from DiagrammedAssertionsMacro
, it needs to be public
so that the generated code can be compiled. It is expected that ScalaTest users would ever need to use DiagrammedExpr
directly.
A sorter for the events of a run's distributed suites.
A sorter for the events of a run's distributed suites.
This trait is used, for example, when -PS
is passed to Runner
, to sort the
events of distributed suites such that each suite's events are propagated together, with a timeout if an event takes too long.
A sorter for the events of a suite's distributed tests.
A sorter for the events of a suite's distributed tests.
This trait is used, for example, by ParallelTestExecution
to sort the
events of tests back into sequential order, with a timeout if an event takes too long.
Trait whose instances facilitate parallel execution of Suite
s.
Trait whose instances facilitate parallel execution of Suite
s.
An optional Distributor
is passed to the run
method of Suite
. If a
Distributor
is indeed passed, trait Suite
's implementation of run
will
populate that Distributor
with its nested Suite
s (by passing them to the Distributor
's
apply
method) rather than executing the nested Suite
s directly. It is then up to another thread or process
to execute those Suite
s.
If you have a set of nested Suite
s that must be executed sequentially, you can mix in trait
SequentialNestedSuiteExecution
, which overrides runNestedSuites
and
calls super
's runNestedSuites
implementation, passing in None
for the
Distributor
.
Implementations of this trait must be thread safe.
Annotation used to indicate that an otherwise discoverable test class should not be discovered.
Annotation used to indicate that an otherwise discoverable test class should not be discovered.
Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible at runtime. It has been inserted into Scaladoc by pretending it is a trait.
ScalaTest will discover any class that either extends Suite
and has a public, no-arg constructor, or is annotated with
a valid WrapWith
annotation. If you wish to prevent a class from being discovered, simply annotate it
with DoNotDiscover
, like this:
import org.scalatest._ @DoNotDiscover class SetSpec extends FlatSpec { "An empty Set" should "have size 0" in { assert(Set.empty.size === 0) } it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
ScalaTest will run classes annotated with DoNotDiscover
if asked to explicitly, it just won't discover them.
Trait to which markup text tests can be reported.
Trait to which markup text tests can be reported.
Note: Documenter
will be described in more detail in a future 2.0 milestone release. As of this release
you can't see its effects yet.
Trait that contains a markup
method, which can be used to send markup to the Reporter
.
Trait that contains a markup
method, which can be used to send markup to the Reporter
.
Dynamic tags for a run.
Dynamic tags for a run.
Instances of this class are passed to the Filter
constructor to
support running selected suites and tests via dynamic tagging. For example, dynamic tags can be used
to rerun tests that failed previously, or tests selected via a wildcard from Runner
or
the Scala interpreter.
a map from String suite ID to a set of tags for that suite.
a map from String suite ID to a map, whose keys are test names and values the tags for that test.
if either suiteTags
or testTags
is null
Trait that provides an implicit conversion that adds left.value
and right.value
methods
to Either
, which will return the selected value of the Either
if defined,
or throw TestFailedException
if not.
Trait that provides an implicit conversion that adds left.value
and right.value
methods
to Either
, which will return the selected value of the Either
if defined,
or throw TestFailedException
if not.
This construct allows you to express in one statement that an Either
should be left or right
and that its value should meet some expectation. Here's are some examples:
either1.right.value should be > 9 either2.left.value should be ("Muchas problemas")
Or, using assertions instead of matcher expressions:
assert(either1.right.value > 9) assert(either2.left.value === "Muchas problemas")
Were you to simply invoke right.get
or left.get
on the Either
,
if the Either
wasn't defined as expected (e.g., it was a Left
when you expected a Right
), it
would throw a NoSuchElementException
:
val either: Either[String, Int] = Left("Muchas problemas")The
either.right.get should be > 9 // either.right.get throws NoSuchElementException
NoSuchElementException
would cause the test to fail, but without providing a stack depth pointing
to the failing line of test code. This stack depth, provided by TestFailedException
(and a
few other ScalaTest exceptions), makes it quicker for
users to navigate to the cause of the failure. Without EitherValues
, to get
a stack depth exception you would need to make two statements, like this:
val either: Either[String, Int] = Left("Muchas problemas")The
either should be ('right) // throws TestFailedException either.right.get should be > 9
EitherValues
trait allows you to state that more concisely:
val either: Either[String, Int] = Left("Muchas problemas")
either.right.value should be > 9 // either.right.value throws TestFailedException
A case class implementation of java.util.Map.Entry
to make it easier to
test Java Map
s with ScalaTest Matchers.
A case class implementation of java.util.Map.Entry
to make it easier to
test Java Map
s with ScalaTest Matchers.
In Java, java.util.Map
is not a subtype of java.util.Collection
, and does not
actually define an element type. You can ask a Java Map
for an “entry set”
via the entrySet
method, which will return the Map
's key/value pairs
wrapped in a set of java.util.Map.Entry
, but a Map
is not actually
a collection of Entry
. To make Java Map
s easier to work with, however,
ScalaTest matchers allows you to treat a Java Map
as a collection of Entry
,
and defines this convenience implementation of java.util.Map.Entry
.
Here's how you use it:
javaMap should contain (Entry(2, 3)) javaMap should contain oneOf (Entry(2, 3), Entry(3, 4))
the key of this entry
the value of this entry
Superclass for the two outcomes of running a test that contain an exception: Failed
and Canceled
.
Superclass for the two outcomes of running a test that contain an exception: Failed
and Canceled
.
This class provides a toOption
method that returns a Some
wrapping the contained exception, and
an isExceptional
field with the value true
. It's companion object provides an extractor that
enables patterns that match a test that either failed or canceled, as in:
outcome match { case Exceptional(ex) => // handle failed or canceled case case _ => // handle succeeded, pending, or omitted case }
Outcome for a test that failed, containing an exception describing the cause of the failure.
Outcome for a test that failed, containing an exception describing the cause of the failure.
Note: the difference between this Failed
class and the similarly named FailedStatus
object is that an instance of this class indicates one test failed, whereas the FailedStatus
object indicates either one or more tests failed
and/or one or more suites aborted during a run. Both are used as the result type of Suite
lifecycle methods, but Failed
is a possible result of withFixture
, whereas FailedStatus
is a possible result of run
, runNestedSuites
,
runTests
, or runTest
. In short, Failed
is always just about one test, whereas FailedStatus
could be
about something larger: multiple tests or an entire suite.
A suite of tests in which each test represents one scenario of a feature.
A suite of tests in which each test represents one scenario of a feature.
FeatureSpec
is intended for writing tests that are "higher level" than unit tests, for example, integration
tests, functional tests, and acceptance tests. You can use FeatureSpec
for unit testing if you prefer, however.
Recommended Usage:
Class FeatureSpec is primarily intended for acceptance testing, including facilitating the process of programmers working alongside non-programmers to
define the acceptance requirements.
|
Although not required, FeatureSpec
is often used together with GivenWhenThen
to express acceptance requirements
in more detail. Here's an example:
package org.scalatest.examples.featurespecNote: for more information on the calls to
import org.scalatest._
class TVSet { private var on: Boolean = false def isOn: Boolean = on def pressPowerButton() { on = !on } }
class TVSetSpec extends FeatureSpec with GivenWhenThen {
info("As a TV set owner") info("I want to be able to turn the TV on and off") info("So I can watch TV when I want") info("And save energy when I'm not watching TV")
feature("TV power button") { scenario("User presses power button when TV is off") {
Given("a TV set that is switched off") val tv = new TVSet assert(!tv.isOn)
When("the power button is pressed") tv.pressPowerButton()
Then("the TV should switch on") assert(tv.isOn) }
scenario("User presses power button when TV is on") {
Given("a TV set that is switched on") val tv = new TVSet tv.pressPowerButton() assert(tv.isOn)
When("the power button is pressed") tv.pressPowerButton()
Then("the TV should switch off") assert(!tv.isOn) } } }
Given
, When
, and Then
, see the documentation
for trait GivenWhenThen
and the Informers
section below.
A FeatureSpec
contains feature clauses and scenarios. You define a feature clause
with feature
, and a scenario with scenario
. Both
feature
and scenario
are methods, defined in
FeatureSpec
, which will be invoked
by the primary constructor of StackFeatureSpec
.
A feature clause describes a feature of the subject (class or other entity) you are specifying
and testing. In the previous example,
the subject under specification and test is a Set. The feature being specified and tested is
the behavior of a Set when it is empty and head is invoked. With each scenario you provide a
string (the spec text) that specifies the behavior of the subject for
one scenario in which the feature may be used, and a block of code that tests that behavior.
You place the spec text between the parentheses, followed by the test code between curly
braces. The test code will be wrapped up as a function passed as a by-name parameter to
scenario
, which will register the test for later execution.
A FeatureSpec
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Scenarios can only be registered with the scenario
method while the FeatureSpec
is
in its registration phase. Any attempt to register a scenario after the FeatureSpec
has
entered its ready phase, i.e., after run
has been invoked on the FeatureSpec
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using FeatureSpec
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
Each scenario represents one test. The name of the test is the spec text passed to the scenario
method.
The feature name does not appear as part of the test name. In a FeatureSpec
, therefore, you must take care
to ensure that each test has a unique name (in other words, that each scenario
has unique spec text).
When you run a FeatureSpec
, it will send Formatter
s in the events it sends to the
Reporter
. ScalaTest's built-in reporters will report these events in such a way
that the output is easy to read as an informal specification of the subject being tested.
For example, were you to run TVSetSpec
from within the Scala interpreter:
scala> new TVSetSpec executeYou would see:
TVSetSpec:
As a TV set owner
I want to be able to turn the TV on and off
So I can watch TV when I want
And save energy when I'm not watching TV
Feature: TV power button
Scenario: User presses power button when TV is off
Given a TV set that is switched off
When the power button is pressed
Then the TV should switch on
Scenario: User presses power button when TV is on
Given a TV set that is switched on
When the power button is pressed
Then the TV should switch off
Or, to run just the “Feature: TV power button Scenario: User presses power button when TV is on
” method, you could pass that test's name, or any unique substring of the
name, such as "TV is on"
. Here's an example:
scala> new TVSetSpec execute "TV is on"
TVSetSpec:
As a TV set owner
I want to be able to turn the TV on and off
So I can watch TV when I want
And save energy when I'm not watching TV
Feature: TV power button
Scenario: User presses power button when TV is on
Given a TV set that is switched on
When the power button is pressed
Then the TV should switch off
You can also pass to execute
a config map of key-value
pairs, which will be passed down into suites and tests, as well as other parameters that configure the run itself.
For more information on running in the Scala interpreter, see the documentation for execute
(below) and the
ScalaTest shell.
The execute
method invokes a run
method that takes two
parameters. This run
method, which actually executes the suite, will usually be invoked by a test runner, such
as run
, tools.Runner
, a build tool, or an IDE.
Note: Trait FeatureSpec
's syntax is in part inspired by Cucumber, a Ruby BDD framework.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, FeatureSpec
provides registration
methods that start with ignore
instead of scenario
. For example, to temporarily
disable the test named addition
, just change “scenario
” into “ignore
,” like this:
package org.scalatest.examples.featurespec.ignoreIf you run this version of
import org.scalatest.FeatureSpec
class TVSet { private var on: Boolean = false def isOn: Boolean = on def pressPowerButton() { on = !on } }
class TVSetSpec extends FeatureSpec {
feature("TV power button") { ignore("User presses power button when TV is off") { val tv = new TVSet assert(!tv.isOn) tv.pressPowerButton() assert(tv.isOn) }
scenario("User presses power button when TV is on") { val tv = new TVSet tv.pressPowerButton() assert(tv.isOn) tv.pressPowerButton() assert(!tv.isOn) } } }
SetSpec
with:
scala> new TVSetSpec executeIt will run only the second scenario and report that the first scenario was ignored:
TVSetSpec: Feature: TV power button Scenario: User presses power button when TV is off !!! IGNORED !!! Scenario: User presses power button when TV is on== Informers == One of the parameters to
FeatureSpec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the default reporting done by FeatureSpec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via its apply
method.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
One use case for the Informer
is to pass more information about a scenario to the reporter. For example,
the GivenWhenThen
trait provides methods that use the implicit info
provided by FeatureSpec
to pass such information to the reporter. You can see this in action in the initial example of this trait's documentation.
== Documenters ==
FeatureSpec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example FlatSpec
that uses markup
:
package org.scalatest.examples.featurespec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSpec extends FeatureSpec with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
feature("An element can be added to an empty mutable Set") { scenario("When an element is added to an empty mutable Set") { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.featurespec.noteBecause
import collection.mutable import org.scalatest._
class SetSpec extends FeatureSpec {
feature("An element can be added to an empty mutable Set") { scenario("When an element is added to an empty mutable Set") {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSpec: Feature: An element can be added to an empty mutable Set + notes are sent immediately + alerts are also sent immediately Scenario: When an element is added to an empty mutable Set info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run. (In other words,
the code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality, has not yet been implemented.
You can mark tests as pending in a FeatureSpec
like this:
package org.scalatest.examples.featurespec.pending(Note: "
import org.scalatest.FeatureSpec
class TVSet { private var on: Boolean = false def isOn: Boolean = on def pressPowerButton() { on = !on } }
class TVSetSpec extends FeatureSpec {
feature("TV power button") {
scenario("User presses power button when TV is off") (pending)
scenario("User presses power button when TV is on") { val tv = new TVSet tv.pressPowerButton() assert(tv.isOn) tv.pressPowerButton() assert(!tv.isOn) } } }
(pending)
" is the body of the test. Thus the test contains just one statement, an invocation
of the pending
method, which throws TestPendingException
.)
If you run this version of TVSetSpec
with:
scala> new TVSetSpec executeIt will run both tests, but report that
When empty should have size 0
is pending. You'll see:
TVSetSpec: Feature: TV power button Scenario: User presses power button when TV is off (pending) Scenario: User presses power button when TV is onOne difference between an ignored test and a pending one is that an ignored test is intended to be used during a significant refactorings of the code under test, when tests break and you don't want to spend the time to fix all of them immediately. You can mark some of those broken tests as ignored temporarily, so that you can focus the red bar on just failing tests you actually want to fix immediately. Later you can go back and fix the ignored tests. In other words, by ignoring some failing tests temporarily, you can more easily notice failed tests that you actually want to fix. By contrast, a pending test is intended to be used before a test and/or the code under test is written. Pending indicates you've decided to write a test for a bit of behavior, but either you haven't written the test yet, or have only written part of it, or perhaps you've written the test but don't want to implement the behavior it tests until after you've implemented a different bit of behavior you realized you need first. Thus ignored tests are designed to facilitate refactoring of existing code whereas pending tests are designed to facilitate the creation of new code. One other difference between ignored and pending tests is that ignored tests are implemented as a test tag that is excluded by default. Thus an ignored test is never executed. By contrast, a pending test is implemented as a test that throws
TestPendingException
(which is what calling the pending
method does). Thus
the body of pending tests are executed up until they throw TestPendingException
. The reason for this difference
is that it enables your unfinished test to send InfoProvided
messages to the reporter before it completes
abruptly with TestPendingException
, as shown in the previous example on Informer
s
that used the GivenWhenThen
trait. For example, the following snippet in a FeatureSpec
:
package org.scalatest.examples.featurespec.infopendingWould yield the following output when run in the interpreter:
import org.scalatest._
class TVSet { private var on: Boolean = false
def isOn: Boolean = on
def pressPowerButton() { on = !on } }
class TVSetSpec extends FeatureSpec with GivenWhenThen {
info("As a TV set owner") info("I want to be able to turn the TV on and off") info("So I can watch TV when I want") info("And save energy when I'm not watching TV")
feature("TV power button") { scenario("User presses power button when TV is off") { Given("a TV that is switched off") When("the power button is pressed") Then("the TV should switch on") pending }
scenario("User presses power button when TV is on") { Given("a TV that is switched on") When("the power button is pressed") Then("the TV should switch off") pending } } }
scala> new TVSetSpec execute TVSetSpec: As a TV set owner I want to be able to turn the TV on and off So I can watch TV when I want And save energy when I'm not watching TV Feature: TV power button Scenario: User presses power button when TV is off (pending) Given a TV that is switched off When the power button is pressed Then the TV should switch on Scenario: User presses power button when TV is on (pending) Given a TV that is switched on When the power button is pressed Then the TV should switch off== Tagging tests == A
FeatureSpec
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a FeatureSpec
, groups of tests can
optionally be included and/or excluded. To tag a FeatureSpec
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for FeatureSpec
s like this:
package org.scalatest.examples.featurespec.taggingGiven these definitions, you could place
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
FeatureSpec
tests into groups like this:
import org.scalatest.FeatureSpecThis code marks both tests with the
class TVSet { private var on: Boolean = false def isOn: Boolean = on def pressPowerButton() { on = !on } }
class TVSetSpec extends FeatureSpec {
feature("TV power button") { scenario("User presses power button when TV is off", SlowTest) { val tv = new TVSet assert(!tv.isOn) tv.pressPowerButton() assert(tv.isOn) }
scenario("User presses power button when TV is on", SlowTest, DbTest) { val tv = new TVSet tv.pressPowerButton() assert(tv.isOn) tv.pressPowerButton() assert(!tv.isOn) } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
It is recommended, though not required, that you create a corresponding tag annotation when you
create a Tag
object. A tag annotation allows you to tag all the tests of a FeatureSpec
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.featurespec.getfixtureThe “
import org.scalatest.FeatureSpec import collection.mutable.ListBuffer
class ExampleSpec extends FeatureSpec {
def fixture = new { val builder = new StringBuilder("ScalaTest is designed to ") val buffer = new ListBuffer[String] }
feature("Simplicity") { scenario("User needs to read test code written by others") { val f = fixture f.builder.append("encourage clear code!") assert(f.builder.toString === "ScalaTest is designed to encourage clear code!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
scenario("User needs to understand what the tests are doing") { val f = fixture f.builder.append("be easy to reason about!") assert(f.builder.toString === "ScalaTest is designed to be easy to reason about!") assert(f.buffer.isEmpty) } } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.featurespec.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.FeatureSpec
class ExampleSpec extends FeatureSpec {
trait Builder { val builder = new StringBuilder("ScalaTest is designed to ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is", "designed", "to") }
feature("Simplicity") { // This test needs the StringBuilder fixture scenario("User needs to read test code written by others") { new Builder { builder.append("encourage clear code!") assert(builder.toString === "ScalaTest is designed to encourage clear code!") } }
// This test needs the ListBuffer[String] fixture scenario("User needs to understand what the tests are doing") { new Buffer { buffer += ("be", "easy", "to", "reason", "about!") assert(buffer === List("ScalaTest", "is", "designed", "to", "be", "easy", "to", "reason", "about!")) } }
// This test needs both the StringBuilder and ListBuffer scenario("User needs to write tests") { new Builder with Buffer { builder.append("be easy to learn!") buffer += ("be", "easy", "to", "remember", "how", "to", "write!") assert(builder.toString === "ScalaTest is designed to be easy to learn!") assert(buffer === List("ScalaTest", "is", "designed", "to", "be", "easy", "to", "remember", "how", "to", "write!")) } } } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. That is to say, instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
send that information to the reporter:
package org.scalatest.examples.featurespec.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSpec extends FeatureSpec {
override def withFixture(test: NoArgTest) = {
super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
scenario("This scenario should succeed") { assert(1 + 1 === 2) }
scenario("This scenario should fail") { assert(1 + 1 === 3) } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSpec execute ExampleSpec: Scenario: This scenario should succeed Scenario: This scenario should fail *** FAILED *** 2 did not equal 3 (Note that the:115) + Dir snapshot: hello.txt, world.txt
NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
package org.scalatest.examples.featurespec.loanfixtureAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
import java.util.concurrent.ConcurrentHashMap
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.FeatureSpec import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSpec extends FeatureSpec {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is designed to ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is designed to ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
feature("Simplicity") { // This test needs the file fixture scenario("User needs to read test code written by others") { withFile { (file, writer) => writer.write("encourage clear code!") writer.flush() assert(file.length === 46) } } // This test needs the database fixture scenario("User needs to understand what the tests are doing") { withDatabase { db => db.append("be easy to reason about!") assert(db.toString === "ScalaTest is designed to be easy to reason about!") } } // This test needs both the file and the database scenario("User needs to write tests") { withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("be easy to learn!") writer.write("be easy to remember how to write!") writer.flush() assert(db.toString === "ScalaTest is designed to be easy to learn!") assert(file.length === 58) } } } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.FeatureSpec
and overriding withFixture(OneArgTest)
.
Each test in a fixture.FeatureSpec
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. In other words, instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.featurespec.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSpec extends fixture.FeatureSpec {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = {
// create the fixture val file = File.createTempFile("hello", "world") val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is designed to be ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
feature("Simplicity") { scenario("User needs to read test code written by others") { f => f.writer.write("encourage clear code!") f.writer.flush() assert(f.file.length === 49) }
scenario("User needs to understand what the tests are doing") { f => f.writer.write("be easy to reason about!") f.writer.flush() assert(f.file.length === 52) } } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.FeatureSpec
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.featurespec.beforeandafterNote that the only way
import org.scalatest._ import collection.mutable.ListBuffer
class ExampleSpec extends FeatureSpec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is designed to ") }
after { builder.clear() buffer.clear() }
feature("Simplicity") { scenario("User needs to read test code written by others") { builder.append("encourage clear code!") assert(builder.toString === "ScalaTest is designed to encourage clear code!") assert(buffer.isEmpty) buffer += "sweet" }
scenario("User needs to understand what the tests are doing") { builder.append("be easy to reason about!") assert(builder.toString === "ScalaTest is designed to be easy to reason about!") assert(buffer.isEmpty) } } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.featurespec.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is designed to ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSpec extends FeatureSpec with Builder with Buffer {
feature("Simplicity") { scenario("User needs to read test code written by others") { builder.append("encourage clear code!") assert(builder.toString === "ScalaTest is designed to encourage clear code!") assert(buffer.isEmpty) buffer += "clear" }
scenario("User needs to understand what the tests are doing") { builder.append("be easy to reason about!") assert(builder.toString === "ScalaTest is designed to be easy to reason about!") assert(buffer.isEmpty) buffer += "easy" } } }
Builder
and Buffer
traits, ExampleSuite
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Suite extends Suite with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Suite extends Suite with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.featurespec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is designed to ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally buffer.clear() } }
class ExampleSpec extends FeatureSpec with Builder with Buffer {
feature("Simplicity") { scenario("User needs to read test code written by others") { builder.append("encourage clear code!") assert(builder.toString === "ScalaTest is designed to encourage clear code!") assert(buffer.isEmpty) buffer += "clear" }
scenario("User needs to understand what the tests are doing") { builder.append("be easy to reason about!") assert(builder.toString === "ScalaTest is designed to be easy to reason about!") assert(buffer.isEmpty) buffer += "easy" } } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared scenarios ==
Sometimes you may want to run the same test code on different fixture objects. In other words, you may want to write tests that are "shared"
by different fixture objects.
To accomplish this in a FeatureSpec
, you first place shared tests (i.e., shared scenarios) in
behavior functions. These behavior functions will be
invoked during the construction phase of any FeatureSpec
that uses them, so that the scenarios they contain will
be registered as scenarios in that FeatureSpec
.
For example, given this stack class:
import scala.collection.mutable.ListBufferYou may want to test the
class Stack[T] {
val MAX = 10 private val buf = new ListBuffer[T]
def push(o: T) { if (!full) buf.prepend(o) else throw new IllegalStateException("can't push onto a full stack") }
def pop(): T = { if (!empty) buf.remove(0) else throw new IllegalStateException("can't pop an empty stack") }
def peek: T = { if (!empty) buf(0) else throw new IllegalStateException("can't pop an empty stack") }
def full: Boolean = buf.size == MAX def empty: Boolean = buf.size == 0 def size = buf.size
override def toString = buf.mkString("Stack(", ", ", ")") }
Stack
class in different states: empty, full, with one item, with one item less than capacity,
etc. You may find you have several scenarios that make sense any time the stack is non-empty. Thus you'd ideally want to run
those same scenarios for three stack fixture objects: a full stack, a stack with a one item, and a stack with one item less than
capacity. With shared tests, you can factor these scenarios out into a behavior function, into which you pass the
stack fixture to use when running the tests. So in your FeatureSpec
for stack, you'd invoke the
behavior function three times, passing in each of the three stack fixtures so that the shared scenarios are run for all three fixtures.
You can define a behavior function that encapsulates these shared scenarios inside the FeatureSpec
that uses them. If they are shared
between different FeatureSpec
s, however, you could also define them in a separate trait that is mixed into
each FeatureSpec
that uses them.
For example, here the nonEmptyStack
behavior function (in this case, a
behavior method) is defined in a trait along with another
method containing shared scenarios for non-full stacks:
import org.scalatest.FeatureSpec import org.scalatest.GivenWhenThen import org.scalatestexamples.helpers.StackGiven these behavior functions, you could invoke them directly, but
trait FeatureSpecStackBehaviors { this: FeatureSpec with GivenWhenThen =>
def nonEmptyStack(createNonEmptyStack: => Stack[Int], lastItemAdded: Int) {
scenario("empty is invoked on this non-empty stack: " + createNonEmptyStack.toString) {
Given("a non-empty stack") val stack = createNonEmptyStack
When("empty is invoked on the stack") Then("empty returns false") assert(!stack.empty) }
scenario("peek is invoked on this non-empty stack: " + createNonEmptyStack.toString) {
Given("a non-empty stack") val stack = createNonEmptyStack val size = stack.size
When("peek is invoked on the stack") Then("peek returns the last item added") assert(stack.peek === lastItemAdded)
And("the size of the stack is the same as before") assert(stack.size === size) }
scenario("pop is invoked on this non-empty stack: " + createNonEmptyStack.toString) {
Given("a non-empty stack") val stack = createNonEmptyStack val size = stack.size
When("pop is invoked on the stack") Then("pop returns the last item added") assert(stack.pop === lastItemAdded)
And("the size of the stack one less than before") assert(stack.size === size - 1) } }
def nonFullStack(createNonFullStack: => Stack[Int]) {
scenario("full is invoked on this non-full stack: " + createNonFullStack.toString) {
Given("a non-full stack") val stack = createNonFullStack
When("full is invoked on the stack") Then("full returns false") assert(!stack.full) }
scenario("push is invoked on this non-full stack: " + createNonFullStack.toString) {
Given("a non-full stack") val stack = createNonFullStack val size = stack.size
When("push is invoked on the stack") stack.push(7)
Then("the size of the stack is one greater than before") assert(stack.size === size + 1)
And("the top of the stack contains the pushed value") assert(stack.peek === 7) } } }
FeatureSpec
offers a DSL for the purpose,
which looks like this:
scenariosFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) scenariosFor(nonFullStack(stackWithOneItem))If you prefer to use an imperative style to change fixtures, for example by mixing in
BeforeAndAfterEach
and
reassigning a stack
var
in beforeEach
, you could write your behavior functions
in the context of that var
, which means you wouldn't need to pass in the stack fixture because it would be
in scope already inside the behavior function. In that case, your code would look like this:
scenariosFor(nonEmptyStack) // assuming lastValuePushed is also in scope inside nonEmptyStack
scenariosFor(nonFullStack)
The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example:
import org.scalatest.FeatureSpec import org.scalatest.GivenWhenThen import org.scalatestexamples.helpers.StackIf you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, you'll see:
class StackFeatureSpec extends FeatureSpec with GivenWhenThen with FeatureSpecStackBehaviors {
// Stack fixture creation methods def emptyStack = new Stack[Int]
def fullStack = { val stack = new Stack[Int] for (i <- 0 until stack.MAX) stack.push(i) stack }
def stackWithOneItem = { val stack = new Stack[Int] stack.push(9) stack }
def stackWithOneItemLessThanCapacity = { val stack = new Stack[Int] for (i <- 1 to 9) stack.push(i) stack }
val lastValuePushed = 9
feature("A Stack is pushed and popped") {
scenario("empty is invoked on an empty stack") {
Given("an empty stack") val stack = emptyStack
When("empty is invoked on the stack") Then("empty returns true") assert(stack.empty) }
scenario("peek is invoked on an empty stack") {
Given("an empty stack") val stack = emptyStack
When("peek is invoked on the stack") Then("peek throws IllegalStateException") intercept[IllegalStateException] { stack.peek } }
scenario("pop is invoked on an empty stack") {
Given("an empty stack") val stack = emptyStack
When("pop is invoked on the stack") Then("pop throws IllegalStateException") intercept[IllegalStateException] { emptyStack.pop } }
scenariosFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) scenariosFor(nonFullStack(stackWithOneItem))
scenariosFor(nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed)) scenariosFor(nonFullStack(stackWithOneItemLessThanCapacity))
scenario("full is invoked on a full stack") {
Given("an full stack") val stack = fullStack
When("full is invoked on the stack") Then("full returns true") assert(stack.full) }
scenariosFor(nonEmptyStack(fullStack, lastValuePushed))
scenario("push is invoked on a full stack") {
Given("an full stack") val stack = fullStack
When("push is invoked on the stack") Then("push throws IllegalStateException") intercept[IllegalStateException] { stack.push(10) } } } }
scala> (new StackFeatureSpec).execute()
Feature: A Stack is pushed and popped
Scenario: empty is invoked on an empty stack
Given an empty stack
When empty is invoked on the stack
Then empty returns true
Scenario: peek is invoked on an empty stack
Given an empty stack
When peek is invoked on the stack
Then peek throws IllegalStateException
Scenario: pop is invoked on an empty stack
Given an empty stack
When pop is invoked on the stack
Then pop throws IllegalStateException
Scenario: empty is invoked on this non-empty stack: Stack(9)
Given a non-empty stack
When empty is invoked on the stack
Then empty returns false
Scenario: peek is invoked on this non-empty stack: Stack(9)
Given a non-empty stack
When peek is invoked on the stack
Then peek returns the last item added
And the size of the stack is the same as before
Scenario: pop is invoked on this non-empty stack: Stack(9)
Given a non-empty stack
When pop is invoked on the stack
Then pop returns the last item added
And the size of the stack one less than before
Scenario: full is invoked on this non-full stack: Stack(9)
Given a non-full stack
When full is invoked on the stack
Then full returns false
Scenario: push is invoked on this non-full stack: Stack(9)
Given a non-full stack
When push is invoked on the stack
Then the size of the stack is one greater than before
And the top of the stack contains the pushed value
Scenario: empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Given a non-empty stack
When empty is invoked on the stack
Then empty returns false
Scenario: peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Given a non-empty stack
When peek is invoked on the stack
Then peek returns the last item added
And the size of the stack is the same as before
Scenario: pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Given a non-empty stack
When pop is invoked on the stack
Then pop returns the last item added
And the size of the stack one less than before
Scenario: full is invoked on this non-full stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Given a non-full stack
When full is invoked on the stack
Then full returns false
Scenario: push is invoked on this non-full stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Given a non-full stack
When push is invoked on the stack
Then the size of the stack is one greater than before
And the top of the stack contains the pushed value
Scenario: full is invoked on a full stack
Given an full stack
When full is invoked on the stack
Then full returns true
Scenario: empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
Given a non-empty stack
When empty is invoked on the stack
Then empty returns false
Scenario: peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
Given a non-empty stack
When peek is invoked on the stack
Then peek returns the last item added
And the size of the stack is the same as before
Scenario: pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
Given a non-empty stack
When pop is invoked on the stack
Then pop returns the last item added
And the size of the stack one less than before
Scenario: push is invoked on a full stack
Given an full stack
When push is invoked on the stack
Then push throws IllegalStateException
One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name.
If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime
complaining that multiple tests are being registered with the same test name.
In a FeatureSpec
there is no nesting construct analogous to FunSpec
's describe
clause.
Therefore, you need to do a bit of
extra work to ensure that the test names are unique. If a duplicate test name problem shows up in a
FeatureSpec
, you'll need to pass in a prefix or suffix string to add to each test name. You can pass this string
the same way you pass any other data needed by the shared tests, or just call toString
on the shared fixture object.
This is the approach taken by the previous FeatureSpecStackBehaviors
example.
Given this FeatureSpecStackBehaviors
trait, calling it with the stackWithOneItem
fixture, like this:
scenariosFor(nonEmptyStack(stackWithOneItem, lastValuePushed))yields test names: -
empty is invoked on this non-empty stack: Stack(9)
- peek is invoked on this non-empty stack: Stack(9)
- pop is invoked on this non-empty stack: Stack(9)
Whereas calling it with the stackWithOneItemLessThanCapacity
fixture, like this:
scenariosFor(nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed))yields different test names: -
empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Implementation trait for class FeatureSpec
, which represents
a suite of tests in which each test represents one scenario of a
feature.
Implementation trait for class FeatureSpec
, which represents
a suite of tests in which each test represents one scenario of a
feature.
FeatureSpec
is a class, not a
trait, to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the
behavior of FeatureSpec
into some other class, you can use this
trait instead, because class FeatureSpec
does nothing more than
extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed
overview of FeatureSpec
.
Filter whose apply
method determines which of the passed tests to run and ignore based on tags to include and exclude passed as
as class parameters.
Filter whose apply
method determines which of the passed tests to run and ignore based on tags to include and exclude passed as
as class parameters.
This class handles the org.scalatest.Ignore
tag specially, in that its apply
method indicates which
tests should be ignored based on whether they are tagged with org.scalatest.Ignore
. If
"org.scalatest.Ignore"
is not passed in the tagsToExclude
set, it will be implicitly added. However, if the
tagsToInclude
option is defined, and the contained set does not include "org.scalatest.Ignore"
, then only those tests
that are both tagged with org.scalatest.Ignore
and at least one of the tags in the tagsToInclude
set
will be included in the result of apply
and marked as ignored (so long as the test is not also
marked with a tag other than org.scalatest.Ignore
that is a member of the tagsToExclude
set. For example, if SlowAsMolasses
is a member of the tagsToInclude
set and a
test is tagged with both org.scalatest.Ignore
and SlowAsMolasses
, and
SlowAsMolasses
appears in the tagsToExclude
set, the
SlowAsMolasses
tag will "overpower" the org.scalatest.Ignore
tag, and the
test will be filtered out entirely rather than being ignored.
if tagsToInclude
is defined, but contains an empty set
if either tagsToInclude
or tagsToExclude
are null
Annotation used to mark a trait or class as defining a testing style that has a org.scalatest.finders.Finder
implementation,
which IDEs and other tools can use to discover tests and scopes.
Annotation used to mark a trait or class as defining a testing style that has a org.scalatest.finders.Finder
implementation,
which IDEs and other tools can use to discover tests and scopes.
Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible at runtime. It has been inserted into Scaladoc by pretending it is a trait.
This annotation is used to enable different styles of testing, including both native ScalaTest styles and custom user-created styles, to have rich IDE support. The "Finder API" is released separately from ScalaTest proper, because it is only used by tools such as IDEs.
Facilitates a “behavior-driven” style of development (BDD), in which tests are combined with text that specifies the behavior the tests verify.
Facilitates a “behavior-driven” style of development (BDD), in which tests are combined with text that specifies the behavior the tests verify.
Recommended Usage:
Class FlatSpec is a good first step for teams wishing to move from xUnit to BDD, because its structure is flat like xUnit, so simple and familiar,
but the test names must be written in a specification style: “X should Y,” “A must B,” etc.
|
Trait FlatSpec
is so named because
your specification text and tests line up flat against the left-side indentation level, with no nesting needed.
Here's an example FlatSpec
:
package org.scalatest.examples.flatspecNote: you can use
import org.scalatest.FlatSpec
class SetSpec extends FlatSpec {
behavior of "An empty Set"
it should "have size 0" in { assert(Set.empty.size === 0) }
it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
must
or can
as well as should
in a FlatSpec
. For example, instead of
it should "pop
..., you could write it must "pop
... or it can "pop
....
Instead of using a behavior of
clause, you can alternatively use a shorthand syntax in which you replace
the first it
with the subject string, like this:
package org.scalatest.examples.flatspecRunning either of the two previous three versions of
import org.scalatest.FlatSpec
class SetSpec extends FlatSpec {
"An empty Set" should "have size 0" in { assert(Set.empty.size === 0) }
it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
SetSpec
in the Scala interpreter would yield:
An empty Set
- should have size 0
- should produce NoSuchElementException when head is invoked
In a FlatSpec
you write a one (or more) sentence specification for each bit of behavior you wish to
specify and test. Each specification sentence has a
"subject," which is sometimes called the system under test (or SUT). The
subject is the entity being specified and tested and also serves as the subject of the sentences you write for each test.
Often you will want to write multiple tests for the same subject. In a FlatSpec
, you name the subject once,
with a behavior of
clause or its shorthand, then write tests for that subject with it should
/must
/can "do something"
phrases.
Each it
refers to the most recently declared subject. For example, the four tests shown in this snippet are all testing
a stack that contains one item:
behavior of "A Stack (with one item)"The same is true if the tests are written using the shorthand notation:
it should "be non-empty" in {}
it should "return the top item on peek" in {}
it should "not remove the top item on peek" in {}
it should "remove the top item on pop" in {}
"A Stack (with one item)" should "be non-empty" in {}In a
it should "return the top item on peek" in {}
it should "not remove the top item on peek" in {}
it should "remove the top item on pop" in {}
FlatSpec
, therefore, to figure out what "it
" means, you just scan vertically until you find the most
recent use of behavior of
or the shorthand notation.
Because sometimes the subject could be plural, you can alternatively use they
instead of it
:
"The combinators" should "be easy to learn" in {}A
they should "be efficient" in {}
they should "do something cool" in {}
FlatSpec
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Tests can only be registered while the FlatSpec
is
in its registration phase. Any attempt to register a test after the FlatSpec
has
entered its ready phase, i.e., after run
has been invoked on the FlatSpec
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using FlatSpec
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, FlatSpec
provides a method
ignore
that can be used instead of it
or they
to register a test. For example, to temporarily
disable the test with the name "An empty Set should produce NoSuchElementException when head is invoked"
, just
change “it
” into “ignore
,” like this:
package org.scalatest.examples.flatspec.ignoreIf you run this version of
import org.scalatest.FlatSpec
class SetSpec extends FlatSpec {
"An empty Set" should "have size 0" in { assert(Set.empty.size === 0) }
ignore should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
SetSpec
with:
scala> new SetSpec executeIt will run only the first test and report that the second test was ignored:
An empty Set - should have size 0 - should produce NoSuchElementException when head is invoked !!! IGNORED !!!When using shorthand notation, you won't have an
it
to change into ignore
for
the first test of each new subject. To ignore such tests, you must instead change in
to ignore
.
For example, to temporarily disable the test with the name "An empty Set should have size 0"
,
change “in
” into “ignore
” like this:
package org.scalatest.examples.flatspec.ignoreafterIf you run this version of
import org.scalatest.FlatSpec
class SetSpec extends FlatSpec {
"An empty Set" should "have size 0" ignore { assert(Set.empty.size === 0) }
it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
StackSpec
with:
scala> new SetSpec executeIt will run only the second test and report that the first test was ignored:
An empty Set - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invokedIf you wish to temporarily ignore an entire suite of tests, you can annotate the test class with
@Ignore
, like this:
package org.scalatest.examples.flatspec.ignoreallWhen you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the
import org.scalatest._
@Ignore class SetSpec extends FlatSpec {
"An empty Set" should "have size 0" in { assert(Set.empty.size === 0) }
it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
SetSpec
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSpec
in the Scala interpreter, you'll see:
scala> new SetSpec execute SetSpec: An empty Set - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invoked !!! IGNORED !!!Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored class visible, to encourage the developers to eventually fix and “un-ignore” it. If you want to prevent a class from being discovered at all, use the
DoNotDiscover
annotation instead.
== Informers ==
One of the parameters to FlatSpec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by FlatSpec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via its apply
method.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
One use case for the Informer
is to pass more information about a specification to the reporter. For example,
the GivenWhenThen
trait provides methods that use the implicit info
provided by FlatSpec
to pass such information to the reporter. Here's an example:
package org.scalatest.examples.flatspec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends FlatSpec with GivenWhenThen {
"A mutable Set" should "allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } }
FlatSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
SetSpec:
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
== Documenters ==
FlatSpec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example FlatSpec
that uses markup
:
package org.scalatest.examples.flatspec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSpec extends FlatSpec with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
"A mutable Set" should "allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.flatspec.noteBecause
import collection.mutable import org.scalatest._
class SetSpec extends FlatSpec {
"A mutable Set" should "allow an element to be added" in {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSpec: A mutable Set + notes are sent immediately + alerts are also sent immediately - should allow an element to be added + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run. (In other words,
the code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality it is intended to test, has not yet been implemented.
You can mark tests as pending in FlatSpec
like this:
package org.scalatest.examples.flatspec.pendingIf you run this version of
import org.scalatest._
class SetSpec extends FlatSpec {
"An empty Set" should "have size 0" in (pending)
it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
FlatSpec
with:
scala> new SetSpec executeIt will run both tests but report that
An empty Set should have size 0
is pending. You'll see:
An empty Set - should have size 0 (pending) - should produce NoSuchElementException when head is invokedOne difference between an ignored test and a pending one is that an ignored test is intended to be used during a significant refactorings of the code under test, when tests break and you don't want to spend the time to fix all of them immediately. You can mark some of those broken tests as ignored temporarily, so that you can focus the red bar on just failing tests you actually want to fix immediately. Later you can go back and fix the ignored tests. In other words, by ignoring some failing tests temporarily, you can more easily notice failed tests that you actually want to fix. By contrast, a pending test is intended to be used before a test and/or the code under test is written. Pending indicates you've decided to write a test for a bit of behavior, but either you haven't written the test yet, or have only written part of it, or perhaps you've written the test but don't want to implement the behavior it tests until after you've implemented a different bit of behavior you realized you need first. Thus ignored tests are designed to facilitate refactoring of existing code whereas pending tests are designed to facilitate the creation of new code. One other difference between ignored and pending tests is that ignored tests are implemented as a test tag that is excluded by default. Thus an ignored test is never executed. By contrast, a pending test is implemented as a test that throws
TestPendingException
(which is what calling the pending
method does). Thus
the body of pending tests are executed up until they throw TestPendingException
. The reason for this difference
is that it enables your unfinished test to send InfoProvided
messages to the reporter before it completes
abruptly with TestPendingException
, as shown in the previous example on Informer
s
that used the GivenWhenThen
trait. For example, the following snippet in a FlatSpec
:
"The Scala language" must "add correctly" in { Given("two integers") When("they are added") Then("the result is the sum of the two numbers") pending } // ...Would yield the following output when run in the interpreter:
The Scala language - must add correctly (pending) + Given two integers + When they are added + Then the result is the sum of the two numbers== Tagging tests == A
FlatSpec
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a FlatSpec
, groups of tests can
optionally be included and/or excluded. To tag a FlatSpec
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for FlatSpec
s like this:
package org.scalatest.examples.flatspec.taggingGiven these definitions, you could place
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
FlatSpec
tests into groups like this:
import org.scalatest.FlatSpecThis code marks both tests with the
class SetSpec extends FlatSpec {
behavior of "An empty Set"
it should "have size 0" taggedAs(SlowTest) in { assert(Set.empty.size === 0) }
it should "produce NoSuchElementException when head is invoked" taggedAs(SlowTest, DbTest) in { intercept[NoSuchElementException] { Set.empty.head } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
It is recommended, though not required, that you create a corresponding tag annotation when you
create a Tag
object. A tag annotation allows you to tag all the tests of a FlatSpec
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.flatspec.getfixtureThe “
import org.scalatest.FlatSpec import collection.mutable.ListBuffer
class ExampleSpec extends FlatSpec {
def fixture = new { val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String] }
"Testing" should "be easy" in { val f = fixture f.builder.append("easy!") assert(f.builder.toString === "ScalaTest is easy!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
it should "be fun" in { val f = fixture f.builder.append("fun!") assert(f.builder.toString === "ScalaTest is fun!") assert(f.buffer.isEmpty) } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, if you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.flatspec.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.FlatSpec
class ExampleSpec extends FlatSpec {
trait Builder { val builder = new StringBuilder("ScalaTest is ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is") }
// This test needs the StringBuilder fixture "Testing" should "be productive" in new Builder { builder.append("productive!") assert(builder.toString === "ScalaTest is productive!") }
// This test needs the ListBuffer[String] fixture "Test code" should "be readable" in new Buffer { buffer += ("readable!") assert(buffer === List("ScalaTest", "is", "readable!")) }
// This test needs both the StringBuilder and ListBuffer it should "be clear and concise" in new Builder with Buffer { builder.append("clear!") buffer += ("concise!") assert(builder.toString === "ScalaTest is clear!") assert(buffer === List("ScalaTest", "is", "concise!")) } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. That is to say, instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
send that information to the reporter:
package org.scalatest.examples.flatspec.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSpec extends FlatSpec {
override def withFixture(test: NoArgTest) = {
super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
"This test" should "succeed" in { assert(1 + 1 === 2) }
it should "fail" in { assert(1 + 1 === 3) } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSuite execute
ExampleSuite:
This test
- should succeed
- should fail *** FAILED ***
2 did not equal 3 (:33)
+ Dir snapshot: hello.txt, world.txt
Note that the NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes [[org.scalatest.TestData TestData
]] such as the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
package org.scalatest.examples.flatspec.loanfixtureAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
import java.util.concurrent.ConcurrentHashMap
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.FlatSpec import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSpec extends FlatSpec {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
// This test needs the file fixture "Testing" should "be productive" in withFile { (file, writer) => writer.write("productive!") writer.flush() assert(file.length === 24) }
// This test needs the database fixture "Test code" should "be readable" in withDatabase { db => db.append("readable!") assert(db.toString === "ScalaTest is readable!") }
// This test needs both the file and the database it should "be clear and concise" in withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("clear!") writer.write("concise!") writer.flush() assert(db.toString === "ScalaTest is clear!") assert(file.length === 21) } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.FlatSpec
and overriding withFixture(OneArgTest)
.
Each test in a fixture.FlatSpec
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. In other words, instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.flatspec.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSpec extends fixture.FlatSpec {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
"Testing" should "be easy" in { f => f.writer.write("easy!") f.writer.flush() assert(f.file.length === 18) }
it should "be fun" in { f => f.writer.write("fun!") f.writer.flush() assert(f.file.length === 17) } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.FlatSpec
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.flatspec.beforeandafterNote that the only way
import org.scalatest._ import collection.mutable.ListBuffer
class ExampleSpec extends FlatSpec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
"Testing" should "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it should "be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.flatspec.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSpec extends FlatSpec with Builder with Buffer {
"Testing" should "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it should "be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } }
Builder
and Buffer
traits, ExampleSuite
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Suite extends Suite with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Suite extends Suite with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.flatspec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally buffer.clear() } }
class ExampleSpec extends FlatSpec with Builder with Buffer {
"Testing" should "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it should "be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared tests ==
Sometimes you may want to run the same test code on different fixture objects. In other words, you may want to write tests that are "shared"
by different fixture objects. To accomplish this in a FlatSpec
, you first place shared tests in behavior functions.
These behavior functions will be invoked during the construction phase of any FlatSpec
that uses them, so that the tests they
contain will be registered as tests in that FlatSpec
. For example, given this stack class:
import scala.collection.mutable.ListBufferYou may want to test the
class Stack[T] {
val MAX = 10 private val buf = new ListBuffer[T]
def push(o: T) { if (!full) buf.prepend(o) else throw new IllegalStateException("can't push onto a full stack") }
def pop(): T = { if (!empty) buf.remove(0) else throw new IllegalStateException("can't pop an empty stack") }
def peek: T = { if (!empty) buf(0) else throw new IllegalStateException("can't pop an empty stack") }
def full: Boolean = buf.size == MAX def empty: Boolean = buf.size == 0 def size = buf.size
override def toString = buf.mkString("Stack(", ", ", ")") }
Stack
class in different states: empty, full, with one item, with one item less than capacity,
etc. You may find you have several tests that make sense any time the stack is non-empty. Thus you'd ideally want to run
those same tests for three stack fixture objects: a full stack, a stack with a one item, and a stack with one item less than
capacity. With shared tests, you can factor these tests out into a behavior function, into which you pass the
stack fixture to use when running the tests. So in your FlatSpec
for stack, you'd invoke the
behavior function three times, passing in each of the three stack fixtures so that the shared tests are run for all three fixtures. You
can define a behavior function that encapsulates these shared tests inside the FlatSpec
that uses them. If they are shared
between different FlatSpec
s, however, you could also define them in a separate trait that is mixed into each FlatSpec
that uses them.
For example, here the nonEmptyStack
behavior function (in this case, a behavior method) is
defined in a trait along with another method containing shared tests for non-full stacks:
trait StackBehaviors { this: FlatSpec =>Given these behavior functions, you could invoke them directly, but
def nonEmptyStack(newStack: => Stack[Int], lastItemAdded: Int) {
it should "be non-empty" in { assert(!newStack.empty) }
it should "return the top item on peek" in { assert(newStack.peek === lastItemAdded) }
it should "not remove the top item on peek" in { val stack = newStack val size = stack.size assert(stack.peek === lastItemAdded) assert(stack.size === size) }
it should "remove the top item on pop" in { val stack = newStack val size = stack.size assert(stack.pop === lastItemAdded) assert(stack.size === size - 1) } }
def nonFullStack(newStack: => Stack[Int]) {
it should "not be full" in { assert(!newStack.full) }
it should "add to the top on push" in { val stack = newStack val size = stack.size stack.push(7) assert(stack.size === size + 1) assert(stack.peek === 7) } } }
FlatSpec
offers a DSL for the purpose,
which looks like this:
it should behave like nonEmptyStack(stackWithOneItem, lastValuePushed) it should behave like nonFullStack(stackWithOneItem)If you prefer to use an imperative style to change fixtures, for example by mixing in
BeforeAndAfterEach
and
reassigning a stack
var
in beforeEach
, you could write your behavior functions
in the context of that var
, which means you wouldn't need to pass in the stack fixture because it would be
in scope already inside the behavior function. In that case, your code would look like this:
it should behave like nonEmptyStack // assuming lastValuePushed is also in scope inside nonEmptyStack
it should behave like nonFullStack
The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example:
class SharedTestExampleSpec extends FlatSpec with StackBehaviors {If you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, you'll see:
// Stack fixture creation methods def emptyStack = new Stack[Int]
def fullStack = { val stack = new Stack[Int] for (i <- 0 until stack.MAX) stack.push(i) stack }
def stackWithOneItem = { val stack = new Stack[Int] stack.push(9) stack }
def stackWithOneItemLessThanCapacity = { val stack = new Stack[Int] for (i <- 1 to 9) stack.push(i) stack }
val lastValuePushed = 9
"A Stack (when empty)" should "be empty" in { assert(emptyStack.empty) }
it should "complain on peek" in { intercept[IllegalStateException] { emptyStack.peek } }
it should "complain on pop" in { intercept[IllegalStateException] { emptyStack.pop } }
"A Stack (with one item)" should behave like nonEmptyStack(stackWithOneItem, lastValuePushed)
it should behave like nonFullStack(stackWithOneItem)
"A Stack (with one item less than capacity)" should behave like nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed)
it should behave like nonFullStack(stackWithOneItemLessThanCapacity)
"A Stack (full)" should "be full" in { assert(fullStack.full) }
it should behave like nonEmptyStack(fullStack, lastValuePushed)
it should "complain on a push" in { intercept[IllegalStateException] { fullStack.push(10) } } }
scala> new SharedTestExampleSpec execute
A Stack (when empty)
- should be empty
- should complain on peek
- should complain on pop
A Stack (with one item)
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should not be full
- should add to the top on push
A Stack (with one item less than capacity)
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should not be full
- should add to the top on push
A Stack (full)
- should be full
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should complain on a push
One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name.
If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime
complaining that multiple tests are being registered with the same test name. A good way to solve this problem in a FlatSpec
is to make sure
each invocation of a behavior function is in the context of a different set of when
, verb (should
,
must
, or can), and that
clauses,
which will prepend a string to each test name.
For example, the following code in a FlatSpec
would register a test with the name "A Stack (when empty) should be empty"
:
behavior of "A Stack (when empty)"Or, using the shorthand notation:
it should "be empty" in { assert(emptyStack.empty) } // ...
"A Stack" when { "empty" should { "be empty" in { assert(emptyStack.empty) } } } // ...If the
"should be empty"
test was factored out into a behavior function, it could be called repeatedly so long
as each invocation of the behavior function is in the context of a different combination
of when
, verb, and that
clauses.
Implementation trait for class FlatSpec
, which facilitates a
“behavior-driven” style of development (BDD), in which tests
are combined with text that specifies the behavior the tests verify.
Implementation trait for class FlatSpec
, which facilitates a
“behavior-driven” style of development (BDD), in which tests
are combined with text that specifies the behavior the tests verify.
FlatSpec
is a class, not a trait,
to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the
behavior of FlatSpec
into some other class, you can use this
trait instead, because class FlatSpec
does nothing more than
extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed
overview of FlatSpec
.
Facilitates a “behavior-driven” style of development (BDD), in which tests
are nested inside text clauses denoted with the dash operator (-
).
Facilitates a “behavior-driven” style of development (BDD), in which tests
are nested inside text clauses denoted with the dash operator (-
).
FreeSpec
is so named because unlike classes such as WordSpec
, FlatSpec
, and FunSpec
,
it is enforces no structure on the text. You are free to compose text however you like. (A FreeSpec
is like free-verse poetry as
opposed to a sonnet or haiku, which defines a structure for the text of the poem.)
Recommended Usage:
Because it gives absolute freedom (and no guidance) on how specification text should be written, FreeSpec is a good choice for teams experienced
with BDD and able to agree on how to structure the specification text.
|
Here's an example FreeSpec
:
package org.scalatest.examples.freespecIn a
import org.scalatest.FreeSpec
class SetSpec extends FreeSpec {
"A Set" - { "when empty" - { "should have size 0" in { assert(Set.empty.size === 0) }
"should produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
FreeSpec
you write a test with a string followed by in
and the body of the
test in curly braces, like this:
"should have size 0" in { // ... }You can nest a test inside any number of description clauses, which you write with a string followed by a dash character and a block, like this:
"A Set" - { // ... }You can nest description clauses as deeply as you want. Because the description clause is denoted with an operator, not a word like
should
, you are free to structure the text however you wish. Here's an example:
import org.scalatest.FreeSpecRunning the above
class StackSpec extends FreeSpec { "A Stack" - { "whenever it is empty" - { "certainly ought to" - { "be empty" in { // ... } "complain on peek" in { // ... } "complain on pop" in { // ... } } } "but when full, by contrast, must" - { "be full" in { // ... } "complain on push" in { // ... } } } }
StackSpec
in the interpreter would yield:
scala> new StackSpec execute
StackSpec:
A Stack
whenever it is empty
certainly ought to
- be empty
- complain on peek
- complain on pop
but when full, by contrast, must
- be full
- complain on push
A FreeSpec
can also be used to write a specification-style test in languages other than English. For
example:
import org.scalatest.FreeSpecRunning the above
class ComputerRoomRulesSpec extends FreeSpec { "Achtung!" - { "Alle touristen und non-technischen lookenpeepers!" - { "Das machine is nicht fuer fingerpoken und mittengrabben." in { // ... } "Is easy" - { "schnappen der springenwerk" in { // ... } "blowenfusen" in { // ... } "und poppencorken mit spitzen sparken." in { // ... } } "Das machine is diggen by experten only." in { // ... } "Is nicht fuer gerwerken by das dummkopfen." in { // ... } "Das rubbernecken sightseeren keepen das cottenpicken hands in das pockets." in { // ... } "Relaxen und watchen das blinkenlights." in { // ... } } } }
ComputerRoomRulesSpec
in the interpreter would yield:
scala> new ComputerRoomRulesSpec execute
ComputerRoomRulesSpec:
Achtung!
Alle touristen und non-technischen lookenpeepers!
- Das machine is nicht fuer fingerpoken und mittengrabben.
Is easy
- schnappen der springenwerk
- blowenfusen
- und poppencorken mit spitzen sparken.
- Das machine is diggen by experten only.
- Is nicht fuer gerwerken by das dummkopfen.
- Das rubbernecken sightseeren keepen das cottenpicken hands in das pockets.
- Relaxen und watchen das blinkenlights.
A FreeSpec
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Tests can only be registered while the FreeSpec
is
in its registration phase. Any attempt to register a test after the FreeSpec
has
entered its ready phase, i.e., after run
has been invoked on the FreeSpec
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using FreeSpec
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, FreeSpec
adds a method
ignore
to strings that can be used instead of in
to register a test. For example, to temporarily
disable the test with the name "A Stack should pop values in last-in-first-out order"
, just
change “in
” into “ignore
,” like this:
package org.scalatest.examples.freespec.ignoreIf you run this version of
import org.scalatest.FreeSpec
class SetSpec extends FreeSpec {
"A Set" - { "when empty" - { "should have size 0" ignore { assert(Set.empty.size === 0) }
"should produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
with:
scala> new SetSpec executeIt will run only the second test and report that the first test was ignored:
A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invokedIf you wish to temporarily ignore an entire suite of tests, you can annotate the test class with
@Ignore
, like this:
package org.scalatest.examples.freespec.ignoreallWhen you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the
import org.scalatest.FreeSpec import org.scalatest.Ignore
@Ignore class SetSpec extends FreeSpec {
"A Set" - { "when empty" - { "should have size 0" in { assert(Set.empty.size === 0) }
"should produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSpec
in the Scala interpreter, you'll see:
scala> new SetSpec execute SetSpec: A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invoked !!! IGNORED !!!Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored class visible, to encourage the developers to eventually fix and “un-ignore” it. If you want to prevent a class from being discovered at all, use the
DoNotDiscover
annotation instead.
== Informers ==
One of the parameters to FreeSpec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by FreeSpec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via its apply
method.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
One use case for the Informer
is to pass more information about a specification to the reporter. For example,
the GivenWhenThen
trait provides methods that use the implicit info
provided by FreeSpec
to pass such information to the reporter. Here's an example:
package org.scalatest.examples.freespec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends FreeSpec with GivenWhenThen {
"A mutable Set" - { "should allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } } }
FreeSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
== Documenters ==
FreeSpec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example FreeSpec
that uses markup
:
package org.scalatest.examples.freespec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSpec extends FreeSpec with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
"A mutable Set" - { "should allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.freespec.note
import collection.mutable import org.scalatest._
class SetSpec extends FreeSpec {
"A mutable Set" - { "should allow an element to be added" in {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } } }
scala> new SetSpec execute SetSpec: A mutable Set + notes are sent immediately + alerts are also sent immediately - should allow an element to be added + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run. (In other words,
the code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality it is intended to test, has not yet been implemented.
You can mark tests as pending in a FreeSpec
like this:
package org.scalatest.examples.freespec.pendingIf you run this version of
import org.scalatest._
class SetSpec extends FreeSpec {
"A Set" - { "when empty" - { "should have size 0" in (pending)
"should produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
with:
scala> new SetSpec executeIt will run both tests but report that
should have size 0
is pending. You'll see:
A Set when empty - should have size 0 (pending) - should produce NoSuchElementException when head is invokedOne difference between an ignored test and a pending one is that an ignored test is intended to be used during a significant refactorings of the code under test, when tests break and you don't want to spend the time to fix all of them immediately. You can mark some of those broken tests as ignored temporarily, so that you can focus the red bar on just failing tests you actually want to fix immediately. Later you can go back and fix the ignored tests. In other words, by ignoring some failing tests temporarily, you can more easily notice failed tests that you actually want to fix. By contrast, a pending test is intended to be used before a test and/or the code under test is written. Pending indicates you've decided to write a test for a bit of behavior, but either you haven't written the test yet, or have only written part of it, or perhaps you've written the test but don't want to implement the behavior it tests until after you've implemented a different bit of behavior you realized you need first. Thus ignored tests are designed to facilitate refactoring of existing code whereas pending tests are designed to facilitate the creation of new code. One other difference between ignored and pending tests is that ignored tests are implemented as a test tag that is excluded by default. Thus an ignored test is never executed. By contrast, a pending test is implemented as a test that throws
TestPendingException
(which is what calling the pending
method does). Thus
the body of pending tests are executed up until they throw TestPendingException
. The reason for this difference
is that it enables your unfinished test to send InfoProvided
messages to the reporter before it completes
abruptly with TestPendingException
, as shown in the previous example on Informer
s
that used the GivenWhenThen
trait. For example, the following snippet in a FreeSpec
:
"The Scala language" - { "should add correctly" in { Given("two integers") When("they are added") Then("the result is the sum of the two numbers") pending } // ...Would yield the following output when run in the interpreter:
The Scala language - should add correctly (pending) + Given two integers + When they are added + Then the result is the sum of the two numbers== Tagging tests == A
FreeSpec
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a FreeSpec
, groups of tests can
optionally be included and/or excluded. To tag a FreeSpec
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for FreeSpec
s like this:
import org.scalatest.TagGiven these definitions, you could tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
FreeSpec
tests like this:
package org.scalatest.examples.freespec.taggingThis code marks both tests with the
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
import org.scalatest.FreeSpec
class SetSpec extends FreeSpec {
"A Set" - { "when empty" - { "should have size 0" taggedAs(SlowTest) in { assert(Set.empty.size === 0) }
"should produce NoSuchElementException when head is invoked" taggedAs(SlowTest, DbTest) in { intercept[NoSuchElementException] { Set.empty.head } } } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
It is recommended, though not required, that you create a corresponding tag annotation when you
create a Tag
object. A tag annotation allows you to tag all the tests of a FreeSpec
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.freespec.getfixtureThe “
import org.scalatest.FreeSpec import collection.mutable.ListBuffer
class ExampleSpec extends FreeSpec {
def fixture = new { val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String] }
"Testing" - { "should be easy" in { val f = fixture f.builder.append("easy!") assert(f.builder.toString === "ScalaTest is easy!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
"should be fun" in { val f = fixture f.builder.append("fun!") assert(f.builder.toString === "ScalaTest is fun!") assert(f.buffer.isEmpty) } } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, if you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.freespec.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.FreeSpec
class ExampleSpec extends FreeSpec {
trait Builder { val builder = new StringBuilder("ScalaTest is ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is") }
"Testing" - { // This test needs the StringBuilder fixture "should be productive" in new Builder { builder.append("productive!") assert(builder.toString === "ScalaTest is productive!") } }
"Test code" - { // This test needs the ListBuffer[String] fixture "should be readable" in new Buffer { buffer += ("readable!") assert(buffer === List("ScalaTest", "is", "readable!")) }
// This test needs both the StringBuilder and ListBuffer "should be clear and concise" in new Builder with Buffer { builder.append("clear!") buffer += ("concise!") assert(builder.toString === "ScalaTest is clear!") assert(buffer === List("ScalaTest", "is", "concise!")) } } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. In other words, instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
and send that information to the reporter:
package org.scalatest.examples.freespec.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSpec extends FreeSpec {
override def withFixture(test: NoArgTest) = {
super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
"This test" - { "should succeed" in { assert(1 + 1 === 2) }
"should fail" in { assert(1 + 1 === 3) } } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSuite execute
ExampleSuite:
This test
- should succeed
- should fail *** FAILED ***
2 did not equal 3 (:33)
+ Dir snapshot: hello.txt, world.txt
Note that the NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
package org.scalatest.examples.freespec.loanfixtureAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
import java.util.concurrent.ConcurrentHashMap
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.FreeSpec import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSpec extends FreeSpec {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
"Testing" - { // This test needs the file fixture "should be productive" in withFile { (file, writer) => writer.write("productive!") writer.flush() assert(file.length === 24) } }
"Test code" - { // This test needs the database fixture "should be readable" in withDatabase { db => db.append("readable!") assert(db.toString === "ScalaTest is readable!") }
// This test needs both the file and the database "should be clear and concise" in withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("clear!") writer.write("concise!") writer.flush() assert(db.toString === "ScalaTest is clear!") assert(file.length === 21) } } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.FreeSpec
and overriding withFixture(OneArgTest)
.
Each test in a fixture.FreeSpec
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. In other words, instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.freespec.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSpec extends fixture.FreeSpec {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = {
// create the fixture val file = File.createTempFile("hello", "world") val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
"Testing" - { "should be easy" in { f => f.writer.write("easy!") f.writer.flush() assert(f.file.length === 18) }
"should be fun" in { f => f.writer.write("fun!") f.writer.flush() assert(f.file.length === 17) } } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.FreeSpec
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.freespec.beforeandafterNote that the only way
import org.scalatest.FreeSpec import org.scalatest.BeforeAndAfter import collection.mutable.ListBuffer
class ExampleSpec extends FreeSpec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
"Testing" - { "should be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
"should be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.freespec.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSpec extends FreeSpec with Builder with Buffer {
"Testing" - { "should be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
"should be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
Builder
and Buffer
traits, ExampleSuite
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Suite extends Suite with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Suite extends Suite with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.freespec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import org.scalatest.BeforeAndAfterEach import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally buffer.clear() } }
class ExampleSpec extends FreeSpec with Builder with Buffer {
"Testing" - { "should be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
"should be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared tests ==
Sometimes you may want to run the same test code on different fixture objects. In other words, you may want to write tests that are "shared"
by different fixture objects. To accomplish this in a FreeSpec
, you first place shared tests in behavior functions.
These behavior functions will be invoked during the construction phase of any FreeSpec
that uses them, so that the tests they
contain will be registered as tests in that FreeSpec
. For example, given this stack class:
import scala.collection.mutable.ListBufferYou may want to test the
class Stack[T] {
val MAX = 10 private val buf = new ListBuffer[T]
def push(o: T) { if (!full) buf.prepend(o) else throw new IllegalStateException("can't push onto a full stack") }
def pop(): T = { if (!empty) buf.remove(0) else throw new IllegalStateException("can't pop an empty stack") }
def peek: T = { if (!empty) buf(0) else throw new IllegalStateException("can't pop an empty stack") }
def full: Boolean = buf.size == MAX def empty: Boolean = buf.size == 0 def size = buf.size
override def toString = buf.mkString("Stack(", ", ", ")") }
Stack
class in different states: empty, full, with one item, with one item less than capacity,
etc. You may find you have several tests that make sense any time the stack is non-empty. Thus you'd ideally want to run
those same tests for three stack fixture objects: a full stack, a stack with a one item, and a stack with one item less than
capacity. With shared tests, you can factor these tests out into a behavior function, into which you pass the
stack fixture to use when running the tests. So in your FreeSpec
for stack, you'd invoke the
behavior function three times, passing in each of the three stack fixtures so that the shared tests are run for all three fixtures. You
can define a behavior function that encapsulates these shared tests inside the FreeSpec
that uses them. If they are shared
between different FreeSpec
s, however, you could also define them in a separate trait that is mixed into each FreeSpec
that uses them.
For example, here the nonEmptyStack
behavior function (in this case, a behavior method) is
defined in a trait along with another method containing shared tests for non-full stacks:
trait StackBehaviors { this: FreeSpec =>Given these behavior functions, you could invoke them directly, but
def nonEmptyStack(newStack: => Stack[Int], lastItemAdded: Int) {
"be non-empty" in { assert(!newStack.empty) }
"return the top item on peek" in { assert(newStack.peek === lastItemAdded) }
"not remove the top item on peek" in { val stack = newStack val size = stack.size assert(stack.peek === lastItemAdded) assert(stack.size === size) }
"remove the top item on pop" in { val stack = newStack val size = stack.size assert(stack.pop === lastItemAdded) assert(stack.size === size - 1) } }
def nonFullStack(newStack: => Stack[Int]) {
"not be full" in { assert(!newStack.full) }
"add to the top on push" in { val stack = newStack val size = stack.size stack.push(7) assert(stack.size === size + 1) assert(stack.peek === 7) } } }
FreeSpec
offers a DSL for the purpose,
which looks like this:
behave like nonEmptyStack(stackWithOneItem, lastValuePushed) behave like nonFullStack(stackWithOneItem)If you prefer to use an imperative style to change fixtures, for example by mixing in
BeforeAndAfterEach
and
reassigning a stack
var
in beforeEach
, you could write your behavior functions
in the context of that var
, which means you wouldn't need to pass in the stack fixture because it would be
in scope already inside the behavior function. In that case, your code would look like this:
behave like nonEmptyStack // assuming lastValuePushed is also in scope inside nonEmptyStack behave like nonFullStackThe recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example:
class SharedTestExampleSpec extends FreeSpec with StackBehaviors {If you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, you'll see:
// Stack fixture creation methods def emptyStack = new Stack[Int]
def fullStack = { val stack = new Stack[Int] for (i <- 0 until stack.MAX) stack.push(i) stack }
def stackWithOneItem = { val stack = new Stack[Int] stack.push(9) stack }
def stackWithOneItemLessThanCapacity = { val stack = new Stack[Int] for (i <- 1 to 9) stack.push(i) stack }
val lastValuePushed = 9
"A Stack" - { "when empty" - { "should be empty" in { assert(emptyStack.empty) }
"should complain on peek" in { intercept[IllegalStateException] { emptyStack.peek } }
"should complain on pop" in { intercept[IllegalStateException] { emptyStack.pop } } }
"when it contains one item" - { "should" - { behave like nonEmptyStack(stackWithOneItem, lastValuePushed) behave like nonFullStack(stackWithOneItem) } }
"when it contains one item less than capacity" - { "should" - { behave like nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed) behave like nonFullStack(stackWithOneItemLessThanCapacity) } }
"when full" - { "should be full" in { assert(fullStack.full) }
"should" - { behave like nonEmptyStack(fullStack, lastValuePushed) }
"should complain on a push" in { intercept[IllegalStateException] { fullStack.push(10) } } } } }
scala> new SharedTestExampleSpec execute
SharedTestExampleSpec:
A Stack
when empty
- should be empty
- should complain on peek
- should complain on pop
when it contains one item
should
- be non-empty
- return the top item on peek
- not remove the top item on peek
- remove the top item on pop
- not be full
- add to the top on push
when it contains one item less than capacity
should
- be non-empty
- return the top item on peek
- not remove the top item on peek
- remove the top item on pop
- not be full
- add to the top on push
when full
- should be full
should
- be non-empty
- return the top item on peek
- not remove the top item on peek
- remove the top item on pop
- should complain on a push
One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name.
If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime
complaining that multiple tests are being registered with the same test name. A good way to solve this problem in a FreeSpec
is to make sure
each test is in the context of different surrounding description clauses,
because a test's name is the concatenation of its surrounding clauses, followed by the test's text.
For example, the following code in a FreeSpec
would register a test with the name "A Stack when empty should be empty"
:
"A Stack" - { "when empty" - { "should be empty" in { assert(emptyStack.empty) } } } // ...If the
"should be empty"
test was factored out into a behavior function, it could be called repeatedly so long
as each invocation of the behavior function is in the context of a different surrounding description (dash) clauses.
Implementation trait for class FreeSpec
, which
facilitates a “behavior-driven” style of development (BDD),
in which tests are nested inside text clauses denoted with the dash
operator (-
).
Implementation trait for class FreeSpec
, which
facilitates a “behavior-driven” style of development (BDD),
in which tests are nested inside text clauses denoted with the dash
operator (-
).
FreeSpec
is a class, not a trait,
to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the
behavior of FreeSpec
into some other class, you can use this
trait instead, because class FreeSpec
does nothing more than
extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed
overview of FreeSpec
.
Facilitates a “behavior-driven” style of development (BDD), in which tests are combined with text that specifies the behavior the tests verify.
Facilitates a “behavior-driven” style of development (BDD), in which tests are combined with text that specifies the behavior the tests verify.
Recommended Usage:
For teams coming from Ruby's RSpec tool, FunSpec will feel familiar and comfortable; More generally, for any team that prefers BDD, FunSpec 's nesting
and gentle guide to structuring text (with describe and it ) provide an excellent general-purpose choice for writing specification-style tests.
|
Here's an example FunSpec
:
package org.scalatest.examples.funspecA
import org.scalatest.FunSpec
class SetSpec extends FunSpec {
describe("A Set") { describe("when empty") { it("should have size 0") { assert(Set.empty.size === 0) }
it("should produce NoSuchElementException when head is invoked") { intercept[NoSuchElementException] { Set.empty.head } } } } }
FunSpec
contains describe clauses and tests. You define a describe clause
with describe
, and a test with either it
or they
.
describe
, it
, and and they
are methods, defined in
FunSpec
, which will be invoked
by the primary constructor of SetSpec
.
A describe clause names, or gives more information about, the subject (class or other entity) you are specifying
and testing. In the previous example, "A Set"
is the subject under specification and test. With each test you provide a string (the spec text) that specifies
one bit of behavior of the subject, and a block of code that tests that behavior.
You place the spec text between the parentheses, followed by the test code between curly
braces. The test code will be wrapped up as a function passed as a by-name parameter to
it
(or they
), which will register the test for later execution.
Note: the they
method is intended for use when the subject is plural, for example:
describe("The combinators") { they("should be easy to learn") {} they("should be efficient") {} they("should do something cool") {} }A
FunSpec
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Tests can only be registered with the it
or they
methods while the FunSpec
is
in its registration phase. Any attempt to register a test after the FunSpec
has
entered its ready phase, i.e., after run
has been invoked on the FunSpec
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using FunSpec
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
When you execute a FunSpec
, it will send Formatter
s in the events it sends to the
Reporter
. ScalaTest's built-in reporters will report these events in such a way
that the output is easy to read as an informal specification of the subject being tested.
For example, were you to run SetSpec
from within the Scala interpreter:
scala> new SetSpec executeYou would see:
A Set when empty - should have size 0 - should produce NoSuchElementException when head is invokedOr, to run just the “
A Set when empty should have size 0
” test, you could pass that test's name, or any unique substring of the
name, such as "size 0"
or even just "0"
. Here's an example:
scala> new SetSuite execute "size 0" A Set when empty - should have size 0You can also pass to
execute
a config map of key-value
pairs, which will be passed down into suites and tests, as well as other parameters that configure the run itself.
For more information on running in the Scala interpreter, see the documentation for execute
(below) and the
ScalaTest shell.
The execute
method invokes a run
method that takes two
parameters. This run
method, which actually executes the suite, will usually be invoked by a test runner, such
as run
, tools.Runner
, a build tool, or an IDE.
Note: FunSpec
's syntax is in great part inspired by RSpec, a Ruby BDD framework.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, FunSpec
provides registration
methods that start with ignore
instead of it
or they
. For example, to temporarily
disable the test with the text "should have size 0"
, just change “it
” into “ignore
,” like this:
package org.scalatest.examples.funspec.ignoreIf you run this version of
import org.scalatest.FunSpec
class SetSpec extends FunSpec {
describe("A Set") { describe("when empty") { ignore("should have size 0") { assert(Set.empty.size === 0) }
it("should produce NoSuchElementException when head is invoked") { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
with:
scala> new SetSpec executeIt will run only the second test and report that the first test was ignored:
A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invokedIf you wish to temporarily ignore an entire suite of tests, you can annotate the test class with
@Ignore
, like this:
package org.scalatest.examples.funspec.ignoreallWhen you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the
import org.scalatest.FunSpec import org.scalatest.Ignore
@Ignore class SetSpec extends FunSpec {
describe("A Set") { describe("when empty") { it("should have size 0") { assert(Set.empty.size === 0) }
it("should produce NoSuchElementException when head is invoked") { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSpec
in the Scala interpreter, you'll see:
scala> new SetSpec execute SetSpec: A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invoked !!! IGNORED !!!Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored class visible, to encourage the developers to eventually fix and “un-ignore” it. If you want to prevent a class from being discovered at all, use the
DoNotDiscover
annotation instead.
== Informers ==
One of the parameters to FunSpec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by FunSpec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via one of its apply
methods.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
Here's an example in which the Informer
returned by info
is used implicitly by the
Given
, When
, and Then
methods of trait GivenWhenThen
:
package org.scalatest.examples.funspec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends FunSpec with GivenWhenThen {
describe("A mutable Set") { it("should allow an element to be added") { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } } }
FunSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
== Documenters ==
FunSpec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example FunSpec
that uses markup
:
package org.scalatest.examples.funspec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSpec extends FunSpec with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
describe("A mutable Set") { it("should allow an element to be added") { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.funspec.noteBecause
import collection.mutable import org.scalatest._
class SetSpec extends FunSpec {
describe("A mutable Set") { it("should allow an element to be added") {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSpec: A mutable Set + notes are sent immediately + alerts are also sent immediately - should allow an element to be added + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run. (In other words,
the code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality, has not yet been implemented.
You can mark a test as pending in FunSpec
by placing "(pending)
" after the
test name, like this:
package org.scalatest.examples.funspec.pending(Note: "
import org.scalatest._
class SetSpec extends FunSpec {
describe("A Set") { describe("when empty") { it("should have size 0") (pending)
it("should produce NoSuchElementException when head is invoked") { intercept[NoSuchElementException] { Set.empty.head } } } } }
(pending)
" is the body of the test. Thus the test contains just one statement, an invocation
of the pending
method, which throws TestPendingException
.)
If you run this version of SetSpec
with:
scala> new SetSpec executeIt will run both tests, but report that the test named "
should have size 0
" is pending. You'll see:
A Set when empty - should have size 0 (pending) - should produce NoSuchElementException when head is invoked== Tagging tests == A
FunSpec
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a FunSpec
, groups of tests can
optionally be included and/or excluded. To tag a FunSpec
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for FunSpec
s like this:
package org.scalatest.examples.funspec.taggingGiven these definitions, you could place
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
FunSpec
tests into groups like this:
import org.scalatest.FunSpecThis code marks both tests with the
class SetSpec extends FunSpec {
describe("A Set") { describe("when empty") { it("should have size 0", SlowTest) { assert(Set.empty.size === 0) }
it("should produce NoSuchElementException when head is invoked", SlowTest, DbTest) { intercept[NoSuchElementException] { Set.empty.head } } } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
It is recommended, though not required, that you create a corresponding tag annotation when you
create a Tag
object. A tag annotation allows you to tag all the tests of a FunSpec
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.funspec.getfixtureThe “
import org.scalatest.FunSpec import collection.mutable.ListBuffer
class ExampleSpec extends FunSpec {
def fixture = new { val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String] }
describe("Testing") { it("should be easy") { val f = fixture f.builder.append("easy!") assert(f.builder.toString === "ScalaTest is easy!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
it("should be fun") { val f = fixture f.builder.append("fun!") assert(f.builder.toString === "ScalaTest is fun!") assert(f.buffer.isEmpty) } } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, if you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.funspec.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.FunSpec
class ExampleSpec extends FunSpec {
trait Builder { val builder = new StringBuilder("ScalaTest is ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is") }
describe("Testing") { // This test needs the StringBuilder fixture it("should be productive") { new Builder { builder.append("productive!") assert(builder.toString === "ScalaTest is productive!") } } }
describe("Test code") { // This test needs the ListBuffer[String] fixture it("should be readable") { new Buffer { buffer += ("readable!") assert(buffer === List("ScalaTest", "is", "readable!")) } }
// This test needs both the StringBuilder and ListBuffer it("should be clear and concise") { new Builder with Buffer { builder.append("clear!") buffer += ("concise!") assert(builder.toString === "ScalaTest is clear!") assert(buffer === List("ScalaTest", "is", "concise!")) } } } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. In other words, instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
and send that information to the reporter:
package org.scalatest.examples.funspec.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSpec extends FunSpec {
override def withFixture(test: NoArgTest) = {
try super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
describe("This test") { it("should succeed") { assert(1 + 1 === 2) }
it("should fail") { assert(1 + 1 === 3) } } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSuite execute
ExampleSuite:
This test
- should succeed
- should fail *** FAILED ***
2 did not equal 3 (:33)
+ Dir snapshot: hello.txt, world.txt
Note that the NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
package org.scalatest.examples.funspec.loanfixtureAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
import java.util.concurrent.ConcurrentHashMap
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.FunSpec import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSpec extends FunSpec {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
describe("Testing") { // This test needs the file fixture it("should be productive") { withFile { (file, writer) => writer.write("productive!") writer.flush() assert(file.length === 24) } } }
describe("Test code") { // This test needs the database fixture it("should be readable") { withDatabase { db => db.append("readable!") assert(db.toString === "ScalaTest is readable!") } }
// This test needs both the file and the database it("should be clear and concise") { withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("clear!") writer.write("concise!") writer.flush() assert(db.toString === "ScalaTest is clear!") assert(file.length === 21) } } } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.Suite
and overriding withFixture(OneArgTest)
.
Each test in a fixture.Suite
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. In other words, instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.funspec.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSpec extends fixture.FunSpec {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = {
// create the fixture val file = File.createTempFile("hello", "world") val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
describe("Testing") { it("should be easy") { f => f.writer.write("easy!") f.writer.flush() assert(f.file.length === 18) }
it("should be fun") { f => f.writer.write("fun!") f.writer.flush() assert(f.file.length === 17) } } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.FunSpec
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.funspec.beforeandafterNote that the only way
import org.scalatest.FunSpec import org.scalatest.BeforeAndAfter import collection.mutable.ListBuffer
class ExampleSpec extends FunSpec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
describe("Testing") { it("should be easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it("should be fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.funspec.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSpec extends FunSpec with Builder with Buffer {
describe("Testing") { it("should be easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it("should be fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
Builder
and Buffer
traits, ExampleSuite
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Suite extends Suite with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Suite extends Suite with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.funspec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import org.scalatest.BeforeAndAfterEach import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally buffer.clear() } }
class ExampleSpec extends FunSpec with Builder with Buffer {
describe("Testing") { it("should be easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
it("should be fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared tests ==
Sometimes you may want to run the same test code on different fixture objects. In other words, you may want to write tests that are "shared"
by different fixture objects.
To accomplish this in a FunSpec
, you first place shared tests in behavior functions. These behavior functions will be
invoked during the construction phase of any FunSpec
that uses them, so that the tests they contain will be registered as tests in that FunSpec
.
For example, given this stack class:
import scala.collection.mutable.ListBufferYou may want to test the
class Stack[T] {
val MAX = 10 private val buf = new ListBuffer[T]
def push(o: T) { if (!full) buf.prepend(o) else throw new IllegalStateException("can't push onto a full stack") }
def pop(): T = { if (!empty) buf.remove(0) else throw new IllegalStateException("can't pop an empty stack") }
def peek: T = { if (!empty) buf(0) else throw new IllegalStateException("can't pop an empty stack") }
def full: Boolean = buf.size == MAX def empty: Boolean = buf.size == 0 def size = buf.size
override def toString = buf.mkString("Stack(", ", ", ")") }
Stack
class in different states: empty, full, with one item, with one item less than capacity,
etc. You may find you have several tests that make sense any time the stack is non-empty. Thus you'd ideally want to run
those same tests for three stack fixture objects: a full stack, a stack with a one item, and a stack with one item less than
capacity. With shared tests, you can factor these tests out into a behavior function, into which you pass the
stack fixture to use when running the tests. So in your FunSpec
for stack, you'd invoke the
behavior function three times, passing in each of the three stack fixtures so that the shared tests are run for all three fixtures. You
can define a behavior function that encapsulates these shared tests inside the FunSpec
that uses them. If they are shared
between different FunSpec
s, however, you could also define them in a separate trait that is mixed into each FunSpec
that uses them.
For example, here the nonEmptyStack
behavior function (in this case, a behavior method) is defined in a trait along with another
method containing shared tests for non-full stacks:
trait StackBehaviors { this: FunSpec =>Given these behavior functions, you could invoke them directly, but
def nonEmptyStack(newStack: => Stack[Int], lastItemAdded: Int) {
it("should be non-empty") { assert(!newStack.empty) }
it("should return the top item on peek") { assert(newStack.peek === lastItemAdded) }
it("should not remove the top item on peek") { val stack = newStack val size = stack.size assert(stack.peek === lastItemAdded) assert(stack.size === size) }
it("should remove the top item on pop") { val stack = newStack val size = stack.size assert(stack.pop === lastItemAdded) assert(stack.size === size - 1) } }
def nonFullStack(newStack: => Stack[Int]) {
it("should not be full") { assert(!newStack.full) }
it("should add to the top on push") { val stack = newStack val size = stack.size stack.push(7) assert(stack.size === size + 1) assert(stack.peek === 7) } } }
FunSpec
offers a DSL for the purpose,
which looks like this:
it should behave like nonEmptyStack(stackWithOneItem, lastValuePushed) it should behave like nonFullStack(stackWithOneItem)If you prefer to use an imperative style to change fixtures, for example by mixing in
BeforeAndAfterEach
and
reassigning a stack
var
in beforeEach
, you could write your behavior functions
in the context of that var
, which means you wouldn't need to pass in the stack fixture because it would be
in scope already inside the behavior function. In that case, your code would look like this:
it should behave like nonEmptyStack // assuming lastValuePushed is also in scope inside nonEmptyStack
it should behave like nonFullStack
The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example:
class SharedTestExampleSpec extends FunSpec with StackBehaviors {If you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, you'll see:
// Stack fixture creation methods def emptyStack = new Stack[Int]
def fullStack = { val stack = new Stack[Int] for (i <- 0 until stack.MAX) stack.push(i) stack }
def stackWithOneItem = { val stack = new Stack[Int] stack.push(9) stack }
def stackWithOneItemLessThanCapacity = { val stack = new Stack[Int] for (i <- 1 to 9) stack.push(i) stack }
val lastValuePushed = 9
describe("A Stack") {
describe("(when empty)") {
it("should be empty") { assert(emptyStack.empty) }
it("should complain on peek") { intercept[IllegalStateException] { emptyStack.peek } }
it("should complain on pop") { intercept[IllegalStateException] { emptyStack.pop } } }
describe("(with one item)") { it should behave like nonEmptyStack(stackWithOneItem, lastValuePushed) it should behave like nonFullStack(stackWithOneItem) }
describe("(with one item less than capacity)") { it should behave like nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed) it should behave like nonFullStack(stackWithOneItemLessThanCapacity) }
describe("(full)") {
it("should be full") { assert(fullStack.full) }
it should behave like nonEmptyStack(fullStack, lastValuePushed)
it("should complain on a push") { intercept[IllegalStateException] { fullStack.push(10) } } } } }
scala> new StackSpec execute
A Stack (when empty)
- should be empty
- should complain on peek
- should complain on pop
A Stack (with one item)
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should not be full
- should add to the top on push
A Stack (with one item less than capacity)
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should not be full
- should add to the top on push
A Stack (full)
- should be full
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should complain on a push
One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name.
If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime
complaining that multiple tests are being registered with the same test name. A good way to solve this problem in a FunSpec
is to surround
each invocation of a behavior function with a describe
clause, which will prepend a string to each test name.
For example, the following code in a FunSpec
would register a test with the name "A Stack (when empty) should be empty"
:
describe("A Stack") {If the
describe("(when empty)") {
it("should be empty") { assert(emptyStack.empty) } // ...
"should be empty"
test was factored out into a behavior function, it could be called repeatedly so long
as each invocation of the behavior function is inside a different set of describe
clauses.
Implementation trait for class FunSpec
, which
facilitates a “behavior-driven” style of development (BDD),
in which tests are combined with text that specifies the behavior the tests
verify.
Implementation trait for class FunSpec
, which
facilitates a “behavior-driven” style of development (BDD),
in which tests are combined with text that specifies the behavior the tests
verify.
FunSpec
is a class, not a trait,
to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the
behavior of FunSpec
into some other class, you can use this
trait instead, because class FunSpec
does nothing more than
extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed
overview of FunSpec
.
A suite of tests in which each test is represented as a function value.
A suite of tests in which each test is represented as a function value. The “Fun
” in FunSuite
stands
for “function.”
Recommended Usage:
For teams coming from xUnit, FunSuite feels comfortable and familiar while still giving some benefits of BDD: FunSuite makes it easy to
write descriptive test names, natural to write focused tests, and generates specification-like output that can facilitate communication among
stakeholders.
|
Here's an example FunSuite
:
package org.scalatest.examples.funsuite“
import org.scalatest.FunSuite
class SetSuite extends FunSuite {
test("An empty Set should have size 0") { assert(Set.empty.size === 0) }
test("Invoking head on an empty Set should produce NoSuchElementException") { intercept[NoSuchElementException] { Set.empty.head } } }
test
” is a method, defined in FunSuite
, which will be invoked
by the primary constructor of SetSuite
. You specify the name of the test as
a string between the parentheses, and the test code itself between curly braces.
The test code is a function passed as a by-name parameter to test
, which registers
it for later execution.
A FunSuite
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Tests can only be registered with the test
method while the FunSuite
is
in its registration phase. Any attempt to register a test after the FunSuite
has
entered its ready phase, i.e., after run
has been invoked on the FunSuite
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using FunSuite
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
Note: FunSuite
was in part inspired by Rehersal,
an early test framework for Scala.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, FunSuite
provides registration
methods that start with ignore
instead of test
. Here's an example: to temporarily
package org.scalatest.examples.funsuite.ignoreIf you run this version of
import org.scalatest.FunSuite
class SetSuite extends FunSuite {
ignore("An empty Set should have size 0") { assert(Set.empty.size === 0) }
test("Invoking head on an empty Set should produce NoSuchElementException") { intercept[NoSuchElementException] { Set.empty.head } } }
SetSuite
with:
scala> new SetSuite executeIt will run only the second test and report that the first test was ignored:
SetSuite: - An empty Set should have size 0 !!! IGNORED !!! - Invoking head on an empty Set should produce NoSuchElementExceptionIf you wish to temporarily ignore an entire suite of tests, you can annotate the test class with
@Ignore
, like this:
package org.scalatest.examples.funsuite.ignoreallWhen you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the
import org.scalatest.FunSuite import org.scalatest.Ignore
@Ignore class SetSuite extends FunSuite {
test("An empty Set should have size 0") { assert(Set.empty.size === 0) }
test("Invoking head on an empty Set should produce NoSuchElementException") { intercept[NoSuchElementException] { Set.empty.head } } }
SetSuite
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSuite
in the Scala interpreter, you'll see:
scala> new SetSuite execute SetSuite: - An empty Set should have size 0 !!! IGNORED !!! - Invoking head on an empty Set should produce NoSuchElementException !!! IGNORED !!!Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored class visible, to encourage the developers to eventually fix and “un-ignore” it. If you want to prevent a class from being discovered at all, use the
DoNotDiscover
annotation instead.
== Informers ==
One of the parameters to FunSuite
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by FunSuite
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information
to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via its apply
method.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
Here's an example that shows both a direct use as well as an indirect use through the methods
of GivenWhenThen
:
package org.scalatest.examples.funsuite.infoIf you run this
import collection.mutable import org.scalatest._
class SetSuite extends FunSuite with GivenWhenThen {
test("An element can be added to an empty mutable Set") {
Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } }
FunSuite
from the interpreter, you will see the following output:
scala> new SetSuite execute
SetSuite:
- an element can be added to an empty mutable Set
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
== Documenters ==
FunSuite
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example FunSuite
that uses markup
:
package org.scalatest.examples.funsuite.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSuite extends FunSuite with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
test("An element can be added to an empty mutable Set") {
Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.funsuite.noteBecause
import collection.mutable import org.scalatest._
class SetSuite extends FunSuite {
test("An element can be added to an empty mutable Set") {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSuite: + notes are sent immediately + alerts are also sent immediately - An element can be added to an empty mutable Set + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run. (In other words,
the code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality, has not yet been implemented.
Although pending tests may be used more often in specification-style suites, such as
org.scalatest.FunSpec
, you can also use it in FunSuite
, like this:
package org.scalatest.examples.funsuite.pending(Note: "
import org.scalatest._
class SetSuite extends FunSuite {
test("An empty Set should have size 0") (pending)
test("Invoking head on an empty Set should produce NoSuchElementException") { intercept[NoSuchElementException] { Set.empty.head } } }
(pending)
" is the body of the test. Thus the test contains just one statement, an invocation
of the pending
method, which throws TestPendingException
.)
If you run this version of SetSuite
with:
scala> new SetSuite executeIt will run both tests, but report that first test is pending. You'll see:
SetSuite: - An empty Set should have size 0 (pending) - Invoking head on an empty Set should produce NoSuchElementExceptionOne difference between an ignored test and a pending one is that an ignored test is intended to be used during a significant refactorings of the code under test, when tests break and you don't want to spend the time to fix all of them immediately. You can mark some of those broken tests as ignored temporarily, so that you can focus the red bar on just failing tests you actually want to fix immediately. Later you can go back and fix the ignored tests. In other words, by ignoring some failing tests temporarily, you can more easily notice failed tests that you actually want to fix. By contrast, a pending test is intended to be used before a test and/or the code under test is written. Pending indicates you've decided to write a test for a bit of behavior, but either you haven't written the test yet, or have only written part of it, or perhaps you've written the test but don't want to implement the behavior it tests until after you've implemented a different bit of behavior you realized you need first. Thus ignored tests are designed to facilitate refactoring of existing code whereas pending tests are designed to facilitate the creation of new code. One other difference between ignored and pending tests is that ignored tests are implemented as a test tag that is excluded by default. Thus an ignored test is never executed. By contrast, a pending test is implemented as a test that throws
TestPendingException
(which is what calling the pending
method does). Thus
the body of pending tests are executed up until they throw TestPendingException
. The reason for this difference
is that it enables your unfinished test to send InfoProvided
messages to the reporter before it completes
abruptly with TestPendingException
, as shown in the previous example on Informer
s
that used the GivenWhenThen
trait.
== Tagging tests ==
A FunSuite
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a FunSuite
, groups of tests can
optionally be included and/or excluded. To tag a FunSuite
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for FunSuite
s like this:
package org.scalatest.examples.funsuite.taggingGiven these definitions, you could place
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
FunSuite
tests into groups like this:
import org.scalatest.FunSuiteThis code marks both tests with the
class SetSuite extends FunSuite {
test("An empty Set should have size 0", SlowTest) { assert(Set.empty.size === 0) }
test("Invoking head on an empty Set should produce NoSuchElementException", SlowTest, DbTest) { intercept[NoSuchElementException] { Set.empty.head } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
It is recommended, though not required, that you create a corresponding tag annotation when you
create a Tag
object. A tag annotation allows you to tag all the tests of a FunSuite
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.funsuite.getfixtureThe “
import org.scalatest.FunSuite import collection.mutable.ListBuffer
class ExampleSuite extends FunSuite {
def fixture = new { val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String] }
test("Testing should be easy") { val f = fixture f.builder.append("easy!") assert(f.builder.toString === "ScalaTest is easy!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
test("Testing should be fun") { val f = fixture f.builder.append("fun!") assert(f.builder.toString === "ScalaTest is fun!") assert(f.buffer.isEmpty) } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, if you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.funsuite.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.FunSuite
class ExampleSuite extends FunSuite {
trait Builder { val builder = new StringBuilder("ScalaTest is ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is") }
// This test needs the StringBuilder fixture test("Testing should be productive") { new Builder { builder.append("productive!") assert(builder.toString === "ScalaTest is productive!") } }
// This test needs the ListBuffer[String] fixture test("Test code should be readable") { new Buffer { buffer += ("readable!") assert(buffer === List("ScalaTest", "is", "readable!")) } }
// This test needs both the StringBuilder and ListBuffer test("Test code should be clear and concise") { new Builder with Buffer { builder.append("clear!") buffer += ("concise!") assert(builder.toString === "ScalaTest is clear!") assert(buffer === List("ScalaTest", "is", "concise!")) } } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. In other words, instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
and send that information to the reporter:
package org.scalatest.examples.funsuite.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSuite extends FunSuite {
override def withFixture(test: NoArgTest) = {
super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
test("This test should succeed") { assert(1 + 1 === 2) }
test("This test should fail") { assert(1 + 1 === 3) } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSuite execute
ExampleSuite:
- this test should succeed
- this test should fail *** FAILED ***
2 did not equal 3 (:33)
+ Dir snapshot: hello.txt, world.txt
Note that the NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
package org.scalatest.examples.funsuite.loanfixtureAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
import java.util.concurrent.ConcurrentHashMap
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.FunSuite import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSuite extends FunSuite {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
// This test needs the file fixture test("Testing should be productive") { withFile { (file, writer) => writer.write("productive!") writer.flush() assert(file.length === 24) } }
// This test needs the database fixture test("Test code should be readable") { withDatabase { db => db.append("readable!") assert(db.toString === "ScalaTest is readable!") } }
// This test needs both the file and the database test("Test code should be clear and concise") { withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("clear!") writer.write("concise!") writer.flush() assert(db.toString === "ScalaTest is clear!") assert(file.length === 21) } } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.Suite
and overriding withFixture(OneArgTest)
.
Each test in a fixture.Suite
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. In other words, instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.funsuite.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSuite extends fixture.FunSuite {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = {
// create the fixture val file = File.createTempFile("hello", "world") val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
test("Testing should be easy") { f => f.writer.write("easy!") f.writer.flush() assert(f.file.length === 18) }
test("Testing should be fun") { f => f.writer.write("fun!") f.writer.flush() assert(f.file.length === 17) } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.FunSuite
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.funsuite.beforeandafterNote that the only way
import org.scalatest.FunSuite import org.scalatest.BeforeAndAfter import collection.mutable.ListBuffer
class ExampleSuite extends FunSuite with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
test("testing should be easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
test("testing should be fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.funsuite.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSuite extends FunSuite with Builder with Buffer {
test("Testing should be easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
test("Testing should be fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } }
Builder
and Buffer
traits, ExampleSuite
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Suite extends Suite with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Suite extends Suite with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.funsuite.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import org.scalatest.BeforeAndAfterEach import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try { super.afterEach() // To be stackable, must call super.afterEach } finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try { super.afterEach() // To be stackable, must call super.afterEach } finally buffer.clear() } }
class ExampleSuite extends FunSuite with Builder with Buffer {
test("Testing should be easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
test("Testing should be fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared tests ==
Sometimes you may want to run the same test code on different fixture objects. In other words, you may want to write tests that are "shared"
by different fixture objects.
To accomplish this in a FunSuite
, you first place shared tests in
behavior functions. These behavior functions will be
invoked during the construction phase of any FunSuite
that uses them, so that the tests they contain will
be registered as tests in that FunSuite
.
For example, given this stack class:
import scala.collection.mutable.ListBufferYou may want to test the
class Stack[T] {
val MAX = 10 private val buf = new ListBuffer[T]
def push(o: T) { if (!full) buf.prepend(o) else throw new IllegalStateException("can't push onto a full stack") }
def pop(): T = { if (!empty) buf.remove(0) else throw new IllegalStateException("can't pop an empty stack") }
def peek: T = { if (!empty) buf(0) else throw new IllegalStateException("can't pop an empty stack") }
def full: Boolean = buf.size == MAX def empty: Boolean = buf.size == 0 def size = buf.size
override def toString = buf.mkString("Stack(", ", ", ")") }
Stack
class in different states: empty, full, with one item, with one item less than capacity,
etc. You may find you have several tests that make sense any time the stack is non-empty. Thus you'd ideally want to run
those same tests for three stack fixture objects: a full stack, a stack with a one item, and a stack with one item less than
capacity. With shared tests, you can factor these tests out into a behavior function, into which you pass the
stack fixture to use when running the tests. So in your FunSuite
for stack, you'd invoke the
behavior function three times, passing in each of the three stack fixtures so that the shared tests are run for all three fixtures.
You can define a behavior function that encapsulates these shared tests inside the FunSuite
that uses them. If they are shared
between different FunSuite
s, however, you could also define them in a separate trait that is mixed into
each FunSuite
that uses them.
For example, here the nonEmptyStack
behavior function (in this case, a
behavior method) is defined in a trait along with another
method containing shared tests for non-full stacks:
import org.scalatest.FunSuiteGiven these behavior functions, you could invoke them directly, but
trait FunSuiteStackBehaviors { this: FunSuite =>
def nonEmptyStack(createNonEmptyStack: => Stack[Int], lastItemAdded: Int) {
test("empty is invoked on this non-empty stack: " + createNonEmptyStack.toString) { val stack = createNonEmptyStack assert(!stack.empty) }
test("peek is invoked on this non-empty stack: " + createNonEmptyStack.toString) { val stack = createNonEmptyStack val size = stack.size assert(stack.peek === lastItemAdded) assert(stack.size === size) }
test("pop is invoked on this non-empty stack: " + createNonEmptyStack.toString) { val stack = createNonEmptyStack val size = stack.size assert(stack.pop === lastItemAdded) assert(stack.size === size - 1) } }
def nonFullStack(createNonFullStack: => Stack[Int]) {
test("full is invoked on this non-full stack: " + createNonFullStack.toString) { val stack = createNonFullStack assert(!stack.full) }
test("push is invoked on this non-full stack: " + createNonFullStack.toString) { val stack = createNonFullStack val size = stack.size stack.push(7) assert(stack.size === size + 1) assert(stack.peek === 7) } } }
FunSuite
offers a DSL for the purpose,
which looks like this:
testsFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) testsFor(nonFullStack(stackWithOneItem))If you prefer to use an imperative style to change fixtures, for example by mixing in
BeforeAndAfterEach
and
reassigning a stack
var
in beforeEach
, you could write your behavior functions
in the context of that var
, which means you wouldn't need to pass in the stack fixture because it would be
in scope already inside the behavior function. In that case, your code would look like this:
testsFor(nonEmptyStack) // assuming lastValuePushed is also in scope inside nonEmptyStack
testsFor(nonFullStack)
The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example:
import org.scalatest.FunSuiteIf you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, you'll see:
class StackFunSuite extends FunSuite with FunSuiteStackBehaviors {
// Stack fixture creation methods def emptyStack = new Stack[Int]
def fullStack = { val stack = new Stack[Int] for (i <- 0 until stack.MAX) stack.push(i) stack }
def stackWithOneItem = { val stack = new Stack[Int] stack.push(9) stack }
def stackWithOneItemLessThanCapacity = { val stack = new Stack[Int] for (i <- 1 to 9) stack.push(i) stack }
val lastValuePushed = 9
test("empty is invoked on an empty stack") { val stack = emptyStack assert(stack.empty) }
test("peek is invoked on an empty stack") { val stack = emptyStack intercept[IllegalStateException] { stack.peek } }
test("pop is invoked on an empty stack") { val stack = emptyStack intercept[IllegalStateException] { emptyStack.pop } }
testsFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) testsFor(nonFullStack(stackWithOneItem))
testsFor(nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed)) testsFor(nonFullStack(stackWithOneItemLessThanCapacity))
test("full is invoked on a full stack") { val stack = fullStack assert(stack.full) }
testsFor(nonEmptyStack(fullStack, lastValuePushed))
test("push is invoked on a full stack") { val stack = fullStack intercept[IllegalStateException] { stack.push(10) } } }
scala> new StackFunSuite execute
StackFunSuite:
- empty is invoked on an empty stack
- peek is invoked on an empty stack
- pop is invoked on an empty stack
- empty is invoked on this non-empty stack: Stack(9)
- peek is invoked on this non-empty stack: Stack(9)
- pop is invoked on this non-empty stack: Stack(9)
- full is invoked on this non-full stack: Stack(9)
- push is invoked on this non-full stack: Stack(9)
- empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- full is invoked on this non-full stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- push is invoked on this non-full stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- full is invoked on a full stack
- empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
- peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
- pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0)
- push is invoked on a full stack
One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name.
If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime
complaining that multiple tests are being registered with the same test name.
In a FunSuite
there is no nesting construct analogous to FunSpec
's describe
clause.
Therefore, you need to do a bit of
extra work to ensure that the test names are unique. If a duplicate test name problem shows up in a
FunSuite
, you'll need to pass in a prefix or suffix string to add to each test name. You can pass this string
the same way you pass any other data needed by the shared tests, or just call toString
on the shared fixture object.
This is the approach taken by the previous FunSuiteStackBehaviors
example.
Given this FunSuiteStackBehaviors
trait, calling it with the stackWithOneItem
fixture, like this:
testsFor(nonEmptyStack(stackWithOneItem, lastValuePushed))yields test names: -
empty is invoked on this non-empty stack: Stack(9)
- peek is invoked on this non-empty stack: Stack(9)
- pop is invoked on this non-empty stack: Stack(9)
Whereas calling it with the stackWithOneItemLessThanCapacity
fixture, like this:
testsFor(nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed))yields different test names: -
empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
- pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
Implementation trait for class FunSuite
, which represents
a suite of tests in which each test is represented as a function value.
Implementation trait for class FunSuite
, which represents
a suite of tests in which each test is represented as a function value.
FunSuite
is a class, not a trait,
to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the
behavior of FunSuite
into some other class, you can use this
trait instead, because class FunSuite
does nothing more than
extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed
overview of FunSuite
.
Trait that contains methods named given
, when
, then
, and and
,
which take a string message and implicit Informer
, and forward the message to the informer.
Trait that contains methods named given
, when
, then
, and and
,
which take a string message and implicit Informer
, and forward the message to the informer.
Here's an example:
package org.scalatest.examples.flatspec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends FlatSpec with GivenWhenThen {
"A mutable Set" should "allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } }
SetSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
Note: The lower case forms of given
, when
, then
and and
were
deprecated in ScalaTest because using then
as an identifier was deprecated in Scala 2.10.
Annotation used to tag a test, or suite of tests, as ignored.
Annotation used to tag a test, or suite of tests, as ignored.
Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible at runtime. It has been inserted into Scaladoc by pretending it is a trait.
If you wish to temporarily ignore an entire suite of tests, you can annotate the test class with @Ignore
, like this:
package org.scalatest.examples.flatspec.ignoreall import org.scalatest._ @Ignore class SetSpec extends FlatSpec { "An empty Set" should "have size 0" in { assert(Set.empty.size === 0) } it should "produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } }
When you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag.
Thus, marking the SetSpec
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSpec
in the Scala interpreter, you'll see:
scala> new SetSpec execute An empty Set - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invoked !!! IGNORED !!!
Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes
will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored
class somewhat visible, to encourage the developers to eventually fix and un-ignore it. If you want to
prevent a class from being discovered at all, use the DoNotDiscover
annotation instead.
Another use case for @Ignore
is to mark test methods as ignored in traits Spec
and fixture.Spec
. Here's an example:
package org.scalatest.examples.spec.ignore import org.scalatest._ class SetSpec extends Spec { @Ignore def `an empty Set should have size 0` { assert(Set.empty.size === 0) } def `invoking head on an empty Set should produce NoSuchElementException` { intercept[NoSuchElementException] { Set.empty.head } } }
If you run this version of SetSpec
in the Scala interpreter, you'll see that it
runs only the second test and reports that the first test was ignored:
scala> new SetSpec execute
SetSpec:
- an empty Set should have size 0 !!! IGNORED !!!
- invoking head on an empty Set should produce NoSuchElementException
Trait to which custom information about a running suite of tests can be reported.
Trait to which custom information about a running suite of tests can be reported.
An Informer
is essentially
used to wrap a Reporter
and provide easy ways to send custom information
to that Reporter
via an InfoProvided
event.
Informer
contains an apply
method that takes a string and
an optional payload object of type Any
.
The Informer
will forward the passed message
string to the
Reporter
as the message
parameter, and the optional
payload object as the payload
parameter, of an InfoProvided
event.
Here's an example in which the Informer
is used both directly via info
method of trait FlatSpec
and indirectly via the methods of
trait GivenWhenThen
:
package org.scalatest.examples.flatspec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends FlatSpec with GivenWhenThen {
"A mutable Set" should "allow an element to be added" in { given("an empty mutable Set") val set = mutable.Set.empty[String]
when("an element is added") set += "clarity"
then("the Set should have size 1") assert(set.size === 1)
and("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } }
SetSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
Trait that contains the info
method, which can be used to send info to the reporter.
Trait that contains the info
method, which can be used to send info to the reporter.
Trait containing the inside
construct, which allows you to make statements about nested object graphs using pattern matching.
Trait containing the inside
construct, which allows you to make statements about nested object graphs using pattern matching.
For example, given the following case classes:
case class Address(street: String, city: String, state: String, zip: String) case class Name(first: String, middle: String, last: String) case class Record(name: Name, address: Address, age: Int)
You could write:
inside (rec) { case Record(name, address, age) => inside (name) { case Name(first, middle, last) => first should be ("Sally") middle should be ("Ann") last should be ("Jones") } inside (address) { case Address(street, city, state, zip) => street should startWith ("25") city should endWith ("Angeles") state should equal ("CA") zip should be ("12345") } age should be < 99 }
If an assertion fails, the error message will include the toString
of each value passed
to inside
clauses enclosing the failed assertion. For example, if rec
in
the previous expression was defined like this:
val rec = Record( Name("Sally", "Anna", "Jones"), Address("25 Main St", "Los Angeles", "CA", "12345"), 38 )
The error message will read:
"Ann[a]" was not equal to "Ann[]", inside Name(Sally,Anna,Jones), inside Record(Name(Sally,Anna,Jones),Address(25 Main St,Los Angeles,CA,12345),38)
Provides nestable inspector methods (or just inspectors) that enable assertions to be made about collections.
Provides nestable inspector methods (or just inspectors) that enable assertions to be made about collections.
For example, the forAll
method enables you to state that something should be true about all elements of a collection, such
as that all elements should be positive:
scala> import org.scalatest._ import org.scalatest._ scala> import Assertions._ import Assertions._ scala> import Inspectors._ import Inspectors._ scala> val xs = List(1, 2, 3, 4, 5) xs: List[Int] = List(1, 2, 3, 4, 5) scala> forAll (xs) { x => assert(x > 0) }
Or, with matchers:
scala> import Matchers._ import Matchers._ scala> forAll (xs) { x => x should be > 0 }
To make assertions about nested collections, you can nest the inspector method invocations.
For example, given the following list of lists of Int
:
scala> val yss = | List( | List(1, 2, 3), | List(1, 2, 3), | List(1, 2, 3) | ) yss: List[List[Int]] = List(List(1, 2, 3), List(1, 2, 3), List(1, 2, 3))
You can assert that all Int
elements in all nested lists are positive by nesting two forAll
method invocations, like this:
scala> forAll (yss) { ys => | forAll (ys) { y => y should be > 0 } | }
The full list of inspector methods are:
forAll
- succeeds if the assertion holds true for every elementforAtLeast
- succeeds if the assertion holds true for at least the specified number of elementsforAtMost
- succeeds if the assertion holds true for at most the specified number of elementsforBetween
- succeeds if the assertion holds true for between the specified minimum and maximum number of elements, inclusiveforEvery
- same as forAll
, but lists all failing elements if it fails (whereas forAll
just reports the first failing element)forExactly
- succeeds if the assertion holds true for exactly the specified number of elementsThe error messages produced by inspector methods are designed to make sense no matter how deeply you nest the method invocations. Here's an example of a nested inspection that fails and the resulting error message:
scala> forAll (yss) { ys => | forAll (ys) { y => y should be < 2 } | } org.scalatest.exceptions.TestFailedException: forAll failed, because: at index 0, forAll failed, because: at index 1, 2 was not less than 2 (<console>:20) in List(1, 2, 3) (<console>:20) in List(List(1, 2, 3), List(1, 2, 3), List(1, 2, 3)) at org.scalatest.InspectorsHelper$.doForAll(Inspectors.scala:146) ...
One way the error message is designed to help you understand the error is by using indentation that mimics the indentation of the
source code (optimistically assuming the source will be nicely indented). The error message above indicates the outer forAll
failed
because its initial List
(i.e., at index 0) failed
the assertion, which was that all elements of that initial List[Int]
at index 0 should be less than 2. This assertion failed because index 1 of
that inner list contained the value 2, which was indeed “not less than 2.” The error message for the inner list is an indented line inside the error message
for the outer list. The actual contents of each list are displayed at the end in inspector error messages, also indented appropriately. The actual contents
are placed at the end so that for very large collections, the contents will not drown out and make it difficult to find the messages that describe
actual causes of the failure.
The forAll
and forEvery
methods are similar in that both succeed only if the assertion holds for all elements of the collection.
They differ in that forAll
will only report the first element encountered that failed the assertion, but forEvery
will report all
elements that fail the assertion. The tradeoff is that while forEvery
gives more information, it may take longer to run because it must inspect every element
of the collection. The forAll
method can simply stop inspecting once it encounters the first failing element. Here's an example that
shows the difference in the forAll
and forEvery
error messages:
scala> forAll (xs) { x => x should be < 3 } org.scalatest.exceptions.TestFailedException: forAll failed, because: at index 2, 3 was not less than 3 (<console>:18) in List(1, 2, 3, 4, 5) at org.scalatest.InspectorsHelper$.doForAll(Inspectors.scala:146) ... scala> forEvery (xs) { x => x should be < 3 } org.scalatest.exceptions.TestFailedException: forEvery failed, because: at index 2, 3 was not less than 3 (<console>:18), at index 3, 4 was not less than 3 (<console>:18), at index 4, 5 was not less than 3 (<console>:18) in List(1, 2, 3, 4, 5) at org.scalatest.InspectorsHelper$.doForEvery(Inspectors.scala:226) ...
Note that if you're using matchers, you can alternatively use inspector shorthands for writing non-nested inspections. Here's an example:
scala> all (xs) should be > 3 org.scalatest.exceptions.TestFailedException: 'all' inspection failed, because: at index 0, 1 was not greater than 3 in List(1, 2, 3, 4, 5) at org.scalatest.InspectorsHelper$.doForAll(Inspectors.scala:146)
You can use Inspectors
on any scala.collection.GenTraversable
, java.util.Collection
,
java.util.Map
(with Entry
), Array
, or String
.
Here are some examples:
scala> import org.scalatest._ import org.scalatest._ scala> import Inspectors._ import Inspectors._ scala> import Matchers._ import Matchers._ scala> forAll (Array(1, 2, 3)) { e => e should be < 5 } scala> import collection.JavaConverters._ import collection.JavaConverters._ scala> val js = List(1, 2, 3).asJava js: java.util.List[Int] = [1, 2, 3] scala> forAll (js) { j => j should be < 5 } scala> val jmap = Map("a" -> 1, "b" -> 2).asJava jmap: java.util.Map[String,Int] = {a=1, b=2} scala> forAtLeast(1, jmap) { e => e shouldBe Entry("b", 2) } scala> forAtLeast(2, "hello, world!") { c => c shouldBe 'o' }
Trait that provides an implicit conversion that adds to collection types a loneElement
method, which
will return the value of the lone element if the collection does
indeed contain one and only one element, or throw TestFailedException
if not.
Trait that provides an implicit conversion that adds to collection types a loneElement
method, which
will return the value of the lone element if the collection does
indeed contain one and only one element, or throw TestFailedException
if not.
This construct allows you to express in one statement that a collection should contain one and only one element and that the element value should meet some expectation. Here's an example:
set.loneElement should be > 9
Or, using an assertion instead of a matcher expression:
assert(set.loneElement > 9)
The loneElement
syntax can be used with any collection type C
for which an
implicit Collecting[C]
is available. ScalaTest provides
implicit Collecting
instances for scala.collection.GenTraversable
, Array
,
and java.util.Collection
. You can enable the loneElement
syntax on other collection types by defining an implicit Collecting
instances for those types.
If you want to use loneElement
with a java.util.Map
, first transform it to a
set of entries with entrySet
, and if helpful, use ScalaTest's Entry
class:
scala> import org.scalatest._ import org.scalatest._ scala> import LoneElement._ import LoneElement._ scala> import Matchers._ import Matchers._ scala> val jmap = new java.util.HashMap[String, Int] jmap: java.util.HashMap[String,Int] = {} scala> jmap.put("one", 1) res0: Int = 0 scala> jmap.entrySet.loneElement should be (Entry("one", 1))
Trait that provides a domain specific language (DSL) for expressing assertions in tests
using the word should
.
Trait that provides a domain specific language (DSL) for expressing assertions in tests
using the word should
.
For example, if you mix Matchers
into
a suite class, you can write an equality assertion in that suite like this:
result should equal (3)
Here result
is a variable, and can be of any type. If the object is an
Int
with the value 3, execution will continue (i.e., the expression will result
in the unit value, ()
). Otherwise, a TestFailedException
will be thrown with a detail message that explains the problem, such as "7 did not equal 3"
.
This TestFailedException
will cause the test to fail.
Here is a table of contents for this documentation:
Boolean
properties with be
BeMatchers
String
s and Array
s as collectionsand
and or
Option
shave
length
and size
with HavePropertyMatcher
sTrait MustMatchers
is an alternative to Matchers
that provides the exact same
meaning, syntax, and behavior as Matchers
, but uses the verb must
instead of should
.
The two traits differ only in the English semantics of the verb: should
is informal, making the code feel like conversation between the writer and the reader; must
is more formal, making the code feel more like
a written specification.
Prior to 2.0, ScalaTest's matchers DSL was provided by traits
org.scalatest.matchers.ShouldMatchers
and
org.scalatest.matchers.MustMatchers
. These are now deprecated in favor of
traits in package org.scalatest
. The fully qualified name of the original
ShouldMatchers
is now org.scalatest.Matchers
, and the fully qualified
name of the original MustMatchers
is now org.scalatest.MustMatchers
.
The old fully qualified names will continue to work during a lengthy deprecation cycle, but
will generate a deprecation warning and eventually be removed in a future version
of ScalaTest. You can migrate existing uses of ShouldMatchers
by simply importing
or mixing in org.scalatest.Matchers
instead of
org.scalatest.matchers.ShouldMatchers
, and can migrate existing
uses of org.scalatest.matchers.MustMatchers
by importing or
mixing in org.scalatest.MustMatchers
instead of org.scalatest.matchers.MustMatchers
.
Two other deprecations in ScalaTest 2.0 matchers are be
===
<value>
and evaluating
...
should
produce
syntax. This will both continue to work as before, but will generate a deprecation
warning and eventually be removed in a future version of ScalaTest. the be
===
syntax is being deprecated so that all uses
of ===
in ScalaTest consistently provide the new
features of tunable type checking, tolerance support, and customized equality. Please replace uses of this syntax with one of the other
ways to check equality described in the next section. The eventually
syntax is being deprecated because it is replaced by thrownBy
clauses, as described below.
Although ScalaTest's matchers have undergone a major refactor in 2.0, all previously documented syntax for matchers should continue to work exactly
the same with one potential exception, which should in practice be extremely rare. The potential breakage is that if you included length
or size
along with custom have-property matchers that you wrote, you'll get a compiler error. To fix such an error, add after
your length
or size
invocation an (of [<type>])
clause, as
described below.
The only other source of potential breakage is the fragile base class problem. We have added fields and methods to Matchers
in 2.0 that may
conflict with fields and methods in your existing classes and cause a compiler error. Such issues can usually be easily fixed locally with simple renames or refactors,
but if you prefer to subtract a token from Matchers
, you can do so by mixing together your own Matchers
trait
from component traits, as described below. Note that you should not see any new implicit conflicts, because we managed to reduce the number
of implicits brought into scope by 2.0 matchers compared to 1.x by about 75%.
ScalaTest matchers provides five different ways to check equality, each designed to address a different need. They are:
result should equal (3) // can customize equality result should === (3) // can customize equality and enforce type constraints result should be (3) // cannot customize equality, so fastest to compile result shouldEqual 3 // can customize equality, no parentheses required result shouldBe 3 // cannot customize equality, so fastest to compile, no parentheses required
The “left
should
equal
(right)
” syntax requires an
org.scalactic.Equality[L]
to be provided (either implicitly or explicitly), where
L
is the left-hand type on which should
is invoked. In the "left
should
equal
(right)
" case,
for example, L
is the type of left
. Thus if left
is type Int
, the "left
should
equal
(right)
"
statement would require an Equality[Int]
.
By default, an implicit Equality[T]
instance is available for any type T
, in which equality is implemented
by simply invoking ==
on the left
value, passing in the right
value, with special treatment for arrays. If either left
or right
is an array, deep
will be invoked on it before comparing with ==. Thus, the following expression
will yield false, because Array
's equals
method compares object identity:
Array(1, 2) == Array(1, 2) // yields false
The next expression will by default not result in a TestFailedException
, because default Equality[Array[Int]]
compares
the two arrays structurally, taking into consideration the equality of the array's contents:
Array(1, 2) should equal (Array(1, 2)) // succeeds (i.e., does not throw TestFailedException)
If you ever do want to verify that two arrays are actually the same object (have the same identity), you can use the
be theSameInstanceAs
syntax, described below.
You can customize the meaning of equality for a type when using "should
equal
," "should
===
,"
or shouldEqual
syntax by defining implicit Equality
instances that will be used instead of default Equality
.
You might do this to normalize types before comparing them with ==
, for instance, or to avoid calling the ==
method entirely,
such as if you want to compare Double
s with a tolerance.
For an example, see the main documentation of trait Equality
.
You can always supply implicit parameters explicitly, but in the case of implicit parameters of type Equality[T]
, Scalactic provides a
simple "explictly" DSL. For example, here's how you could explicitly supply an Equality[String]
instance that normalizes both left and right
sides (which must be strings), by transforming them to lowercase:
scala> import org.scalatest.Matchers._ import org.scalatest.Matchers._ scala> import org.scalactic.Explicitly._ import org.scalactic.Explicitly._ scala> import org.scalactic.StringNormalizations._ import org.scalactic.StringNormalizations._ scala> "Hi" should equal ("hi") (after being lowerCased)
The after
being
lowerCased
expression results in an Equality[String]
, which is then passed
explicitly as the second curried parameter to equal
. For more information on the explictly DSL, see the main documentation
for trait Explicitly
.
The "should
be
" and shouldBe
syntax do not take an Equality[T]
and can therefore not be customized.
They always use the default approach to equality described above. As a result, "should
be
" and shouldBe
will
likely be the fastest-compiling matcher syntax for equality comparisons, since the compiler need not search for
an implicit Equality[T]
each time.
The should
===
syntax (and its complement, should
!==
) can be used to enforce type
constraints at compile-time between the left and right sides of the equality comparison. Here's an example:
scala> import org.scalatest.Matchers._ import org.scalatest.Matchers._ scala> import org.scalactic.TypeCheckedTripleEquals._ import org.scalactic.TypeCheckedTripleEquals._ scala> Some(2) should === (2) <console>:17: error: types Some[Int] and Int do not adhere to the equality constraint selected for the === and !== operators; the missing implicit parameter is of type org.scalactic.Constraint[Some[Int],Int] Some(2) should === (2) ^
By default, the "Some(2)
should
===
(2)
" statement would fail at runtime. By mixing in
the equality constraints provided by TypeCheckedTripleEquals
, however, the statement fails to compile. For more information
and examples, see the main documentation for trait TypeCheckedTripleEquals
.
You can check the size or length of any type of object for which it makes sense. Here's how checking for length looks:
result should have length 3
Size is similar:
result should have size 10
The length
syntax can be used with String
, Array
, any scala.collection.GenSeq
,
any java.util.List
, and any type T
for which an implicit Length[T]
type class is
available in scope.
Similarly, the size
syntax can be used with Array
, any scala.collection.GenTraversable
,
any java.util.Collection
, any java.util.Map
, and any type T
for which an implicit Size[T]
type class is
available in scope. You can enable the length
or size
syntax for your own arbitrary types, therefore,
by defining Length
or Size
type
classes for those types.
In addition, the length
syntax can be used with any object that has a field or method named length
or a method named getLength
. Similarly, the size
syntax can be used with any
object that has a field or method named size
or a method named getSize
.
The type of a length
or size
field, or return type of a method, must be either Int
or Long
. Any such method must take no parameters. (The Scala compiler will ensure at compile time that
the object on which should
is being invoked has the appropriate structure.)
You can check for whether a string starts with, ends with, or includes a substring like this:
string should startWith ("Hello") string should endWith ("world") string should include ("seven")
You can check for whether a string starts with, ends with, or includes a regular expression, like this:
string should startWith regex "Hel*o" string should endWith regex "wo.ld" string should include regex "wo.ld"
And you can check whether a string fully matches a regular expression, like this:
string should fullyMatch regex """(-)?(\d+)(\.\d*)?"""
The regular expression passed following the regex
token can be either a String
or a scala.util.matching.Regex
.
With the startWith
, endWith
, include
, and fullyMatch
tokens can also be used with an optional specification of required groups, like this:
"abbccxxx" should startWith regex ("a(b*)(c*)" withGroups ("bb", "cc")) "xxxabbcc" should endWith regex ("a(b*)(c*)" withGroups ("bb", "cc")) "xxxabbccxxx" should include regex ("a(b*)(c*)" withGroups ("bb", "cc")) "abbcc" should fullyMatch regex ("a(b*)(c*)" withGroups ("bb", "cc"))
You can check whether a string is empty with empty
:
s shouldBe empty
You can also use most of ScalaTest's matcher syntax for collections on String
by
treating the String
s as collections of characters. For examples, see the
String
s and Array
s as collections section below.
You can check whether any type for which an implicit Ordering[T]
is available
is greater than, less than, greater than or equal, or less
than or equal to a value of type T
. The syntax is:
one should be < 7 one should be > 0 one should be <= 7 one should be >= 0
Boolean
properties with be
If an object has a method that takes no parameters and returns boolean, you can check
it by placing a Symbol
(after be
) that specifies the name
of the method (excluding an optional prefix of "is
"). A symbol literal
in Scala begins with a tick mark and ends at the first non-identifier character. Thus,
'traversableAgain
results in a Symbol
object at runtime, as does
'completed
and 'file
. Here's an example:
iter shouldBe 'traversableAgain
Given this code, ScalaTest will use reflection to look on the object referenced from
emptySet
for a method that takes no parameters and results in Boolean
,
with either the name empty
or isEmpty
. If found, it will invoke
that method. If the method returns true
, execution will continue. But if it returns
false
, a TestFailedException
will be thrown that will contain a detail message, such as:
non-empty iterator was not traversableAgain
This be
syntax can be used with any reference (AnyRef
) type. If the object does
not have an appropriately named predicate method, you'll get a TestFailedException
at runtime with a detailed message that explains the problem.
(For the details on how a field or method is selected during this
process, see the documentation for BeWord
.)
If you think it reads better, you can optionally put a
or an
after
be
. For example, java.io.File
has two predicate methods,
isFile
and isDirectory
. Thus with a File
object
named temp
, you could write:
temp should be a 'file
Or, given java.awt.event.KeyEvent
has a method isActionKey
that takes
no arguments and returns Boolean
, you could assert that a KeyEvent
is
an action key with:
keyEvent should be an 'actionKey
If you prefer to check Boolean
properties in a type-safe manner, you can use a BePropertyMatcher
.
This would allow you to write expressions such as:
xs shouldBe traversableAgain temp should be a file keyEvent should be an actionKey
These expressions would fail to compile if should
is used on an inappropriate type, as determined
by the type parameter of the BePropertyMatcher
being used. (For example, file
in this example
would likely be of type BePropertyMatcher[java.io.File]
. If used with an appropriate type, such an expression will compile
and at run time the Boolean
property method or field will be accessed directly; i.e., no reflection will be used.
See the documentation for BePropertyMatcher
for more information.
BeMatchers
If you want to create a new way of using be
, which doesn't map to an actual property on the
type you care about, you can create a BeMatcher
. You could use this, for example, to create BeMatcher[Int]
called odd
, which would match any odd Int
, and even
, which would match
any even Int
.
Given this pair of BeMatcher
s, you could check whether an Int
was odd or even with expressions like:
num shouldBe odd num should not be even
For more information, see the documentation for BeMatcher
.
If you need to check that two references refer to the exact same object, you can write:
ref1 should be theSameInstanceAs ref2
If you need to check that an object is an instance of a particular class or trait, you can supply the type to
“be
a
” or “be
an
”:
result1 shouldBe a [Tiger] result1 should not be an [Orangutan]
Because type parameters are erased on the JVM, we recommend you insert an underscore for any type parameters
when using this syntax. Both of the following test only that the result is an instance of List[_]
, because at
runtime the type parameter has been erased:
result shouldBe a [List[_]] // recommended result shouldBe a [List[Fruit]] // discouraged
Often you may want to check whether a number is within a
range. You can do that using the +-
operator, like this:
sevenDotOh should equal (6.9 +- 0.2) sevenDotOh should === (6.9 +- 0.2) sevenDotOh should be (6.9 +- 0.2) sevenDotOh shouldEqual 6.9 +- 0.2 sevenDotOh shouldBe 6.9 +- 0.2
Any of these expressions will cause a TestFailedException
to be thrown if the floating point
value, sevenDotOh
is outside the range 6.7
to 7.1
.
You can use +-
with any type T
for which an implicit Numeric[T]
exists, such as integral types:
seven should equal (6 +- 2) seven should === (6 +- 2) seven should be (6 +- 2) seven shouldEqual 6 +- 2 seven shouldBe 6 +- 2
You can check whether an object is "empty", like this:
traversable shouldBe empty javaMap should not be empty
The empty
token can be used with any type L
for which an implicit Emptiness[L]
exists.
The Emptiness
companion object provides implicits for GenTraversable[E]
, java.util.Collection[E]
,
java.util.Map[K, V]
, String
, Array[E]
, and Option[E]
. In addition, the
Emptiness
companion object provides structural implicits for types that declare an isEmpty
method that
returns a Boolean
. Here are some examples:
scala> import org.scalatest.Matchers._ import org.scalatest.Matchers._ scala> List.empty shouldBe empty scala> None shouldBe empty scala> Some(1) should not be empty scala> "" shouldBe empty scala> new java.util.HashMap[Int, Int] shouldBe empty scala> new { def isEmpty = true} shouldBe empty scala> Array(1, 2, 3) should not be empty
You can check whether a collection contains a particular element like this:
traversable should contain ("five")
The contain
syntax shown above can be used with any type C
that has a "containing" nature, evidenced by
an implicit org.scalatest.enablers.Containing[L]
, where L
is left-hand type on
which should
is invoked. In the Containing
companion object, implicits are provided for types GenTraversable[E]
, java.util.Collection[E]
,
java.util.Map[K, V]
, String
, Array[E]
, and Option[E]
.
Here are some examples:
scala> import org.scalatest.Matchers._ import org.scalatest.Matchers._ scala> List(1, 2, 3) should contain (2) scala> Map('a' -> 1, 'b' -> 2, 'c' -> 3) should contain ('b' -> 2) scala> Set(1, 2, 3) should contain (2) scala> Array(1, 2, 3) should contain (2) scala> "123" should contain ('2') scala> Some(2) should contain (2)
ScalaTest's implicit methods that provide the Containing[L]
type classes require an Equality[E]
, where
E
is an element type. For example, to obtain a Containing[Array[Int]]
you must supply an Equality[Int]
,
either implicitly or explicitly. The contain
syntax uses this Equality[E]
to determine containership.
Thus if you want to change how containership is determined for an element type E
, place an implicit Equality[E]
in scope or use the explicitly DSL. Although the implicit parameter required for the contain
syntax is of type Containing[L]
,
implicit conversions are provided in the Containing
companion object from Equality[E]
to the various
types of containers of E
. Here's an example:
scala> import org.scalatest.Matchers._ import org.scalatest.Matchers._ scala> List("Hi", "Di", "Ho") should contain ("ho") org.scalatest.exceptions.TestFailedException: List(Hi, Di, Ho) did not contain element "ho" at ... scala> import org.scalactic.Explicitly._ import org.scalactic.Explicitly._ scala> import org.scalactic.StringNormalizations._ import org.scalactic.StringNormalizations._ scala> (List("Hi", "Di", "Ho") should contain ("ho")) (after being lowerCased)
Note that when you use the explicitly DSL with contain
you need to wrap the entire
contain
expression in parentheses, as shown here.
(List("Hi", "Di", "Ho") should contain ("ho")) (after being lowerCased) ^ ^
In addition to determining whether an object contains another object, you can use contain
to
make other determinations.
For example, the contain
oneOf
syntax ensures that one and only one of the specified elements are
contained in the containing object:
List(1, 2, 3, 4, 5) should contain oneOf (5, 7, 9) Some(7) should contain oneOf (5, 7, 9) "howdy" should contain oneOf ('a', 'b', 'c', 'd')
Note that if multiple specified elements appear in the containing object, oneOf
will fail:
scala> List(1, 2, 3) should contain oneOf (2, 3, 4) org.scalatest.exceptions.TestFailedException: List(1, 2, 3) did not contain one of (2, 3, 4) at ...
If you really want to ensure one or more of the specified elements are contained in the containing object,
use atLeastOneOf
, described below, instead of oneOf
. Keep in mind, oneOf
means "exactly one of."
Note also that with any contain
syntax, you can place custom implicit Equality[E]
instances in scope
to customize how containership is determined, or use the explicitly DSL. Here's an example:
(Array("Doe", "Ray", "Me") should contain oneOf ("X", "RAY", "BEAM")) (after being lowerCased)
The contain
noneOf
syntax does the opposite of oneOf
: it ensures none of the specified elements
are contained in the containing object:
List(1, 2, 3, 4, 5) should contain noneOf (7, 8, 9) Some(0) should contain noneOf (7, 8, 9) "12345" should contain noneOf ('7', '8', '9')
As mentioned, the "contain
," "contain
oneOf
," and "contain
noneOf
" syntax requires a
Containing[L]
be provided, where L
is the left-hand type. Other contain
syntax, which
will be described in this section, requires an Aggregating[L]
be provided, where again L
is the left-hand type.
(An Aggregating[L]
instance defines the "aggregating nature" of a type L
.)
The reason, essentially, is that contain
syntax that makes sense for Option
is enabled by
Containing[L]
, whereas syntax that does not make sense for Option
is enabled
by Aggregating[L]
. For example, it doesn't make sense to assert that an Option[Int]
contains all of a set of integers, as it
could only ever contain one of them. But this does make sense for a type such as List[Int]
that can aggregate zero to many integers.
The Aggregating
companion object provides implicit instances of Aggregating[L]
for types GenTraversable[E]
, java.util.Collection[E]
,
java.util.Map[K, V]
, String
, Array[E]
. Note that these are the same types as are supported with
Containing
, but with Option[E]
missing.
Here are some examples:
The contain
atLeastOneOf
syntax, for example, works for any type L
for which an Aggregating[L]
exists. It ensures
that at least one of (i.e., one or more of) the specified objects are contained in the containing object:
List(1, 2, 3) should contain atLeastOneOf (2, 3, 4) Array(1, 2, 3) should contain atLeastOneOf (3, 4, 5) "abc" should contain atLeastOneOf ('c', 'a', 't')
Similar to Containing[L]
, the implicit methods that provide the Aggregating[L]
instances require an Equality[E]
, where
E
is an element type. For example, to obtain a Aggregating[Vector[String]]
you must supply an Equality[String]
,
either implicitly or explicitly. The contain
syntax uses this Equality[E]
to determine containership.
Thus if you want to change how containership is determined for an element type E
, place an implicit Equality[E]
in scope or use the explicitly DSL. Although the implicit parameter required for the contain
syntax is of type Aggregating[L]
,
implicit conversions are provided in the Aggregating
companion object from Equality[E]
to the various
types of aggregations of E
. Here's an example:
(Vector(" A", "B ") should contain atLeastOneOf ("a ", "b", "c")) (after being lowerCased and trimmed)
The "contain
atMostOneOf
" syntax lets you specify a set of objects at most one of which should be contained in the containing object:
List(1, 2, 3, 4, 5) should contain atMostOneOf (5, 6, 7)
The "contain
allOf
" syntax lets you specify a set of objects that should all be contained in the containing object:
List(1, 2, 3, 4, 5) should contain allOf (2, 3, 5)
The "contain
only
" syntax lets you assert that the containing object contains only the specified objects, though it may
contain more than one of each:
List(1, 2, 3, 2, 1) should contain only (1, 2, 3)
The "contain
theSameElementsAs
" and "contain
theSameElementsInOrderAs
syntax differ from the others
in that the right hand side is a GenTraversable[_]
rather than a varargs of Any
. (Note: in a future 2.0 milestone release, possibly
2.0.M6, these will likely be widened to accept any type R
for which an Aggregating[R]
exists.)
The "contain
theSameElementsAs
" syntax lets you assert that two aggregations contain the same objects:
List(1, 2, 2, 3, 3, 3) should contain theSameElementsAs Vector(3, 2, 3, 1, 2, 3)
The number of times any family of equal objects appears must also be the same in both the left and right aggregations. The specified objects may appear multiple times, but must appear in the order they appear in the right-hand list. For example, if the last 3 element is left out of the right-hand list in the previous example, the expression would fail because the left side has three 3's and the right hand side has only two:
List(1, 2, 2, 3, 3, 3) should contain theSameElementsAs Vector(3, 2, 3, 1, 2) org.scalatest.exceptions.TestFailedException: List(1, 2, 2, 3, 3, 3) did not contain the same elements as Vector(3, 2, 3, 1, 2) at ...
The rest of the contain
syntax, which
will be described in this section, requires a Sequencing[L]
be provided, where again L
is the left-hand type.
(A Sequencing[L]
instance defines the "sequencing nature" of a type L
.)
The reason, essentially, is that contain
syntax that implies an "order" of elements makes sense only for types that place elements in a sequence.
For example, it doesn't make sense to assert that a Map[String, Int]
or Set[Int]
contains all of a set of integers in a particular
order, as these types don't necessarily define an order for their elements. But this does make sense for a type such as Seq[Int]
that does define
an order for its elements.
The Sequencing
companion object provides implicit instances of Sequencing[L]
for types GenSeq[E]
, java.util.List[E]
,
String
, and Array[E]
.
Here are some examples:
Similar to Containing[L]
, the implicit methods that provide the Aggregating[L]
instances require an Equality[E]
, where
E
is an element type. For example, to obtain a Aggregating[Vector[String]]
you must supply an Equality[String]
,
either implicitly or explicitly. The contain
syntax uses this Equality[E]
to determine containership.
Thus if you want to change how containership is determined for an element type E
, place an implicit Equality[E]
in scope or use the explicitly DSL. Although the implicit parameter required for the contain
syntax is of type Aggregating[L]
,
implicit conversions are provided in the Aggregating
companion object from Equality[E]
to the various
types of aggregations of E
. Here's an example:
The "contain
inOrderOnly
" syntax lets you assert that the containing object contains only the specified objects, in order.
The specified objects may appear multiple times, but must appear in the order they appear in the right-hand list. Here's an example:
List(1, 2, 2, 3, 3, 3) should contain inOrderOnly (1, 2, 3)
The "contain
inOrder
" syntax lets you assert that the containing object contains only the specified objects in order, like
inOrderOnly
, but allows other objects to appear in the left-hand aggregation as well:
contain more than one of each:
List(0, 1, 2, 2, 99, 3, 3, 3, 5) should contain inOrder (1, 2, 3)
Note that "order" in inOrder
, inOrderOnly
, and theSameElementsInOrderAs
(described below)
in the Aggregation[L]
instances built-in to ScalaTest is defined as "iteration order".
Lastly, the "contain
theSameElementsInOrderAs
" syntax lets you assert that two aggregations contain
the same exact elements in the same (iteration) order:
List(1, 2, 3) should contain theSameElementsInOrderAs collection.mutable.TreeSet(3, 2, 1)
The previous assertion succeeds because the iteration order of aTreeSet
is the natural
ordering of its elements, which in this case is 1, 2, 3. An iterator obtained from the left-hand List
will produce the same elements
in the same order.
You can also ask whether the elements of "sortable" objects (such as Array
s, Java List
s, and GenSeq
s)
are in sorted order, like this:
List(1, 2, 3) shouldBe sorted
Althought it seems desireable to provide similar matcher syntax for Scala and Java iterators to that provided for sequences like
Seq
s, Array
, and java.util.List
, the
ephemeral nature of iterators makes this problematic. Some syntax (such as should
contain
) is relatively straightforward to
support on iterators, but other syntax (such
as, for example, Inspector
expressions on nested iterators) is not. Rather
than allowing inconsistencies between sequences and iterators in the API, we chose to not support any such syntax directly on iterators:
scala> val it = List(1, 2, 3).iterator it: Iterator[Int] = non-empty iteratorInstead, you will need to convert your iterators to a sequence explicitly before using them in matcher expressions:
scala> it should contain (2) <console>:15: error: could not find implicit value for parameter typeClass1: org.scalatest.enablers.Containing[Iterator[Int]] it should contain (2) ^
scala> it.toStream should contain (2)
We recommend you convert (Scala or Java) iterators to Stream
s, as shown in the previous example, so that you can
continue to reap any potential benefits provided by the laziness of the underlying iterator.
== Inspector shorthands ==
You can use the Inspectors
syntax with matchers as well as assertions. If you have a multi-dimensional collection, such as a
list of lists, using Inspectors
is your best option:
val yss = List( List(1, 2, 3), List(1, 2, 3), List(1, 2, 3) )For assertions on one-dimensional collections, however, matchers provides "inspector shorthands." Instead of writing:
forAll (yss) { ys => forAll (ys) { y => y should be > 0 } }
val xs = List(1, 2, 3) forAll (xs) { x => x should be < 10 }You can write:
all (xs) should be < 10
The previous statement asserts that all elements of the xs
list should be less than 10.
All of the inspectors have shorthands in matchers. Here is the full list:
- all
- succeeds if the assertion holds true for every element
- atLeast
- succeeds if the assertion holds true for at least the specified number of elements
- atMost
- succeeds if the assertion holds true for at most the specified number of elements
- between
- succeeds if the assertion holds true for between the specified minimum and maximum number of elements, inclusive
- every
- same as all
, but lists all failing elements if it fails (whereas all
just reports the first failing element)
- exactly
- succeeds if the assertion holds true for exactly the specified number of elements
Here are some examples:
scala> import org.scalatest.Matchers._ import org.scalatest.Matchers._ scala> val xs = List(1, 2, 3, 4, 5) xs: List[Int] = List(1, 2, 3, 4, 5) scala> all (xs) should be > 0 scala> atMost (2, xs) should be >= 4 scala> atLeast (3, xs) should be < 5 scala> between (2, 3, xs) should (be > 1 and be < 5) scala> exactly (2, xs) should be <= 2 scala> every (xs) should be < 10 scala> // And one that fails... scala> exactly (2, xs) shouldEqual 2 org.scalatest.exceptions.TestFailedException: 'exactly(2)' inspection failed, because only 1 element satisfied the assertion block at index 1: at index 0, 1 did not equal 2, at index 2, 3 did not equal 2, at index 3, 4 did not equal 2, at index 4, 5 did not equal 2 in List(1, 2, 3, 4, 5) at ...Like
Inspectors
, objects used with inspector shorthands can be any type T
for which a Collecting[T, E]
is availabe, which by default includes GenTraversable
,
Java Collection
, Java Map
, Array
s, and String
s.
Here are some examples:
scala> import org.scalatest._ import org.scalatest._ scala> import Matchers._ import Matchers._ scala> all (Array(1, 2, 3)) should be < 5 scala> import collection.JavaConverters._ import collection.JavaConverters._ scala> val js = List(1, 2, 3).asJava js: java.util.List[Int] = [1, 2, 3] scala> all (js) should be < 5 scala> val jmap = Map("a" -> 1, "b" -> 2).asJava jmap: java.util.Map[String,Int] = {a=1, b=2} scala> atLeast(1, jmap) shouldBe Entry("b", 2) scala> atLeast(2, "hello, world!") shouldBe 'o'== Single-element collections == To assert both that a collection contains just one "lone" element as well as something else about that element, you can use the
loneElement
syntax provided by trait LoneElement
. For example, if a
Set[Int]
should contain just one element, an Int
less than or equal to 10, you could write:
import LoneElement._ set.loneElement should be <= 10You can invoke
loneElement
on any type T
for which an implicit Collecting[E, T]
is available, where E
is the element type returned by the loneElement
invocation. By default, you can use loneElement
on GenTraversable
, Java Collection
, Java Map
, Array
, and String
.
== Java collections and maps ==
You can use similar syntax on Java collections (java.util.Collection
) and maps (java.util.Map
).
For example, you can check whether a Java Collection
or Map
is empty
,
like this:
javaCollection should be ('empty) javaMap should be ('empty)Even though Java's
List
type doesn't actually have a length
or getLength
method,
you can nevertheless check the length of a Java List
(java.util.List
) like this:
javaList should have length 9
You can check the size of any Java Collection
or Map
, like this:
javaMap should have size 20 javaSet should have size 90In addition, you can check whether a Java
Collection
contains a particular
element, like this:
javaCollection should contain ("five")
One difference to note between the syntax supported on Java and Scala collections is that
in Java, Map
is not a subtype of Collection
, and does not
actually define an element type. You can ask a Java Map
for an "entry set"
via the entrySet
method, which will return the Map
's key/value pairs
wrapped in a set of java.util.Map.Entry
, but a Map
is not actually
a collection of Entry
. To make Java Map
s easier to work with, however,
ScalaTest matchers allows you to treat a Java Map
as a collection of Entry
,
and defines a convenience implementation of java.util.Map.Entry
in
org.scalatest.Entry
. Here's how you use it:
javaMap should contain (Entry(2, 3)) javaMap should contain oneOf (Entry(2, 3), Entry(3, 4))You can you alse just check whether a Java
Map
contains a particular key, or value, like this:
javaMap should contain key 1 javaMap should contain value "Howdy"==
String
s and Array
s as collections ==
You can also use all the syntax described above for Scala and Java collections on Array
s and
String
s. Here are some examples:
scala> import org.scalatest._ import org.scalatest._ scala> import Matchers._ import Matchers._ scala> atLeast (2, Array(1, 2, 3)) should be > 1 scala> atMost (2, "halloo") shouldBe 'o' scala> Array(1, 2, 3) shouldBe sorted scala> "abcdefg" shouldBe sorted scala> Array(1, 2, 3) should contain atMostOneOf (3, 4, 5) scala> "abc" should contain atMostOneOf ('c', 'd', 'e')==
be
as an equality comparison ==
All uses of be
other than those shown previously perform an equality comparison. They work
the same as equal
when it is used with default equality. This redundancy between be
and equals
exists in part
because it enables syntax that sometimes sounds more natural. For example, instead of writing:
result should equal (null)
You can write:
result should be (null)
(Hopefully you won't write that too much given null
is error prone, and Option
is usually a better, well, option.)
As mentioned previously, the other difference between equal
and be
is that equal
delegates the equality check to an Equality
typeclass, whereas
be
always uses default equality.
Here are some other examples of be
used for equality comparison:
sum should be (7.0) boring should be (false) fun should be (true) list should be (Nil) option should be (None) option should be (Some(1))As with
equal
used with default equality, using be
on arrays results in deep
being called on both arrays prior to
calling equal
. As a result,
the following expression would not throw a TestFailedException
:
Array(1, 2) should be (Array(1, 2)) // succeeds (i.e., does not throw TestFailedException)Because
be
is used in several ways in ScalaTest matcher syntax, just as it is used in many ways in English, one
potential point of confusion in the event of a failure is determining whether be
was being used as an equality comparison or
in some other way, such as a property assertion. To make it more obvious when be
is being used for equality, the failure
messages generated for those equality checks will include the word equal
in them. For example, if this expression fails with a
TestFailedException
:
option should be (Some(1))The detail message in that
TestFailedException
will include the words "equal to"
to signify be
was in this case being used for equality comparison:
Some(2) was not equal to Some(1)== Being negative == If you wish to check the opposite of some condition, you can simply insert
not
in the expression.
Here are a few examples:
result should not be (null) sum should not be <= (10) mylist should not equal (yourList) string should not startWith ("Hello")== Checking that a snippet of code does not compile == Often when creating libraries you may wish to ensure that certain arrangements of code that represent potential “user errors” do not compile, so that your library is more error resistant. ScalaTest
Matchers
trait includes the following syntax for that purpose:
"val a: String = 1" shouldNot compile
If you want to ensure that a snippet of code does not compile because of a type error (as opposed
to a syntax error), use:
"val a: String = 1" shouldNot typeCheck
Note that the shouldNot
typeCheck
syntax will only succeed if the given snippet of code does not
compile because of a type error. A syntax error will still result on a thrown TestFailedException
.
If you want to state that a snippet of code does compile, you can make that
more obvious with:
"val a: Int = 1" should compile
Although the previous three constructs are implemented with macros that determine at compile time whether
the snippet of code represented by the string does or does not compile, errors
are reported as test failures at runtime.
== Logical expressions with and
and or
==
You can also combine matcher expressions with and
and/or or
, however,
you must place parentheses or curly braces around the and
or or
expression. For example,
this and
-expression would not compile, because the parentheses are missing:
map should contain key ("two") and not contain value (7) // ERROR, parentheses missing!Instead, you need to write:
map should (contain key ("two") and not contain value (7))Here are some more examples:
number should (be > (0) and be <= (10)) option should (equal (Some(List(1, 2, 3))) or be (None)) string should ( equal ("fee") or equal ("fie") or equal ("foe") or equal ("fum") )Two differences exist between expressions composed of these
and
and or
operators and the expressions you can write
on regular Boolean
s using its &&
and ||
operators. First, expressions with and
and or
do not short-circuit. The following contrived expression, for example, would print "hello, world!"
:
"yellow" should (equal ("blue") and equal { println("hello, world!"); "green" })In other words, the entire
and
or or
expression is always evaluated, so you'll see any side effects
of the right-hand side even if evaluating
only the left-hand side is enough to determine the ultimate result of the larger expression. Failure messages produced by these
expressions will "short-circuit," however,
mentioning only the left-hand side if that's enough to determine the result of the entire expression. This "short-circuiting" behavior
of failure messages is intended
to make it easier and quicker for you to ascertain which part of the expression caused the failure. The failure message for the previous
expression, for example, would be:
"yellow" did not equal "blue"Most likely this lack of short-circuiting would rarely be noticeable, because evaluating the right hand side will usually not involve a side effect. One situation where it might show up, however, is if you attempt to
and
a null
check on a variable with an expression
that uses the variable, like this:
map should (not be (null) and contain key ("ouch"))If
map
is null
, the test will indeed fail, but with a NullPointerException
, not a
TestFailedException
. Here, the NullPointerException
is the visible right-hand side effect. To get a
TestFailedException
, you would need to check each assertion separately:
map should not be (null) map should contain key ("ouch")If
map
is null
in this case, the null
check in the first expression will fail with
a TestFailedException
, and the second expression will never be executed.
The other difference with Boolean
operators is that although &&
has a higher precedence than ||
,
and
and or
have the same precedence. Thus although the Boolean
expression (a || b && c)
will evaluate the &&
expression
before the ||
expression, like (a || (b && c))
, the following expression:
traversable should (contain (7) or contain (8) and have size (9))Will evaluate left to right, as:
traversable should ((contain (7) or contain (8)) and have size (9))If you really want the
and
part to be evaluated first, you'll need to put in parentheses, like this:
traversable should (contain (7) or (contain (8) and have size (9)))== Working with
Option
s ==
ScalaTest matchers has no special support for Option
s, but you can
work with them quite easily using syntax shown previously. For example, if you wish to check
whether an option is None
, you can write any of:
option shouldEqual None option shouldBe None option should not be defined option shouldBe emptyIf you wish to check an option is defined, and holds a specific value, you can write either of:
option shouldEqual Some("hi") option shouldBe Some("hi")If you only wish to check that an option is defined, but don't care what it's value is, you can write:
option shouldBe definedIf you mix in (or import the members of)
OptionValues
,
you can write one statement that indicates you believe an option should be defined and then say something else about its value. Here's an example:
import org.scalatest.OptionValues._ option.value should be < 7== Checking arbitrary properties with
have
==
Using have
, you can check properties of any type, where a property is an attribute of any
object that can be retrieved either by a public field, method, or JavaBean-style get
or is
method, like this:
book should have ( 'title ("Programming in Scala"), 'author (List("Odersky", "Spoon", "Venners")), 'pubYear (2008) )This expression will use reflection to ensure the
title
, author
, and pubYear
properties of object book
are equal to the specified values. For example, it will ensure that book
has either a public Java field or method
named title
, or a public method named getTitle
, that when invoked (or accessed in the field case) results
in a the string "Programming in Scala"
. If all specified properties exist and have their expected values, respectively,
execution will continue. If one or more of the properties either does not exist, or exists but results in an unexpected value,
a TestFailedException
will be thrown that explains the problem. (For the details on how a field or method is selected during this
process, see the documentation for HavePropertyMatcherGenerator
.)
When you use this syntax, you must place one or more property values in parentheses after have
, seperated by commas, where a property
value is a symbol indicating the name of the property followed by the expected value in parentheses. The only exceptions to this rule is the syntax
for checking size and length shown previously, which does not require parentheses. If you forget and put parentheses in, however, everything will
still work as you'd expect. Thus instead of writing:
array should have length (3) set should have size (90)You can alternatively, write:
array should have (length (3)) set should have (size (90))If a property has a value different from the specified expected value, a
TestFailedError
will be thrown
with a detailed message that explains the problem. For example, if you assert the following on
a book
whose title is Moby Dick
:
book should have ('title ("A Tale of Two Cities"))You'll get a
TestFailedException
with this detail message:
The title property had value "Moby Dick", instead of its expected value "A Tale of Two Cities", on object Book("Moby Dick", "Melville", 1851)If you prefer to check properties in a type-safe manner, you can use a
HavePropertyMatcher
.
This would allow you to write expressions such as:
book should have ( title ("Programming in Scala"), author (List("Odersky", "Spoon", "Venners")), pubYear (2008) )These expressions would fail to compile if
should
is used on an inappropriate type, as determined
by the type parameter of the HavePropertyMatcher
being used. (For example, title
in this example
might be of type HavePropertyMatcher[org.publiclibrary.Book]
. If used with an appropriate type, such an expression will compile
and at run time the property method or field will be accessed directly; i.e., no reflection will be used.
See the documentation for HavePropertyMatcher
for more information.
== Using length
and size
with HavePropertyMatcher
s ==
If you want to use length
or size
syntax with your own custom HavePropertyMatcher
s, you
can do so, but you must write (of [“the type”])
afterwords. For example, you could write:
book should have ( title ("A Tale of Two Cities"), length (220) (of [Book]), author ("Dickens") )Prior to ScalaTest 2.0, “
length
(22)
” yielded a HavePropertyMatcher[Any, Int]
that used reflection to dynamically look
for a length
field or getLength
method. In ScalaTest 2.0, “length
(22)
” yields a
MatcherFactory1[Any, Length]
, so it is no longer a HavePropertyMatcher
. The (of [<type>])
syntax converts the
the MatcherFactory1[Any, Length]
to a HavePropertyMatcher[<type>, Int]
.
== Checking that an expression matches a pattern ==
ScalaTest's Inside
trait allows you to make assertions after a pattern match.
Here's an example:
case class Name(first: String, middle: String, last: String)You can use
val name = Name("Jane", "Q", "Programmer")
inside(name) { case Name(first, _, _) => first should startWith ("S") }
inside
to just ensure a pattern is matched, without making any further assertions, but a better
alternative for that kind of assertion is matchPattern
. The matchPattern
syntax allows you
to express that you expect a value to match a particular pattern, no more and no less:
name should matchPattern { case Name("Sarah", _, _) => }== Using custom matchers == If none of the built-in matcher syntax (or options shown so far for extending the syntax) satisfy a particular need you have, you can create custom
Matcher
s that allow
you to place your own syntax directly after should
. For example, class java.io.File
has a method isHidden
, which
indicates whether a file of a certain path and name is hidden. Because the isHidden
method takes no parameters and returns Boolean
,
you can call it using be
with a symbol or BePropertyMatcher
, yielding assertions like:
file should be ('hidden) // using a symbol file should be (hidden) // using a BePropertyMatcherIf it doesn't make sense to have your custom syntax follow
be
, you might want to create a custom Matcher
instead, so your syntax can follow should
directly. For example, you might want to be able to check whether
a java.io.File
's name ends with a particular extension, like this:
// using a plain-old Matcher file should endWithExtension ("txt")ScalaTest provides several mechanism to make it easy to create custom matchers, including ways to compose new matchers out of existing ones complete with new error messages. For more information about how to create custom
Matcher
s, please see the documentation for the Matcher
trait.
== Checking for expected exceptions ==
Sometimes you need to test whether a method throws an expected exception under certain circumstances, such
as when invalid arguments are passed to the method. With Matchers
mixed in, you can
check for an expected exception like this:
an [IndexOutOfBoundsException] should be thrownBy s.charAt(-1)If
charAt
throws an instance of StringIndexOutOfBoundsException
,
this expression will result in that exception. But if charAt
completes normally, or throws a different
exception, this expression will complete abruptly with a TestFailedException
.
If you need to further isnpect an expected exception, you can capture it using this syntax:
val thrown = the [IndexOutOfBoundsException] thrownBy s.charAt(-1)This expression returns the caught exception so that you can inspect it further if you wish, for example, to ensure that data contained inside the exception has the expected values. Here's an example:
thrown.getMessage should equal ("String index out of range: -1")
If you prefer you can also capture and inspect an expected exception in one statement, like this:
the [ArithmeticException] thrownBy 1 / 0 should have message "/ by zero" the [IndexOutOfBoundsException] thrownBy { s.charAt(-1) } should have message "String index out of range: -1"You can also state that no exception should be thrown by some code, like this:
noException should be thrownBy 0 / 1Note: the following syntax from ScalaTest 1.x has been deprecated:
evaluating { s.charAt(-1) } should produce [IndexOutOfBoundsException]Such uses will continue to work during the deprecation cycle, but support for this syntax will eventually be removed in a future version of ScalaTest. Please change all uses to a corresponding use of the syntax described previously in this section. == Those pesky parens == Perhaps the most tricky part of writing assertions using ScalaTest matchers is remembering when you need or don't need parentheses, but bearing in mind a few simple rules should help. It is also reassuring to know that if you ever leave off a set of parentheses when they are required, your code will not compile. Thus the compiler will help you remember when you need the parens. That said, the rules are: 1. Although you don't always need them, you may choose to always put parentheses around right-hand values, such as the
7
in num should equal (7)
:
result should equal (4) array should have length (3) book should have ( 'title ("Programming in Scala"), 'author (List("Odersky", "Spoon", "Venners")), 'pubYear (2008) ) option should be ('defined) catMap should (contain key (9) and contain value ("lives")) keyEvent should be an ('actionKey) javaSet should have size (90)2. Except for
length
, size
and message
, you must always put parentheses around
the list of one or more property values following a have
:
file should (exist and have ('name ("temp.txt"))) book should have ( title ("Programming in Scala"), author (List("Odersky", "Spoon", "Venners")), pubYear (2008) ) javaList should have length (9) // parens optional for length and size3. You must always put parentheses around
and
and or
expressions, as in:
catMap should (contain key (9) and contain value ("lives")) number should (equal (2) or equal (4) or equal (8))4. Although you don't always need them, you may choose to always put parentheses around custom
Matcher
s when they appear directly after not
:
file should exist file should not (exist) file should (exist and have ('name ("temp.txt"))) file should (not (exist) and have ('name ("temp.txt")) file should (have ('name ("temp.txt") or exist) file should (have ('name ("temp.txt") or not (exist))That's it. With a bit of practice it should become natural to you, and the compiler will always be there to tell you if you forget a set of needed parentheses. Note: ScalaTest's matchers are in part inspired by the matchers of RSpec, Hamcrest, and specs2, and its “
shouldNot compile
” syntax
by the illTyped
macro of shapeless.
Trait that provides a domain specific language (DSL) for expressing assertions in tests
using the word must
.
Trait that provides a domain specific language (DSL) for expressing assertions in tests
using the word must
.
For example, if you mix Matchers
into
a suite class, you can write an equality assertion in that suite like this:
result must equal (3)
Here result
is a variable, and can be of any type. If the object is an
Int
with the value 3, execution will continue (i.e., the expression will result
in the unit value, ()
). Otherwise, a TestFailedException
will be thrown with a detail message that explains the problem, such as "7 did not equal 3"
.
This TestFailedException
will cause the test to fail.
Here is a table of contents for this documentation:
Boolean
properties with be
BeMatchers
String
s and Array
s as collectionsand
and or
Option
shave
length
and size
with HavePropertyMatcher
sTrait MustMatchers
is an alternative to Matchers
that provides the exact same
meaning, syntax, and behavior as Matchers
, but uses the verb must
instead of should
.
The two traits differ only in the English semantics of the verb: should
is informal, making the code feel like conversation between the writer and the reader; must
is more formal, making the code feel more like
a written specification.
Prior to 2.0, ScalaTest's matchers DSL was provided by traits
org.scalatest.matchers.ShouldMatchers
and
org.scalatest.matchers.MustMatchers
. These are now deprecated in favor of
traits in package org.scalatest
. The fully qualified name of the original
ShouldMatchers
is now org.scalatest.Matchers
, and the fully qualified
name of the original MustMatchers
is now org.scalatest.MustMatchers
.
The old fully qualified names will continue to work during a lengthy deprecation cycle, but
will generate a deprecation warning and eventually be removed in a future version
of ScalaTest. You can migrate existing uses of ShouldMatchers
by simply importing
or mixing in org.scalatest.Matchers
instead of
org.scalatest.matchers.ShouldMatchers
, and can migrate existing
uses of org.scalatest.matchers.MustMatchers
by importing or
mixing in org.scalatest.MustMatchers
instead of org.scalatest.matchers.MustMatchers
.
Two other deprecations in ScalaTest 2.0 matchers are be
===
<value>
and evaluating
...
must
produce
syntax. This will both continue to work as before, but will generate a deprecation
warning and eventually be removed in a future version of ScalaTest. the be
===
syntax is being deprecated so that all uses
of ===
in ScalaTest consistently provide the new
features of tunable type checking, tolerance support, and customized equality. Please replace uses of this syntax with one of the other
ways to check equality described in the next section. The eventually
syntax is being deprecated because it is replaced by thrownBy
clauses, as described below.
Although ScalaTest's matchers have undergone a major refactor in 2.0, all previously documented syntax for matchers must continue to work exactly
the same with one potential exception, which must in practice be extremely rare. The potential breakage is that if you included length
or size
along with custom have-property matchers that you wrote, you'll get a compiler error. To fix such an error, add after
your length
or size
invocation an (of [<type>])
clause, as
described below.
The only other source of potential breakage is the fragile base class problem. We have added fields and methods to Matchers
in 2.0 that may
conflict with fields and methods in your existing classes and cause a compiler error. Such issues can usually be easily fixed locally with simple renames or refactors,
but if you prefer to subtract a token from Matchers
, you can do so by mixing together your own Matchers
trait
from component traits, as described below. Note that you must not see any new implicit conflicts, because we managed to reduce the number
of implicits brought into scope by 2.0 matchers compared to 1.x by about 75%.
ScalaTest matchers provides five different ways to check equality, each designed to address a different need. They are:
result must equal (3) // can customize equality result must === (3) // can customize equality and enforce type constraints result must be (3) // cannot customize equality, so fastest to compile result mustEqual 3 // can customize equality, no parentheses required result mustBe 3 // cannot customize equality, so fastest to compile, no parentheses required
The “left
must
equal
(right)
” syntax requires an
org.scalactic.Equality[L]
to be provided (either implicitly or explicitly), where
L
is the left-hand type on which must
is invoked. In the "left
must
equal
(right)
" case,
for example, L
is the type of left
. Thus if left
is type Int
, the "left
must
equal
(right)
"
statement would require an Equality[Int]
.
By default, an implicit Equality[T]
instance is available for any type T
, in which equality is implemented
by simply invoking ==
on the left
value, passing in the right
value, with special treatment for arrays. If either left
or right
is an array, deep
will be invoked on it before comparing with ==. Thus, the following expression
will yield false, because Array
's equals
method compares object identity:
Array(1, 2) == Array(1, 2) // yields false
The next expression will by default not result in a TestFailedException
, because default Equality[Array[Int]]
compares
the two arrays structurally, taking into consideration the equality of the array's contents:
Array(1, 2) must equal (Array(1, 2)) // succeeds (i.e., does not throw TestFailedException)
If you ever do want to verify that two arrays are actually the same object (have the same identity), you can use the
be theSameInstanceAs
syntax, described below.
You can customize the meaning of equality for a type when using "must
equal
," "must
===
,"
or mustEqual
syntax by defining implicit Equality
instances that will be used instead of default Equality
.
You might do this to normalize types before comparing them with ==
, for instance, or to avoid calling the ==
method entirely,
such as if you want to compare Double
s with a tolerance.
For an example, see the main documentation of trait Equality
.
You can always supply implicit parameters explicitly, but in the case of implicit parameters of type Equality[T]
, Scalactic provides a
simple "explictly" DSL. For example, here's how you could explicitly supply an Equality[String]
instance that normalizes both left and right
sides (which must be strings), by transforming them to lowercase:
scala> import org.scalatest.MustMatchers._ import org.scalatest.MustMatchers._ scala> import org.scalactic.Explicitly._ import org.scalactic.Explicitly._ scala> import org.scalactic.StringNormalizations._ import org.scalactic.StringNormalizations._ scala> "Hi" must equal ("hi") (after being lowerCased)
The after
being
lowerCased
expression results in an Equality[String]
, which is then passed
explicitly as the second curried parameter to equal
. For more information on the explictly DSL, see the main documentation
for trait Explicitly
.
The "must
be
" and mustBe
syntax do not take an Equality[T]
and can therefore not be customized.
They always use the default approach to equality described above. As a result, "must
be
" and mustBe
will
likely be the fastest-compiling matcher syntax for equality comparisons, since the compiler need not search for
an implicit Equality[T]
each time.
The must
===
syntax (and its complement, must
!==
) can be used to enforce type
constraints at compile-time between the left and right sides of the equality comparison. Here's an example:
scala> import org.scalatest.MustMatchers._ import org.scalatest.MustMatchers._ scala> import org.scalactic.TypeCheckedTripleEquals._ import org.scalactic.TypeCheckedTripleEquals._ scala> Some(2) must === (2) <console>:17: error: types Some[Int] and Int do not adhere to the equality constraint selected for the === and !== operators; the missing implicit parameter is of type org.scalactic.Constraint[Some[Int],Int] Some(2) must === (2) ^
By default, the "Some(2)
must
===
(2)
" statement would fail at runtime. By mixing in
the equality constraints provided by TypeCheckedTripleEquals
, however, the statement fails to compile. For more information
and examples, see the main documentation for trait TypeCheckedTripleEquals
.
You can check the size or length of any type of object for which it makes sense. Here's how checking for length looks:
result must have length 3
Size is similar:
result must have size 10
The length
syntax can be used with String
, Array
, any scala.collection.GenSeq
,
any java.util.List
, and any type T
for which an implicit Length[T]
type class is
available in scope.
Similarly, the size
syntax can be used with Array
, any scala.collection.GenTraversable
,
any java.util.Collection
, any java.util.Map
, and any type T
for which an implicit Size[T]
type class is
available in scope. You can enable the length
or size
syntax for your own arbitrary types, therefore,
by defining Length
or Size
type
classes for those types.
In addition, the length
syntax can be used with any object that has a field or method named length
or a method named getLength
. Similarly, the size
syntax can be used with any
object that has a field or method named size
or a method named getSize
.
The type of a length
or size
field, or return type of a method, must be either Int
or Long
. Any such method must take no parameters. (The Scala compiler will ensure at compile time that
the object on which must
is being invoked has the appropriate structure.)
You can check for whether a string starts with, ends with, or includes a substring like this:
string must startWith ("Hello") string must endWith ("world") string must include ("seven")
You can check for whether a string starts with, ends with, or includes a regular expression, like this:
string must startWith regex "Hel*o" string must endWith regex "wo.ld" string must include regex "wo.ld"
And you can check whether a string fully matches a regular expression, like this:
string must fullyMatch regex """(-)?(\d+)(\.\d*)?"""
The regular expression passed following the regex
token can be either a String
or a scala.util.matching.Regex
.
With the startWith
, endWith
, include
, and fullyMatch
tokens can also be used with an optional specification of required groups, like this:
"abbccxxx" must startWith regex ("a(b*)(c*)" withGroups ("bb", "cc")) "xxxabbcc" must endWith regex ("a(b*)(c*)" withGroups ("bb", "cc")) "xxxabbccxxx" must include regex ("a(b*)(c*)" withGroups ("bb", "cc")) "abbcc" must fullyMatch regex ("a(b*)(c*)" withGroups ("bb", "cc"))
You can check whether a string is empty with empty
:
s mustBe empty
You can also use most of ScalaTest's matcher syntax for collections on String
by
treating the String
s as collections of characters. For examples, see the
String
s and Array
s as collections section below.
You can check whether any type for which an implicit Ordering[T]
is available
is greater than, less than, greater than or equal, or less
than or equal to a value of type T
. The syntax is:
one must be < 7 one must be > 0 one must be <= 7 one must be >= 0
Boolean
properties with be
If an object has a method that takes no parameters and returns boolean, you can check
it by placing a Symbol
(after be
) that specifies the name
of the method (excluding an optional prefix of "is
"). A symbol literal
in Scala begins with a tick mark and ends at the first non-identifier character. Thus,
'traversableAgain
results in a Symbol
object at runtime, as does
'completed
and 'file
. Here's an example:
iter mustBe 'traversableAgain
Given this code, ScalaTest will use reflection to look on the object referenced from
emptySet
for a method that takes no parameters and results in Boolean
,
with either the name empty
or isEmpty
. If found, it will invoke
that method. If the method returns true
, execution will continue. But if it returns
false
, a TestFailedException
will be thrown that will contain a detail message, such as:
non-empty iterator was not traversableAgain
This be
syntax can be used with any reference (AnyRef
) type. If the object does
not have an appropriately named predicate method, you'll get a TestFailedException
at runtime with a detailed message that explains the problem.
(For the details on how a field or method is selected during this
process, see the documentation for BeWord
.)
If you think it reads better, you can optionally put a
or an
after
be
. For example, java.io.File
has two predicate methods,
isFile
and isDirectory
. Thus with a File
object
named temp
, you could write:
temp must be a 'file
Or, given java.awt.event.KeyEvent
has a method isActionKey
that takes
no arguments and returns Boolean
, you could assert that a KeyEvent
is
an action key with:
keyEvent must be an 'actionKey
If you prefer to check Boolean
properties in a type-safe manner, you can use a BePropertyMatcher
.
This would allow you to write expressions such as:
xs mustBe traversableAgain temp must be a file keyEvent must be an actionKey
These expressions would fail to compile if must
is used on an inappropriate type, as determined
by the type parameter of the BePropertyMatcher
being used. (For example, file
in this example
would likely be of type BePropertyMatcher[java.io.File]
. If used with an appropriate type, such an expression will compile
and at run time the Boolean
property method or field will be accessed directly; i.e., no reflection will be used.
See the documentation for BePropertyMatcher
for more information.
BeMatchers
If you want to create a new way of using be
, which doesn't map to an actual property on the
type you care about, you can create a BeMatcher
. You could use this, for example, to create BeMatcher[Int]
called odd
, which would match any odd Int
, and even
, which would match
any even Int
.
Given this pair of BeMatcher
s, you could check whether an Int
was odd or even with expressions like:
num mustBe odd num must not be even
For more information, see the documentation for BeMatcher
.
If you need to check that two references refer to the exact same object, you can write:
ref1 must be theSameInstanceAs ref2
If you need to check that an object is an instance of a particular class or trait, you can supply the type to
“be
a
” or “be
an
”:
result1 mustBe a [Tiger] result1 must not be an [Orangutan]
Because type parameters are erased on the JVM, we recommend you insert an underscore for any type parameters
when using this syntax. Both of the following test only that the result is an instance of List[_]
, because at
runtime the type parameter has been erased:
result mustBe a [List[_]] // recommended result mustBe a [List[Fruit]] // discouraged
Often you may want to check whether a number is within a
range. You can do that using the +-
operator, like this:
sevenDotOh must equal (6.9 +- 0.2) sevenDotOh must === (6.9 +- 0.2) sevenDotOh must be (6.9 +- 0.2) sevenDotOh mustEqual 6.9 +- 0.2 sevenDotOh mustBe 6.9 +- 0.2
Any of these expressions will cause a TestFailedException
to be thrown if the floating point
value, sevenDotOh
is outside the range 6.7
to 7.1
.
You can use +-
with any type T
for which an implicit Numeric[T]
exists, such as integral types:
seven must equal (6 +- 2) seven must === (6 +- 2) seven must be (6 +- 2) seven mustEqual 6 +- 2 seven mustBe 6 +- 2
You can check whether an object is "empty", like this:
traversable mustBe empty javaMap must not be empty
The empty
token can be used with any type L
for which an implicit Emptiness[L]
exists.
The Emptiness
companion object provides implicits for GenTraversable[E]
, java.util.Collection[E]
,
java.util.Map[K, V]
, String
, Array[E]
, and Option[E]
. In addition, the
Emptiness
companion object provides structural implicits for types that declare an isEmpty
method that
returns a Boolean
. Here are some examples:
scala> import org.scalatest.MustMatchers._ import org.scalatest.MustMatchers._ scala> List.empty mustBe empty scala> None mustBe empty scala> Some(1) must not be empty scala> "" mustBe empty scala> new java.util.HashMap[Int, Int] mustBe empty scala> new { def isEmpty = true} mustBe empty scala> Array(1, 2, 3) must not be empty
You can check whether a collection contains a particular element like this:
traversable must contain ("five")
The contain
syntax shown above can be used with any type C
that has a "containing" nature, evidenced by
an implicit org.scalatest.enablers.Containing[L]
, where L
is left-hand type on
which must
is invoked. In the Containing
companion object, implicits are provided for types GenTraversable[E]
, java.util.Collection[E]
,
java.util.Map[K, V]
, String
, Array[E]
, and Option[E]
.
Here are some examples:
scala> import org.scalatest.MustMatchers._ import org.scalatest.MustMatchers._ scala> List(1, 2, 3) must contain (2) scala> Map('a' -> 1, 'b' -> 2, 'c' -> 3) must contain ('b' -> 2) scala> Set(1, 2, 3) must contain (2) scala> Array(1, 2, 3) must contain (2) scala> "123" must contain ('2') scala> Some(2) must contain (2)
ScalaTest's implicit methods that provide the Containing[L]
type classes require an Equality[E]
, where
E
is an element type. For example, to obtain a Containing[Array[Int]]
you must supply an Equality[Int]
,
either implicitly or explicitly. The contain
syntax uses this Equality[E]
to determine containership.
Thus if you want to change how containership is determined for an element type E
, place an implicit Equality[E]
in scope or use the explicitly DSL. Although the implicit parameter required for the contain
syntax is of type Containing[L]
,
implicit conversions are provided in the Containing
companion object from Equality[E]
to the various
types of containers of E
. Here's an example:
scala> import org.scalatest.MustMatchers._ import org.scalatest.MustMatchers._ scala> List("Hi", "Di", "Ho") must contain ("ho") org.scalatest.exceptions.TestFailedException: List(Hi, Di, Ho) did not contain element "ho" at ... scala> import org.scalactic.Explicitly._ import org.scalactic.Explicitly._ scala> import org.scalactic.StringNormalizations._ import org.scalactic.StringNormalizations._ scala> (List("Hi", "Di", "Ho") must contain ("ho")) (after being lowerCased)
Note that when you use the explicitly DSL with contain
you need to wrap the entire
contain
expression in parentheses, as shown here.
(List("Hi", "Di", "Ho") must contain ("ho")) (after being lowerCased) ^ ^
In addition to determining whether an object contains another object, you can use contain
to
make other determinations.
For example, the contain
oneOf
syntax ensures that one and only one of the specified elements are
contained in the containing object:
List(1, 2, 3, 4, 5) must contain oneOf (5, 7, 9) Some(7) must contain oneOf (5, 7, 9) "howdy" must contain oneOf ('a', 'b', 'c', 'd')
Note that if multiple specified elements appear in the containing object, oneOf
will fail:
scala> List(1, 2, 3) must contain oneOf (2, 3, 4) org.scalatest.exceptions.TestFailedException: List(1, 2, 3) did not contain one of (2, 3, 4) at ...
If you really want to ensure one or more of the specified elements are contained in the containing object,
use atLeastOneOf
, described below, instead of oneOf
. Keep in mind, oneOf
means "exactly one of."
Note also that with any contain
syntax, you can place custom implicit Equality[E]
instances in scope
to customize how containership is determined, or use the explicitly DSL. Here's an example:
(Array("Doe", "Ray", "Me") must contain oneOf ("X", "RAY", "BEAM")) (after being lowerCased)
The contain
noneOf
syntax does the opposite of oneOf
: it ensures none of the specified elements
are contained in the containing object:
List(1, 2, 3, 4, 5) must contain noneOf (7, 8, 9) Some(0) must contain noneOf (7, 8, 9) "12345" must contain noneOf ('7', '8', '9')
As mentioned, the "contain
," "contain
oneOf
," and "contain
noneOf
" syntax requires a
Containing[L]
be provided, where L
is the left-hand type. Other contain
syntax, which
will be described in this section, requires an Aggregating[L]
be provided, where again L
is the left-hand type.
(An Aggregating[L]
instance defines the "aggregating nature" of a type L
.)
The reason, essentially, is that contain
syntax that makes sense for Option
is enabled by
Containing[L]
, whereas syntax that does not make sense for Option
is enabled
by Aggregating[L]
. For example, it doesn't make sense to assert that an Option[Int]
contains all of a set of integers, as it
could only ever contain one of them. But this does make sense for a type such as List[Int]
that can aggregate zero to many integers.
The Aggregating
companion object provides implicit instances of Aggregating[L]
for types GenTraversable[E]
, java.util.Collection[E]
,
java.util.Map[K, V]
, String
, Array[E]
. Note that these are the same types as are supported with
Containing
, but with Option[E]
missing.
Here are some examples:
The contain
atLeastOneOf
syntax, for example, works for any type L
for which an Aggregating[L]
exists. It ensures
that at least one of (i.e., one or more of) the specified objects are contained in the containing object:
List(1, 2, 3) must contain atLeastOneOf (2, 3, 4) Array(1, 2, 3) must contain atLeastOneOf (3, 4, 5) "abc" must contain atLeastOneOf ('c', 'a', 't')
Similar to Containing[L]
, the implicit methods that provide the Aggregating[L]
instances require an Equality[E]
, where
E
is an element type. For example, to obtain a Aggregating[Vector[String]]
you must supply an Equality[String]
,
either implicitly or explicitly. The contain
syntax uses this Equality[E]
to determine containership.
Thus if you want to change how containership is determined for an element type E
, place an implicit Equality[E]
in scope or use the explicitly DSL. Although the implicit parameter required for the contain
syntax is of type Aggregating[L]
,
implicit conversions are provided in the Aggregating
companion object from Equality[E]
to the various
types of aggregations of E
. Here's an example:
(Vector(" A", "B ") must contain atLeastOneOf ("a ", "b", "c")) (after being lowerCased and trimmed)
The "contain
atMostOneOf
" syntax lets you specify a set of objects at most one of which must be contained in the containing object:
List(1, 2, 3, 4, 5) must contain atMostOneOf (5, 6, 7)
The "contain
allOf
" syntax lets you specify a set of objects that must all be contained in the containing object:
List(1, 2, 3, 4, 5) must contain allOf (2, 3, 5)
The "contain
only
" syntax lets you assert that the containing object contains only the specified objects, though it may
contain more than one of each:
List(1, 2, 3, 2, 1) must contain only (1, 2, 3)
The "contain
theSameElementsAs
" and "contain
theSameElementsInOrderAs
syntax differ from the others
in that the right hand side is a GenTraversable[_]
rather than a varargs of Any
. (Note: in a future 2.0 milestone release, possibly
2.0.M6, these will likely be widened to accept any type R
for which an Aggregating[R]
exists.)
The "contain
theSameElementsAs
" syntax lets you assert that two aggregations contain the same objects:
List(1, 2, 2, 3, 3, 3) must contain theSameElementsAs Vector(3, 2, 3, 1, 2, 3)
The number of times any family of equal objects appears must also be the same in both the left and right aggregations. The specified objects may appear multiple times, but must appear in the order they appear in the right-hand list. For example, if the last 3 element is left out of the right-hand list in the previous example, the expression would fail because the left side has three 3's and the right hand side has only two:
List(1, 2, 2, 3, 3, 3) must contain theSameElementsAs Vector(3, 2, 3, 1, 2) org.scalatest.exceptions.TestFailedException: List(1, 2, 2, 3, 3, 3) did not contain the same elements as Vector(3, 2, 3, 1, 2) at ...
The rest of the contain
syntax, which
will be described in this section, requires a Sequencing[L]
be provided, where again L
is the left-hand type.
(A Sequencing[L]
instance defines the "sequencing nature" of a type L
.)
The reason, essentially, is that contain
syntax that implies an "order" of elements makes sense only for types that place elements in a sequence.
For example, it doesn't make sense to assert that a Map[String, Int]
or Set[Int]
contains all of a set of integers in a particular
order, as these types don't necessarily define an order for their elements. But this does make sense for a type such as Seq[Int]
that does define
an order for its elements.
The Sequencing
companion object provides implicit instances of Sequencing[L]
for types GenSeq[E]
, java.util.List[E]
,
String
, and Array[E]
.
Here are some examples:
Similar to Containing[L]
, the implicit methods that provide the Aggregating[L]
instances require an Equality[E]
, where
E
is an element type. For example, to obtain a Aggregating[Vector[String]]
you must supply an Equality[String]
,
either implicitly or explicitly. The contain
syntax uses this Equality[E]
to determine containership.
Thus if you want to change how containership is determined for an element type E
, place an implicit Equality[E]
in scope or use the explicitly DSL. Although the implicit parameter required for the contain
syntax is of type Aggregating[L]
,
implicit conversions are provided in the Aggregating
companion object from Equality[E]
to the various
types of aggregations of E
. Here's an example:
The "contain
inOrderOnly
" syntax lets you assert that the containing object contains only the specified objects, in order.
The specified objects may appear multiple times, but must appear in the order they appear in the right-hand list. Here's an example:
List(1, 2, 2, 3, 3, 3) must contain inOrderOnly (1, 2, 3)
The "contain
inOrder
" syntax lets you assert that the containing object contains only the specified objects in order, like
inOrderOnly
, but allows other objects to appear in the left-hand aggregation as well:
contain more than one of each:
List(0, 1, 2, 2, 99, 3, 3, 3, 5) must contain inOrder (1, 2, 3)
Note that "order" in inOrder
, inOrderOnly
, and theSameElementsInOrderAs
(described below)
in the Aggregation[L]
instances built-in to ScalaTest is defined as "iteration order".
Lastly, the "contain
theSameElementsInOrderAs
" syntax lets you assert that two aggregations contain
the same exact elements in the same (iteration) order:
List(1, 2, 3) must contain theSameElementsInOrderAs collection.mutable.TreeSet(3, 2, 1)
The previous assertion succeeds because the iteration order of aTreeSet
is the natural
ordering of its elements, which in this case is 1, 2, 3. An iterator obtained from the left-hand List
will produce the same elements
in the same order.
You can also ask whether the elements of "sortable" objects (such as Array
s, Java List
s, and GenSeq
s)
are in sorted order, like this:
List(1, 2, 3) mustBe sorted
Althought it seems desireable to provide similar matcher syntax for Scala and Java iterators to that provided for sequences like
Seq
s, Array
, and java.util.List
, the
ephemeral nature of iterators makes this problematic. Some syntax (such as must
contain
) is relatively straightforward to
support on iterators, but other syntax (such
as, for example, Inspector
expressions on nested iterators) is not. Rather
than allowing inconsistencies between sequences and iterators in the API, we chose to not support any such syntax directly on iterators:
scala> val it = List(1, 2, 3).iterator it: Iterator[Int] = non-empty iteratorInstead, you will need to convert your iterators to a sequence explicitly before using them in matcher expressions:
scala> it must contain (2) <console>:15: error: could not find implicit value for parameter typeClass1: org.scalatest.enablers.Containing[Iterator[Int]] it must contain (2) ^
scala> it.toStream must contain (2)
We recommend you convert (Scala or Java) iterators to Stream
s, as shown in the previous example, so that you can
continue to reap any potential benefits provided by the laziness of the underlying iterator.
== Inspector shorthands ==
You can use the Inspectors
syntax with matchers as well as assertions. If you have a multi-dimensional collection, such as a
list of lists, using Inspectors
is your best option:
val yss = List( List(1, 2, 3), List(1, 2, 3), List(1, 2, 3) )For assertions on one-dimensional collections, however, matchers provides "inspector shorthands." Instead of writing:
forAll (yss) { ys => forAll (ys) { y => y must be > 0 } }
val xs = List(1, 2, 3) forAll (xs) { x => x must be < 10 }You can write:
all (xs) must be < 10
The previous statement asserts that all elements of the xs
list must be less than 10.
All of the inspectors have shorthands in matchers. Here is the full list:
- all
- succeeds if the assertion holds true for every element
- atLeast
- succeeds if the assertion holds true for at least the specified number of elements
- atMost
- succeeds if the assertion holds true for at most the specified number of elements
- between
- succeeds if the assertion holds true for between the specified minimum and maximum number of elements, inclusive
- every
- same as all
, but lists all failing elements if it fails (whereas all
just reports the first failing element)
- exactly
- succeeds if the assertion holds true for exactly the specified number of elements
Here are some examples:
scala> import org.scalatest.MustMatchers._ import org.scalatest.MustMatchers._ scala> val xs = List(1, 2, 3, 4, 5) xs: List[Int] = List(1, 2, 3, 4, 5) scala> all (xs) must be > 0 scala> atMost (2, xs) must be >= 4 scala> atLeast (3, xs) must be < 5 scala> between (2, 3, xs) must (be > 1 and be < 5) scala> exactly (2, xs) must be <= 2 scala> every (xs) must be < 10 scala> // And one that fails... scala> exactly (2, xs) mustEqual 2 org.scalatest.exceptions.TestFailedException: 'exactly(2)' inspection failed, because only 1 element satisfied the assertion block at index 1: at index 0, 1 did not equal 2, at index 2, 3 did not equal 2, at index 3, 4 did not equal 2, at index 4, 5 did not equal 2 in List(1, 2, 3, 4, 5) at ...Like
Inspectors
, objects used with inspector shorthands can be any type T
for which a Collecting[T, E]
is availabe, which by default includes GenTraversable
,
Java Collection
, Java Map
, Array
s, and String
s.
Here are some examples:
scala> import org.scalatest._ import org.scalatest._ scala> import MustMatchers._ import MustMatchers._ scala> all (Array(1, 2, 3)) must be < 5 scala> import collection.JavaConverters._ import collection.JavaConverters._ scala> val js = List(1, 2, 3).asJava js: java.util.List[Int] = [1, 2, 3] scala> all (js) must be < 5 scala> val jmap = Map("a" -> 1, "b" -> 2).asJava jmap: java.util.Map[String,Int] = {a=1, b=2} scala> atLeast(1, jmap) mustBe Entry("b", 2) scala> atLeast(2, "hello, world!") mustBe 'o'== Single-element collections == To assert both that a collection contains just one "lone" element as well as something else about that element, you can use the
loneElement
syntax provided by trait LoneElement
. For example, if a
Set[Int]
must contain just one element, an Int
less than or equal to 10, you could write:
import LoneElement._ set.loneElement must be <= 10You can invoke
loneElement
on any type T
for which an implicit Collecting[E, T]
is available, where E
is the element type returned by the loneElement
invocation. By default, you can use loneElement
on GenTraversable
, Java Collection
, Java Map
, Array
, and String
.
== Java collections and maps ==
You can use similar syntax on Java collections (java.util.Collection
) and maps (java.util.Map
).
For example, you can check whether a Java Collection
or Map
is empty
,
like this:
javaCollection must be ('empty) javaMap must be ('empty)Even though Java's
List
type doesn't actually have a length
or getLength
method,
you can nevertheless check the length of a Java List
(java.util.List
) like this:
javaList must have length 9
You can check the size of any Java Collection
or Map
, like this:
javaMap must have size 20 javaSet must have size 90In addition, you can check whether a Java
Collection
contains a particular
element, like this:
javaCollection must contain ("five")
One difference to note between the syntax supported on Java and Scala collections is that
in Java, Map
is not a subtype of Collection
, and does not
actually define an element type. You can ask a Java Map
for an "entry set"
via the entrySet
method, which will return the Map
's key/value pairs
wrapped in a set of java.util.Map.Entry
, but a Map
is not actually
a collection of Entry
. To make Java Map
s easier to work with, however,
ScalaTest matchers allows you to treat a Java Map
as a collection of Entry
,
and defines a convenience implementation of java.util.Map.Entry
in
org.scalatest.Entry
. Here's how you use it:
javaMap must contain (Entry(2, 3)) javaMap must contain oneOf (Entry(2, 3), Entry(3, 4))You can you alse just check whether a Java
Map
contains a particular key, or value, like this:
javaMap must contain key 1 javaMap must contain value "Howdy"==
String
s and Array
s as collections ==
You can also use all the syntax described above for Scala and Java collections on Array
s and
String
s. Here are some examples:
scala> import org.scalatest._ import org.scalatest._ scala> import MustMatchers._ import MustMatchers._ scala> atLeast (2, Array(1, 2, 3)) must be > 1 scala> atMost (2, "halloo") mustBe 'o' scala> Array(1, 2, 3) mustBe sorted scala> "abcdefg" mustBe sorted scala> Array(1, 2, 3) must contain atMostOneOf (3, 4, 5) scala> "abc" must contain atMostOneOf ('c', 'd', 'e')==
be
as an equality comparison ==
All uses of be
other than those shown previously perform an equality comparison. They work
the same as equal
when it is used with default equality. This redundancy between be
and equals
exists in part
because it enables syntax that sometimes sounds more natural. For example, instead of writing:
result must equal (null)
You can write:
result must be (null)
(Hopefully you won't write that too much given null
is error prone, and Option
is usually a better, well, option.)
As mentioned previously, the other difference between equal
and be
is that equal
delegates the equality check to an Equality
typeclass, whereas
be
always uses default equality.
Here are some other examples of be
used for equality comparison:
sum must be (7.0) boring must be (false) fun must be (true) list must be (Nil) option must be (None) option must be (Some(1))As with
equal
used with default equality, using be
on arrays results in deep
being called on both arrays prior to
calling equal
. As a result,
the following expression would not throw a TestFailedException
:
Array(1, 2) must be (Array(1, 2)) // succeeds (i.e., does not throw TestFailedException)Because
be
is used in several ways in ScalaTest matcher syntax, just as it is used in many ways in English, one
potential point of confusion in the event of a failure is determining whether be
was being used as an equality comparison or
in some other way, such as a property assertion. To make it more obvious when be
is being used for equality, the failure
messages generated for those equality checks will include the word equal
in them. For example, if this expression fails with a
TestFailedException
:
option must be (Some(1))The detail message in that
TestFailedException
will include the words "equal to"
to signify be
was in this case being used for equality comparison:
Some(2) was not equal to Some(1)== Being negative == If you wish to check the opposite of some condition, you can simply insert
not
in the expression.
Here are a few examples:
result must not be (null) sum must not be <= (10) mylist must not equal (yourList) string must not startWith ("Hello")== Checking that a snippet of code does not compile == Often when creating libraries you may wish to ensure that certain arrangements of code that represent potential “user errors” do not compile, so that your library is more error resistant. ScalaTest
Matchers
trait includes the following syntax for that purpose:
"val a: String = 1" mustNot compile
If you want to ensure that a snippet of code does not compile because of a type error (as opposed
to a syntax error), use:
"val a: String = 1" mustNot typeCheck
Note that the mustNot
typeCheck
syntax will only succeed if the given snippet of code does not
compile because of a type error. A syntax error will still result on a thrown TestFailedException
.
If you want to state that a snippet of code does compile, you can make that
more obvious with:
"val a: Int = 1" must compile
Although the previous three constructs are implemented with macros that determine at compile time whether
the snippet of code represented by the string does or does not compile, errors
are reported as test failures at runtime.
== Logical expressions with and
and or
==
You can also combine matcher expressions with and
and/or or
, however,
you must place parentheses or curly braces around the and
or or
expression. For example,
this and
-expression would not compile, because the parentheses are missing:
map must contain key ("two") and not contain value (7) // ERROR, parentheses missing!Instead, you need to write:
map must (contain key ("two") and not contain value (7))Here are some more examples:
number must (be > (0) and be <= (10)) option must (equal (Some(List(1, 2, 3))) or be (None)) string must ( equal ("fee") or equal ("fie") or equal ("foe") or equal ("fum") )Two differences exist between expressions composed of these
and
and or
operators and the expressions you can write
on regular Boolean
s using its &&
and ||
operators. First, expressions with and
and or
do not short-circuit. The following contrived expression, for example, would print "hello, world!"
:
"yellow" must (equal ("blue") and equal { println("hello, world!"); "green" })In other words, the entire
and
or or
expression is always evaluated, so you'll see any side effects
of the right-hand side even if evaluating
only the left-hand side is enough to determine the ultimate result of the larger expression. Failure messages produced by these
expressions will "short-circuit," however,
mentioning only the left-hand side if that's enough to determine the result of the entire expression. This "short-circuiting" behavior
of failure messages is intended
to make it easier and quicker for you to ascertain which part of the expression caused the failure. The failure message for the previous
expression, for example, would be:
"yellow" did not equal "blue"Most likely this lack of short-circuiting would rarely be noticeable, because evaluating the right hand side will usually not involve a side effect. One situation where it might show up, however, is if you attempt to
and
a null
check on a variable with an expression
that uses the variable, like this:
map must (not be (null) and contain key ("ouch"))If
map
is null
, the test will indeed fail, but with a NullPointerException
, not a
TestFailedException
. Here, the NullPointerException
is the visible right-hand side effect. To get a
TestFailedException
, you would need to check each assertion separately:
map must not be (null) map must contain key ("ouch")If
map
is null
in this case, the null
check in the first expression will fail with
a TestFailedException
, and the second expression will never be executed.
The other difference with Boolean
operators is that although &&
has a higher precedence than ||
,
and
and or
have the same precedence. Thus although the Boolean
expression (a || b && c)
will evaluate the &&
expression
before the ||
expression, like (a || (b && c))
, the following expression:
traversable must (contain (7) or contain (8) and have size (9))Will evaluate left to right, as:
traversable must ((contain (7) or contain (8)) and have size (9))If you really want the
and
part to be evaluated first, you'll need to put in parentheses, like this:
traversable must (contain (7) or (contain (8) and have size (9)))== Working with
Option
s ==
ScalaTest matchers has no special support for Option
s, but you can
work with them quite easily using syntax shown previously. For example, if you wish to check
whether an option is None
, you can write any of:
option mustEqual None option mustBe None option must not be defined option mustBe emptyIf you wish to check an option is defined, and holds a specific value, you can write either of:
option mustEqual Some("hi") option mustBe Some("hi")If you only wish to check that an option is defined, but don't care what it's value is, you can write:
option mustBe definedIf you mix in (or import the members of)
OptionValues
,
you can write one statement that indicates you believe an option must be defined and then say something else about its value. Here's an example:
import org.scalatest.OptionValues._ option.value must be < 7== Checking arbitrary properties with
have
==
Using have
, you can check properties of any type, where a property is an attribute of any
object that can be retrieved either by a public field, method, or JavaBean-style get
or is
method, like this:
book must have ( 'title ("Programming in Scala"), 'author (List("Odersky", "Spoon", "Venners")), 'pubYear (2008) )This expression will use reflection to ensure the
title
, author
, and pubYear
properties of object book
are equal to the specified values. For example, it will ensure that book
has either a public Java field or method
named title
, or a public method named getTitle
, that when invoked (or accessed in the field case) results
in a the string "Programming in Scala"
. If all specified properties exist and have their expected values, respectively,
execution will continue. If one or more of the properties either does not exist, or exists but results in an unexpected value,
a TestFailedException
will be thrown that explains the problem. (For the details on how a field or method is selected during this
process, see the documentation for HavePropertyMatcherGenerator
.)
When you use this syntax, you must place one or more property values in parentheses after have
, seperated by commas, where a property
value is a symbol indicating the name of the property followed by the expected value in parentheses. The only exceptions to this rule is the syntax
for checking size and length shown previously, which does not require parentheses. If you forget and put parentheses in, however, everything will
still work as you'd expect. Thus instead of writing:
array must have length (3) set must have size (90)You can alternatively, write:
array must have (length (3)) set must have (size (90))If a property has a value different from the specified expected value, a
TestFailedError
will be thrown
with a detailed message that explains the problem. For example, if you assert the following on
a book
whose title is Moby Dick
:
book must have ('title ("A Tale of Two Cities"))You'll get a
TestFailedException
with this detail message:
The title property had value "Moby Dick", instead of its expected value "A Tale of Two Cities", on object Book("Moby Dick", "Melville", 1851)If you prefer to check properties in a type-safe manner, you can use a
HavePropertyMatcher
.
This would allow you to write expressions such as:
book must have ( title ("Programming in Scala"), author (List("Odersky", "Spoon", "Venners")), pubYear (2008) )These expressions would fail to compile if
must
is used on an inappropriate type, as determined
by the type parameter of the HavePropertyMatcher
being used. (For example, title
in this example
might be of type HavePropertyMatcher[org.publiclibrary.Book]
. If used with an appropriate type, such an expression will compile
and at run time the property method or field will be accessed directly; i.e., no reflection will be used.
See the documentation for HavePropertyMatcher
for more information.
== Using length
and size
with HavePropertyMatcher
s ==
If you want to use length
or size
syntax with your own custom HavePropertyMatcher
s, you
can do so, but you must write (of [“the type”])
afterwords. For example, you could write:
book must have ( title ("A Tale of Two Cities"), length (220) (of [Book]), author ("Dickens") )Prior to ScalaTest 2.0, “
length
(22)
” yielded a HavePropertyMatcher[Any, Int]
that used reflection to dynamically look
for a length
field or getLength
method. In ScalaTest 2.0, “length
(22)
” yields a
MatcherFactory1[Any, Length]
, so it is no longer a HavePropertyMatcher
. The (of [<type>])
syntax converts the
the MatcherFactory1[Any, Length]
to a HavePropertyMatcher[<type>, Int]
.
== Checking that an expression matches a pattern ==
ScalaTest's Inside
trait allows you to make assertions after a pattern match.
Here's an example:
case class Name(first: String, middle: String, last: String)You can use
val name = Name("Jane", "Q", "Programmer")
inside(name) { case Name(first, _, _) => first must startWith ("S") }
inside
to just ensure a pattern is matched, without making any further assertions, but a better
alternative for that kind of assertion is matchPattern
. The matchPattern
syntax allows you
to express that you expect a value to match a particular pattern, no more and no less:
name must matchPattern { case Name("Sarah", _, _) => }== Using custom matchers == If none of the built-in matcher syntax (or options shown so far for extending the syntax) satisfy a particular need you have, you can create custom
Matcher
s that allow
you to place your own syntax directly after must
. For example, class java.io.File
has a method isHidden
, which
indicates whether a file of a certain path and name is hidden. Because the isHidden
method takes no parameters and returns Boolean
,
you can call it using be
with a symbol or BePropertyMatcher
, yielding assertions like:
file must be ('hidden) // using a symbol file must be (hidden) // using a BePropertyMatcherIf it doesn't make sense to have your custom syntax follow
be
, you might want to create a custom Matcher
instead, so your syntax can follow must
directly. For example, you might want to be able to check whether
a java.io.File
's name ends with a particular extension, like this:
// using a plain-old Matcher file must endWithExtension ("txt")ScalaTest provides several mechanism to make it easy to create custom matchers, including ways to compose new matchers out of existing ones complete with new error messages. For more information about how to create custom
Matcher
s, please see the documentation for the Matcher
trait.
== Checking for expected exceptions ==
Sometimes you need to test whether a method throws an expected exception under certain circumstances, such
as when invalid arguments are passed to the method. With Matchers
mixed in, you can
check for an expected exception like this:
an [IndexOutOfBoundsException] must be thrownBy s.charAt(-1)If
charAt
throws an instance of StringIndexOutOfBoundsException
,
this expression will result in that exception. But if charAt
completes normally, or throws a different
exception, this expression will complete abruptly with a TestFailedException
.
If you need to further isnpect an expected exception, you can capture it using this syntax:
val thrown = the [IndexOutOfBoundsException] thrownBy s.charAt(-1)This expression returns the caught exception so that you can inspect it further if you wish, for example, to ensure that data contained inside the exception has the expected values. Here's an example:
thrown.getMessage must equal ("String index out of range: -1")
If you prefer you can also capture and inspect an expected exception in one statement, like this:
the [ArithmeticException] thrownBy 1 / 0 must have message "/ by zero" the [IndexOutOfBoundsException] thrownBy { s.charAt(-1) } must have message "String index out of range: -1"You can also state that no exception must be thrown by some code, like this:
noException must be thrownBy 0 / 1Note: the following syntax from ScalaTest 1.x has been deprecated:
evaluating { s.charAt(-1) } must produce [IndexOutOfBoundsException]Such uses will continue to work during the deprecation cycle, but support for this syntax will eventually be removed in a future version of ScalaTest. Please change all uses to a corresponding use of the syntax described previously in this section. == Those pesky parens == Perhaps the most tricky part of writing assertions using ScalaTest matchers is remembering when you need or don't need parentheses, but bearing in mind a few simple rules should help. It is also reassuring to know that if you ever leave off a set of parentheses when they are required, your code will not compile. Thus the compiler will help you remember when you need the parens. That said, the rules are: 1. Although you don't always need them, you may choose to always put parentheses around right-hand values, such as the
7
in num must equal (7)
:
result must equal (4) array must have length (3) book must have ( 'title ("Programming in Scala"), 'author (List("Odersky", "Spoon", "Venners")), 'pubYear (2008) ) option must be ('defined) catMap must (contain key (9) and contain value ("lives")) keyEvent must be an ('actionKey) javaSet must have size (90)2. Except for
length
, size
and message
, you must always put parentheses around
the list of one or more property values following a have
:
file must (exist and have ('name ("temp.txt"))) book must have ( title ("Programming in Scala"), author (List("Odersky", "Spoon", "Venners")), pubYear (2008) ) javaList must have length (9) // parens optional for length and size3. You must always put parentheses around
and
and or
expressions, as in:
catMap must (contain key (9) and contain value ("lives")) number must (equal (2) or equal (4) or equal (8))4. Although you don't always need them, you may choose to always put parentheses around custom
Matcher
s when they appear directly after not
:
file must exist file must not (exist) file must (exist and have ('name ("temp.txt"))) file must (not (exist) and have ('name ("temp.txt")) file must (have ('name ("temp.txt") or exist) file must (have ('name ("temp.txt") or not (exist))That's it. With a bit of practice it should become natural to you, and the compiler will always be there to tell you if you forget a set of needed parentheses. Note: ScalaTest's matchers are in part inspired by the matchers of RSpec, Hamcrest, and specs2, and its “
mustNot compile
” syntax
by the illTyped
macro of shapeless.
Trait that can be mixed into a Suite
to disable the lone implicit conversion provided by default in trait
Assertions
, which trait Suite
extends.
Trait that can be mixed into a Suite
to disable the lone implicit conversion provided by default in trait
Assertions
, which trait Suite
extends.
Currently there is just one implicit conversion provided by default in Suite
, the one that adds a ===
method to
anything. If more default implicits are added to Suite
in future versions of ScalaTest, they will be added here as well so that
this trait will disable all of them.
This trait can be used to quickly solve a problem in which ScalaTest's default implicit conversion is clashing with those of some other library you need to use in your tests. After mixing in this trait, like this:
class MySuite extends FunSuite with NonImplicitAssertions { // ... }
You can write tests using assert
(without triple equals), expect
, and intercept
:
assert(a < 7)
expect(2) { 1 + 1 }
intercept[IndexOutOfBoundsException] { "hi".charAt(-1) }
Trait providing an apply
method to which status updates about a running suite of tests can be reported.
Trait providing an apply
method to which status updates about a running suite of tests can be reported.
An Notifier
is essentially
used to wrap a Reporter
and provide easy ways to send status updates
to that Reporter
via an NoteProvided
event.
Notifier
contains an apply
method that takes a string and
an optional payload object of type Any
.
The Notifier
will forward the passed alert message
string to the
Reporter
as the message
parameter, and the optional
payload object as the payload
parameter, of an NoteProvided
event.
For insight into the differences between Notifier
, Alerter
, and Informer
, see the
main documentation for trait Notifying
.
Trait that contains the note
method, which can be used to send a status notification to the reporter.
Trait that contains the note
method, which can be used to send a status notification to the reporter.
The difference between note
and the info
method of Informer
is that
info
messages provided during a test are recorded and sent as part of test completion event, whereas
note
messages are sent right away as NoteProvided
messages. For long-running tests,
note
allows you to send "status notifications" to the reporter right away, so users can track the
progress of the long-running tests. By contrast, info
messages will only be seen by the user after the
test has completed, and are more geared towards specification (such as Given/When/Then messages) than notification.
The difference between note
and the alert
method of Alerting
is
that alert
is intended to be used
for warnings or notifications of potential problems, whereas note
is just for status notifications.
In string reporters for which ANSI color is enabled, note
notifications are shown in green and alert
notifications
in yellow.
Trait that facilitates a style of testing in which each test is run in its own instance of the suite class to isolate each test from the side effects of the other tests in the suite.
Trait that facilitates a style of testing in which each test is run in its own instance of the suite class to isolate each test from the side effects of the other tests in the suite.
Recommended Usage: Trait OneInstancePerTest is intended primarily to serve as a supertrait for
ParallelTestExecution and the path traits, to
facilitate porting JUnit tests to ScalaTest, and to make it easy for users who prefer JUnit's approach to isolation to obtain similar
behavior in ScalaTest.
|
If you mix this trait into a Suite
, you can initialize shared reassignable
fixture variables as well as shared mutable fixture objects in the constructor of the
class. Because each test will run in its own instance of the class, each test will
get a fresh copy of the instance variables. This is the approach to test isolation taken,
for example, by the JUnit framework. OneInstancePerTest
can, therefore,
be handy when porting JUnit tests to ScalaTest.
Here's an example of OneInstancePerTest
being used in a FunSuite
:
import org.scalatest.FunSuite import org.scalatest.OneInstancePerTest import collection.mutable.ListBuffer
class MySuite extends FunSuite with OneInstancePerTest {
val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String]
test("easy") { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
test("fun") { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } }
OneInstancePerTest
is supertrait to ParallelTestExecution
, in which
running each test in its own instance is intended to make it easier to write suites of tests that run in parallel (by reducing the likelihood
of concurrency bugs in those suites.) OneInstancePerTest
is also supertrait to the path traits,
path.FunSpec
and path.FreeSpec
, to make it obvious
these traits run each test in a new, isolated instance.
For the details on how OneInstancePerTest
works, see the documentation for methods runTests
and runTest
,
which this trait overrides.
Trait that provides an implicit conversion that adds a value
method
to Option
, which will return the value of the option if it is defined,
or throw TestFailedException
if not.
Trait that provides an implicit conversion that adds a value
method
to Option
, which will return the value of the option if it is defined,
or throw TestFailedException
if not.
This construct allows you to express in one statement that an option should be defined and that its value should meet some expectation. Here's an example:
opt.value should be > 9
Or, using an assertion instead of a matcher expression:
assert(opt.value > 9)
Were you to simply invoke get
on the Option
,
if the option wasn't defined, it would throw a NoSuchElementException
:
val opt: Option[Int] = NoneThe
opt.get should be > 9 // opt.get throws NoSuchElementException
NoSuchElementException
would cause the test to fail, but without providing a stack depth pointing
to the failing line of test code. This stack depth, provided by TestFailedException
(and a
few other ScalaTest exceptions), makes it quicker for
users to navigate to the cause of the failure. Without OptionValues
, to get
a stack depth exception you would need to make two statements, like this:
val opt: Option[Int] = NoneThe
opt should be ('defined) // throws TestFailedException opt.get should be > 9
OptionValues
trait allows you to state that more concisely:
val opt: Option[Int] = None
opt.value should be > 9 // opt.value throws TestFailedException
Superclass for the possible outcomes of running a test.
Superclass for the possible outcomes of running a test.
Outcome
is the result type of the withFixture
methods of traits
Suite
and fixture.Suite
, as well as their
NoArgTest
and OneArgTest
function types.
The four possible outcomes are:
Succeeded
- indicates a test succeededFailed
- indicates a test failed and contains an exception describing the failureCanceled
- indicates a test was canceled and contains an exception describing the cancelationPending
- indicates a test was pendingNote that "ignored" does not appear as a type of Outcome
, because tests are
marked as ignored on the outside and skipped over as the suite executes. So an ignored test never runs, and therefore
never has an outcome. By contrast, a test is determined to be pending by running the test
and observing the actual outcome. If the test body completes abruptly with a TestPendingException
,
then the outcome was that the test was pending.
Trait that contains the outcomeOf
method, which executes a passed code block and
transforms the outcome into an Outcome
, using the
same mechanism used by ScalaTest to produce an Outcome
when executing
a test.
Trait that causes that the tests of any suite it is mixed into to be run in parallel if
a Distributor
is passed to runTests
.
Trait that causes that the tests of any suite it is mixed into to be run in parallel if
a Distributor
is passed to runTests
.
ScalaTest's normal approach for running suites of tests in parallel is to run different suites in parallel, but the tests of any one suite sequentially. This approach should provide sufficient distribution of the work load in most cases, but some suites may encapsulate multiple long-running tests. Such suites may dominate the execution time of the run. If so, mixing in this trait into just those suites will allow their long-running tests to run in parallel with each other, thereby helping to reduce the total time required to run an entire run.
To make it easier for users to write tests that run in parallel, this trait runs each test in its own instance of the class.
Running each test in its own instance enables tests to use the same instance vars
and mutable objects referenced from
instance variables without needing to synchronize. Although ScalaTest provides functional approaches to
factoring out common test code that can help avoid such issues, running each test in its own instance is an insurance policy that makes
running tests in parallel easier and less error prone.
For the details on how ParallelTestExecution
works, see the documentation for methods run
, runTests
, and runTest
,
which this trait overrides.
Note: This trait's implementation of runTest
is final
, to ensure that behavior
related to individual tests are executed by the same thread that executes the actual test. This means,
for example, that you won't be allowed to write ...with ParallelTestExecution with BeforeAndAfter
.
Instead, you'd need to put ParallelTestExecution
last, as
in: with BeforeAndAfter with ParallelTestExecution
. For more details, see the documentation
for the runTest
method.
Trait that provides an implicit conversion that adds a valueAt
method
to PartialFunction
, which will return the value (result) of the function applied to the argument passed to valueAt
,
or throw TestFailedException
if the partial function is not defined at the argument.
Trait that provides an implicit conversion that adds a valueAt
method
to PartialFunction
, which will return the value (result) of the function applied to the argument passed to valueAt
,
or throw TestFailedException
if the partial function is not defined at the argument.
This construct allows you to express in one statement that a partial function should be defined for a particular input, and that its result value should meet some expectation. Here's an example:
pf.valueAt("IV") should equal (4)
Or, using an assertion instead of a matcher expression:
assert(pf.valueAt("IV") === 4)
Were you to simply invoke apply
on the PartialFunction
, passing in an input value,
if the partial function wasn't defined at that input, it would throw some exception, but likely not one
that provides a stack depth:
// Note: a Map[K, V] is a PartialFunction[K, V] val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)The
pf("V") should equal (5) // pf("V") throws NoSuchElementException
NoSuchElementException
thrown in this situation would cause the test to fail, but without providing a stack depth pointing
to the failing line of test code. This stack depth, provided by TestFailedException
(and a
few other ScalaTest exceptions), makes it quicker for
users to navigate to the cause of the failure. Without PartialFunctionValues
, to get
a stack depth exception you would need to make two statements, like this:
val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)The
pf.isDefinedAt("V") should be (true) // throws TestFailedException pf("V") should equal (5)
PartialFunctionValues
trait allows you to state that more concisely:
val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4)
pf.valueAt("V") should equal (5) // pf.valueAt("V") throws TestFailedException
Trait facilitating the inclusion of a payload in a thrown ScalaTest exception.
Trait facilitating the inclusion of a payload in a thrown ScalaTest exception.
This trait includes a withPayload
construct
that enables a payload object (or modified
payload object) to be included as the payload of a thrown exception.
Many ScalaTest events include an optional "payload" field that can be used
to pass information to a custom reporter. This trait facilitates such customization,
by making it easy to insert a payload into a thrown exception, such as a TestFailedException
.
The thrown exception must mix in Payload
.
ScalaTest looks for trait Payload
and fires any payloads it finds in the relevant ScalaTest event
stimulated by the exception, such as a TestFailed
event stimulated by a TestFailedException
.
Here's an example in which a GUI snapshot is included as a payload when a test fails:
withPayload(generateGUISnapshot()) { 1 + 1 should be === 3 }
Type that is used as the return type of the pending
method in class
Suite
, which always completes abruptly with a
TestPendingException
.
Type that is used as the return type of the pending
method in class
Suite
, which always completes abruptly with a
TestPendingException
.
This type is used primarily to facilitate the is (pending)
syntax of
traits FlatSpec
and WordSpec
, as well the
is (pending)
or (pending)
syntax of several traits
in the org.scalatest.fixture
package. Because the pending
method in Suite
always completes abruptly with an exception, its
type would be inferred to be Nothing
, which is a relatively common
type. To make sure syntax like is (pending)
only works with
method pending
, it is helpful to have a specially named
"Nothing
" type.
Trait that facilitates the testing of private methods.
Trait that facilitates the testing of private methods.
To test a private method, mix in trait PrivateMethodTester
and
create a PrivateMethod
object, like this:
val decorateToStringValue = PrivateMethod[String]('decorateToStringValue)
The type parameter on PrivateMethod
, in this case String
, is the result type of the private method
you wish to invoke. The symbol passed to the PrivateMethod.apply
factory method, in this
case 'decorateToStringValue
, is the name of the private method to invoke. To test
the private method, use the invokePrivate
operator, like this:
targetObject invokePrivate decorateToStringValue(1)
Here, targetObject
is a variable or singleton object name referring to the object whose
private method you want to test. You pass the arguments to the private method in the parentheses after
the PrivateMethod
object.
The result type of an invokePrivate
operation will be the type parameter of the PrivateMethod
object, thus you need not cast the result to use it. In other words, after creating a PrivateMethod
object, the
syntax to invoke the private method
looks like a regular method invocation, but with the dot (.
) replaced by invokePrivate
.
The private method is invoked dynamically via reflection, so if you have a typo in the method name symbol, specify the wrong result type,
or pass invalid parameters, the invokePrivate
operation will compile, but throw an exception at runtime.
One limitation to be aware of is that you can't use PrivateMethodTester
to test a private method
declared in a trait, because the class the trait gets mixed into will not declare that private method. Only the
class generated to hold method implementations for the trait will have that private method. If you want to
test a private method declared in a trait, and that method does not use any state of that trait, you can move
the private method to a companion object for the trait and test it using PrivateMethodTester
that
way. If the private trait method you want to test uses the trait's state, your best options are to test it
indirectly via a non-private trait method that calls the private method, or make the private method package access
and test it directly via regular static method invocations.
Also, if you want to use PrivateMethodTester
to invoke a parameterless private method, you'll need to use
empty parens. Instead of:
targetObject invokePrivate privateParameterlessMethod
You'll need to write:
targetObject invokePrivate privateParameterlessMethod()
A suite of property-based tests.
A suite of property-based tests.
Recommended Usage:
Class PropSpec is a good fit for teams that want to write tests exclusively in terms of property checks, and is also a good choice
for writing the occasional test matrix when a different style trait is chosen as the main unit testing style.
|
Here's an example PropSpec
:
package org.scalatest.examples.propspecYou can run a
import org.scalatest._ import prop._ import scala.collection.immutable._
class SetSpec extends PropSpec with TableDrivenPropertyChecks with ShouldMatchers {
val examples = Table( "set", BitSet.empty, HashSet.empty[Int], TreeSet.empty[Int] )
property("an empty Set should have size 0") { forAll(examples) { set => set.size should be (0) } }
property("invoking head on an empty set should produce NoSuchElementException") { forAll(examples) { set => evaluating { set.head } should produce [NoSuchElementException] } } }
PropSpec
by invoking execute
on it.
This method, which prints test results to the standard output, is intended to serve as a
convenient way to run tests from within the Scala interpreter. For example,
to run SetSpec
from within the Scala interpreter, you could write:
scala> new SetSpec executeAnd you would see:
SetSpec:
- an empty Set should have size 0
- invoking head on an empty Set should produce NoSuchElementException
Or, to run just the “an empty Set should have size 0
” method, you could pass that test's name, or any unique substring of the
name, such as "size 0"
or even just "0"
. Here's an example:
scala> new SetSpec execute "size 0"
SetSpec:
- an empty Set should have size 0
You can also pass to execute
a config map of key-value
pairs, which will be passed down into suites and tests, as well as other parameters that configure the run itself.
For more information on running in the Scala interpreter, see the documentation for execute
(below) and the
ScalaTest shell.
The execute
method invokes a run
method that takes two
parameters. This run
method, which actually executes the suite, will usually be invoked by a test runner, such
as run
, tools.Runner
, a build tool, or an IDE.
“property
” is a method, defined in PropSpec
, which will be invoked
by the primary constructor of SetSpec
. You specify the name of the test as
a string between the parentheses, and the test code itself between curly braces.
The test code is a function passed as a by-name parameter to property
, which registers
it for later execution.
A PropSpec
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Tests can only be registered with the property
method while the PropSpec
is
in its registration phase. Any attempt to register a test after the PropSpec
has
entered its ready phase, i.e., after run
has been invoked on the PropSpec
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using PropSpec
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, PropSpec
provides registration
methods that start with ignore
instead of property
. Here's an example:
package org.scalatest.examples.suite.ignoreIf you run this version of
import org.scalatest._ import prop._ import scala.collection.immutable._
class SetSpec extends PropSpec with TableDrivenPropertyChecks with ShouldMatchers {
val examples = Table( "set", BitSet.empty, HashSet.empty[Int], TreeSet.empty[Int] )
ignore("an empty Set should have size 0") { forAll(examples) { set => set.size should be (0) } }
property("invoking head on an empty set should produce NoSuchElementException") { forAll(examples) { set => evaluating { set.head } should produce [NoSuchElementException] } } }
SetSuite
with:
scala> new SetSpec executeIt will run only the second test and report that the first test was ignored:
SetSuite: - an empty Set should have size 0 !!! IGNORED !!! - invoking head on an empty Set should produce NoSuchElementException== Informers == One of the parameters to
PropSpec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by PropSpec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information
to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via its apply
method.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
Here's an example that shows both a direct use as well as an indirect use through the methods
of GivenWhenThen
:
package org.scalatest.examples.propspec.infoIf you run this
import org.scalatest._ import prop._ import collection.mutable
class SetSpec extends PropSpec with TableDrivenPropertyChecks with GivenWhenThen {
val examples = Table( "set", mutable.BitSet.empty, mutable.HashSet.empty[Int], mutable.LinkedHashSet.empty[Int] )
property("an element can be added to an empty mutable Set") {
forAll(examples) { set =>
info("—————-")
Given("an empty mutable " + set.getClass.getSimpleName) assert(set.isEmpty)
When("an element is added") set += 99
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains(99)) } } }
PropSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
SetSpec:
- an element can be added to an empty mutable Set
+ ----------------
+ Given an empty mutable BitSet
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ ----------------
+ Given an empty mutable HashSet
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ ----------------
+ Given an empty mutable LinkedHashSet
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
== Documenters ==
PropSpec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example PropSpec
that uses markup
:
package org.scalatest.examples.propspec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import org.scalatest._ import prop._ import collection.mutable
class SetSpec extends PropSpec with TableDrivenPropertyChecks with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
val examples = Table( "set", mutable.BitSet.empty, mutable.HashSet.empty[Int], mutable.LinkedHashSet.empty[Int] )
property("an element can be added to an empty mutable Set") {
forAll(examples) { set =>
info("—————-")
Given("an empty mutable " + set.getClass.getSimpleName) assert(set.isEmpty)
When("an element is added") set += 99
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains(99)) }
markup("This test finished with a **bold** statement!") } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.propspec.noteBecause
import org.scalatest._ import prop._ import collection.mutable
class SetSpec extends PropSpec with TableDrivenPropertyChecks {
val examples = Table( "set", mutable.BitSet.empty, mutable.HashSet.empty[Int], mutable.LinkedHashSet.empty[Int] )
property("an element can be added to an empty mutable Set") {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
forAll(examples) { set =>
assert(set.isEmpty) set += 99 assert(set.size === 1) assert(set.contains(99)) } } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSpec: + notes are sent immediately + alerts are also sent immediately - an element can be added to an empty mutable Set + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run.
(The code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality, has not yet been implemented.
You can mark tests pending in PropSpec
like this:
import org.scalatest._ import prop._ import scala.collection.immutable._(Note: "
class SetSpec extends PropSpec with TableDrivenPropertyChecks with ShouldMatchers {
val examples = Table( "set", BitSet.empty, HashSet.empty[Int], TreeSet.empty[Int] )
property("an empty Set should have size 0") (pending)
property("invoking head on an empty set should produce NoSuchElementException") { forAll(examples) { set => evaluating { set.head } should produce [NoSuchElementException] } } }
(pending)
" is the body of the test. Thus the test contains just one statement, an invocation
of the pending
method, which throws TestPendingException
.)
If you run this version of SetSuite
with:
scala> new SetSuite executeIt will run both tests, but report that first test is pending. You'll see:
SetSuite: - An empty Set should have size 0 (pending) - Invoking head on an empty Set should produce NoSuchElementExceptionOne difference between an ignored test and a pending one is that an ignored test is intended to be used during a significant refactorings of the code under test, when tests break and you don't want to spend the time to fix all of them immediately. You can mark some of those broken tests as ignored temporarily, so that you can focus the red bar on just failing tests you actually want to fix immediately. Later you can go back and fix the ignored tests. In other words, by ignoring some failing tests temporarily, you can more easily notice failed tests that you actually want to fix. By contrast, a pending test is intended to be used before a test and/or the code under test is written. Pending indicates you've decided to write a test for a bit of behavior, but either you haven't written the test yet, or have only written part of it, or perhaps you've written the test but don't want to implement the behavior it tests until after you've implemented a different bit of behavior you realized you need first. Thus ignored tests are designed to facilitate refactoring of existing code whereas pending tests are designed to facilitate the creation of new code. One other difference between ignored and pending tests is that ignored tests are implemented as a test tag that is excluded by default. Thus an ignored test is never executed. By contrast, a pending test is implemented as a test that throws
TestPendingException
(which is what calling the pending
method does). Thus
the body of pending tests are executed up until they throw TestPendingException
. The reason for this difference
is that it enables your unfinished test to send InfoProvided
messages to the reporter before it completes
abruptly with TestPendingException
, as shown in the previous example on Informer
s
that used the GivenWhenThen
trait.
== Tagging tests ==
A PropSpec
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a PropSpec
, groups of tests can
optionally be included and/or excluded. To tag a PropSpec
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for PropSpec
s like this:
package org.scalatest.examples.propspec.taggingGiven these definitions, you could place
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
PropSpec
tests into groups like this:
import org.scalatest._ import prop._ import scala.collection.immutable._This code marks both tests with the
class SetSpec extends PropSpec with TableDrivenPropertyChecks with ShouldMatchers {
val examples = Table( "set", BitSet.empty, HashSet.empty[Int], TreeSet.empty[Int] )
property("an empty Set should have size 0", SlowTest) { forAll(examples) { set => set.size should be (0) } }
property("invoking head on an empty set should produce NoSuchElementException", SlowTest, DbTest) {
forAll(examples) { set => evaluating { set.head } should produce [NoSuchElementException] } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The techniques in PropSpec
are identical to those in FunSuite
, but with “test
”
replaced by “property
”. The following table summarizes the options with a link to the relevant
documentation for trait FunSuite
:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
PropSpec
to implement a test matrix ====
Using fixture-context objects in a PropSpec
is a good way to implement a test matrix.
What is the matrix? A test matrix is a series of tests that you need to run on a series of subjects. For example, The Scala API contains
many implementations of trait Set
. Every implementation must obey the contract of Set
.
One property of any Set
is that an empty Set
should have size 0, another is that
invoking head on an empty Set
should give you a NoSuchElementException
, and so on. Already you have a matrix,
where rows are the properties and the columns are the set implementations:
BitSet | HashSet | TreeSet | |
---|---|---|---|
An empty Set should have size 0 | pass | pass | pass |
Invoking head on an empty set should produce NoSuchElementException | pass | pass | pass |
BitSet
, HashSet
,
and TreeSet
) as elements in a single-dimensional Table
. Each element in the Table
represents
one Set
implementation. Because different properties may require different fixture instances for those implementations, you
can define a trait to hold the examples, like this:
trait SetExamples extends Tables {Given this trait, you could provide empty sets in one implementation of
def examples = Table("set", bitSet, hashSet, treeSet)
def bitSet: BitSet def hashSet: HashSet[Int] def treeSet: TreeSet[Int] }
SetExamples
, and non-empty sets in another.
Here's how you might provide empty set examples:
class EmptySetExamples extends SetExamples { def bitSet = BitSet.empty def hashSet = HashSet.empty[Int] def treeSet = TreeSet.empty[Int] }And here's how you might provide set examples with one item each:
class SetWithOneItemExamples extends SetExamples { def bitSet = BitSet(1) def hashSet = HashSet(1) def treeSet = TreeSet(1) }Armed with these example classes, you can define checks of properties that require empty or non-empty set fixtures by using instances of these classes as fixture-context objects. In other words, the columns of the test matrix are implemented as elements of a one-dimensional table of fixtures, the rows are implemented as
property
clauses of a PropSpec
.
Here's a complete example that checks the two properties mentioned previously:
package org.scalatest.examples.propspec.matrixOne benefit of this approach is that the compiler will help you when you need to add either a new row or column to the matrix. In either case, you'll need to ensure all cells are checked to get your code to compile. == Shared tests == Sometimes you may want to run the same test code on different fixture objects. That is to say, you may want to write tests that are "shared" by different fixture objects. You accomplish this in a
import org.scalatest._ import org.scalatest.prop._ import scala.collection.immutable._
trait SetExamples extends Tables {
def examples = Table("set", bitSet, hashSet, treeSet)
def bitSet: BitSet def hashSet: HashSet[Int] def treeSet: TreeSet[Int] }
class EmptySetExamples extends SetExamples { def bitSet = BitSet.empty def hashSet = HashSet.empty[Int] def treeSet = TreeSet.empty[Int] }
class SetSpec extends PropSpec with TableDrivenPropertyChecks with ShouldMatchers {
property("an empty Set should have size 0") { new EmptySetExamples { forAll(examples) { set => set.size should be (0) } } }
property("invoking head on an empty set should produce NoSuchElementException") { new EmptySetExamples { forAll(examples) { set => evaluating { set.head } should produce [NoSuchElementException] } } } }
PropSpec
in the same way you would do it in a FunSuite
, except instead of test
you say property
, and instead of testsFor
you say propertiesFor
.
For more information, see the Shared tests section of FunSuite
's
documentation.
Implementation trait for class PropSpec
, which represents
a suite of property-based tests.
Implementation trait for class PropSpec
, which represents
a suite of property-based tests.
PropSpec
is a class, not a trait,
to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the
behavior of PropSpec
into some other class, you can use this
trait instead, because class PropSpec
does nothing more than
extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed
overview of PropSpec
.
Trait that causes tests to be run in pseudo-random order.
Trait that causes tests to be run in pseudo-random order.
Although the tests are run in pseudo-random order, events will be fired in the “normal” order for the Suite
that mixes in this trait, as determined by runTests
.
The purpose of this trait is to reduce the likelihood of unintentional order dependencies between tests in the same test class.
Trait whose instances collect the results of a running suite of tests and presents those results in some way to the user.
Trait whose instances collect the results of a running suite of tests and presents those results in some way to the user. Instances of this trait can be called "report functions" or "reporters."
Reporters receive test results via fifteen events. Each event is fired to pass a particular kind of information to the reporter. The events are:
DiscoveryStarting
DiscoveryCompleted
RunStarting
RunStopped
RunAborted
RunCompleted
ScopeOpened
ScopeClosed
ScopePending
TestStarting
TestSucceeded
TestFailed
TestCanceled
TestIgnored
TestPending
SuiteStarting
SuiteCompleted
SuiteAborted
InfoProvided
MarkupProvided
AlertProvided
NoteProvided
Reporters may be implemented such that they only present some of the reported events to the user. For example, you could
define a reporter class that does nothing in response to SuiteStarting
events.
Such a class would always ignore SuiteStarting
events.
The term test as used in the TestStarting
, TestSucceeded
,
and TestFailed
event names
is defined abstractly to enable a wide range of test implementations.
ScalaTest's style traits (subclasse of trait Suite
) fire
TestStarting
to indicate they are about to invoke one
of their tests, TestSucceeded
to indicate a test returned normally,
and TestFailed
to indicate a test completed abruptly with an exception.
Although the execution of a Suite
subclass's tests will likely be a common event
reported via the
TestStarting
, TestSucceeded
, and TestFailed
events, because
of the abstract definition of “test” used by the
the event classes, these events are not limited to this use. Information about any conceptual test
may be reported via the TestStarting
, TestSucceeded
, and
TestFailed
events.
Likewise, the term suite as used in the SuiteStarting
, SuiteAborted
,
and SuiteCompleted
event names
is defined abstractly to enable a wide range of suite implementations.
Object Runner
fires SuiteStarting
to indicate it is about to invoke
run
on a
Suite
, SuiteCompleted
to indicate a Suite
's
run
method returned normally,
and SuiteAborted
to indicate a Suite
's run
method completed abruptly with an exception.
Similarly, class Suite
fires SuiteStarting
to indicate it is about to invoke
run
on a
nested Suite
, SuiteCompleted
to indicate a nested Suite
's
run
method returned normally,
and SuiteAborted
to indicate a nested Suite
's run
method completed abruptly with an exception.
Although the execution of a Suite
's run
method will likely be a
common event reported via the
SuiteStarting
, SuiteAborted
, and SuiteCompleted
events, because
of the abstract definition of "suite" used by the
event classes, these events are not limited to this use. Information about any conceptual suite
may be reported via the SuiteStarting
, SuiteAborted
, and
SuiteCompleted
events.
You can create classes that extend Reporter
to report test results in custom ways, and to
report custom information passed as an event "payload."
Reporter
classes can handle events in any manner, including doing nothing.
Subtrait of Reporter
that contains a dispose
method for
releasing any finite, non-memory resources, such as file handles, held by the
Reporter
.
Subtrait of Reporter
that contains a dispose
method for
releasing any finite, non-memory resources, such as file handles, held by the
Reporter
. Runner
will invoke dispose
on
any ResourcefulReporter
when it no longer needs the Reporter
.
Provides methods that can be used in withFixture
implementations to retry tests in various scenarios.
Provides methods that can be used in withFixture
implementations to retry tests in various scenarios.
Trait Retries
is intended to help you deal with “flickers”—tests that usually pass, but
occasionally fail. The best way to deal with such tests is to fix them so they always pass. Sometimes, however, this is
not practical. In such cases, flickers can waste your time by forcing you to investigate test failures that turn
out to be flickers. Or worse, like the boy who cried wolf, the flickers may train you an your colleagues to not pay attention
to failures such that you don't notice real problems, at least not in a timely manner.
Trait Retries
offers methods that will retry a failed and/or canceled test once, on the same thread,
with or without a delay. These methods take a block that results in Outcome
,
and are intended to be used in withFixture
methods. You should be very selective about which tests you
retry, retrying those for which you have good evidence to conclude they are flickers. Thus it is recommended you
only retry tests that are tagged with Retryable
, and only tag tests as such once they have flickered
consistently for a while, and only after you invested a reasonable effort into fixing them properly.
Here's an example showing how you might use Retries
:
package org.scalatest.examples.tagobjects.retryable
import org.scalatest._ import tagobjects.Retryable
class SetSpec extends FlatSpec with Retries {
override def withFixture(test: NoArgTest) = { if (isRetryable(test)) withRetry { super.withFixture(test) } else super.withFixture(test) }
"An empty Set" should "have size 0" taggedAs(Retryable) in { assert(Set.empty.size === 0) } }
A Suite
class mixing in SequentialNestedSuiteExecution
that takes
zero to many Suite
s, which will be returned from its nestedSuites
method.
A Suite
class mixing in SequentialNestedSuiteExecution
that takes
zero to many Suite
s, which will be returned from its nestedSuites
method.
For example, you can define a suite that always executes a list of nested suites like this:
class StepsSuite extends Sequential( new Step1Suite, new Step2Suite, new Step3Suite, new Step4Suite, new Step5Suite )
When StepsSuite
is executed, it will execute its
nested suites in the passed order: Step1Suite
, Step2Suite
,
Step3Suite
, Step4Suite
, and Step5Suite
.
Because Sequential
extends SequentialNestedSuiteExecution
,
the distributor passed to runNestedSuites
will always be None
.
So not only will the suites passed to the constructor be executed sequentially, any
tests and nested suites of the passed suites will also be executed sequentually.
The difference between Sequential
and Stepwise
is that although Stepwise
executes its own nested suites sequentially, it passes
whatever distributor was passed to it to those nested suites. Thus the nested suites could run their own nested
suites and tests in parallel if that distributor is defined. By contrast, Sequential
always
passes None
for the distributor to the nested suites, so any and every test and nested suite
contained within the nested suites passed to the Sequential
construtor will be executed sequentially.
if suitesToNest
, or any suite
it contains, is null
.
Trait that causes the nested suites of any suite it is mixed into to be run sequentially even if
a Distributor
is passed to runNestedSuites
.
Trait that causes the nested suites of any suite it is mixed into to be run sequentially even if
a Distributor
is passed to runNestedSuites
. This trait overrides the
runNestedSuites
method and fowards every parameter passed to it to a superclass invocation
of runNestedSuites
, except it always passes None
for the Distributor
.
Mix in this trait into any suite whose nested suites need to be run sequentially even with the rest of the
run is being executed concurrently.
Trait that causes StackDepth
exceptions thrown by a running test (such as TestFailedException
s) to have
the exception's stack trace severed at the stack depth.
Trait that causes StackDepth
exceptions thrown by a running test (such as TestFailedException
s) to have
the exception's stack trace severed at the stack depth. Because the stack depth indicates the exact line of code that caused
the exception to be thrown, the severed stack trace will show that offending line of code on top. This can make the line
of test code that discovered a problem to be more easily found in IDEs and tools that don't make use of
ScalaTest's StackDepth
exceptions directly.
Trait whose instances provide a run
method and configuration fields that implement
the ScalaTest shell: its DSL for the Scala interpreter.
Trait whose instances provide a run
method and configuration fields that implement
the ScalaTest shell: its DSL for the Scala interpreter.
The main command of the ScalaTest shell is run
, which you can use to run a suite of tests.
The shell also provides several commands for configuring a call to run
:
color
(the default) - display results in color (green for success; red for failure; yellow for warning; blue for statistics)nocolor
- display results without colordurations
- display durations of (i.e., how long it took to run) tests and suitesnodurations
(the default) - do not display durations of tests and suitesshortstacks
- display short (i.e., truncated to show just the most useful portion) stack traces for all exceptionsfullstacks
- display full stack trackes for all exceptionsnostacks
(the default) - display no stack trace for StackDepth
exceptions and a short stack trace for non-StackDepth
exceptionsstats
- display statistics before and after the run, such as expected test count before the run and tests succeeded, failed, pending,
etc., counts after the runnostats
(the default) not display statistics before or after the runThe default configuration is color
, nodurations
, nostacks
, and nostats
.
All of these commands are fields of trait org.scalatest.Shell
. Each configuration command is a field that refers to
another Shell
instance with every configuration parameter
the same except for the one you've asked to change. For example, durations
provides a
Shell
instance that has every parameter configured the same way, except with durations enabled. When you invoke
run
on that, you will get a run with durations enabled and every other configuration parameter at its default value.
The other useful "command"
to know about, though not technically part of the shell, is the apply
factory method in the Suites
singleton object. This allows you to easily create composite suites out of nested suites, which you can then pass to run
. This
will be demonstrated later in this documentation.
The package object of the org.scalatest
package, although it does not extend Shell
, declares all the
same members as Shell
. Its run
method runs with all the Shell
configuration parameters set
to their default values. A good way to use the ScalaTest shell, therefore, is to import the members of package org.scalatest
:
scala> import org.scalatest._
import org.scalatest._
One thing importing org.scalatest._
allows you to do is access any of ScalaTest's classes and traits by shorter
names, for example:
scala> class ArithmeticSuite extends FunSuite with matchers.ShouldMatchers {
| test("addition works") {
| 1 + 1 should equal (2)
| }
| ignore("subtraction works") {
| 1 - 1 should equal (0)
| }
| test("multiplication works") {
| 1 * 1 should equal (2)
| }
| test("division works") (pending)
| }
defined class ArithmeticSuite
But importing org.scalatest._
also brings into scope the commands of the Shell
, so you can, for
example, invoke run
without qualification:
scala> run(new ArithmeticSuite) ArithmeticSuite: - addition works - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** 1 did not equal 2 (:16) - division works (pending)
To configure a single run, you can prefix run by one or more configuration commands, separated by dots. For example, to enable durations during a single run, you would write:
scala> durations.run(new ArithmeticSuite) ArithmeticSuite: - addition works (102 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (36 milliseconds) 1 did not equal 2 (:16) - division works (pending)
To enable statistics during a single run, you would write:
scala> stats.run(new ArithmeticSuite) Run starting. Expected test count is: 3 ArithmeticSuite: - addition works - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** 1 did not equal 2 (:16) - division works (pending) Run completed in 386 milliseconds. Total number of tests run: 2 Suites: completed 1, aborted 0 Tests: succeeded 1, failed 1, ignored 1, pending 1 *** 1 TEST FAILED ***
And to enable both durations and statistics during a single run, you could write:
scala> durations.stats.run(new ArithmeticSuite) Run starting. Expected test count is: 3 ArithmeticSuite: - addition works (102 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED (36 milliseconds)*** 1 did not equal 2 (:16) - division works (pending) Run completed in 386 milliseconds. Total number of tests run: 2 Suites: completed 1, aborted 0 Tests: succeeded 1, failed 1, ignored 1, pending 1 *** 1 TEST FAILED ***
The order doesn't matter when you are chaining multiple configuration commands. You'll get the same
result whether you write durations.stats.run
or stats.durations.run
.
To disable color, use nocolor
:
scala> nocolor.run(new ArithmeticSuite)
ArithmeticSuite:
- addition works
- subtraction works !!! IGNORED !!!
- multiplication works *** FAILED ***
1 did not equal 2 (:16)
- division works (pending)
To enable short stack traces during a single run, use shortstacks
:
scala> shortstacks.run(new ArithmeticSuite) ArithmeticSuite: - addition works (101 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (33 milliseconds) 1 did not equal 2 (:16) org.scalatest.TestFailedException: ... at line2$object$$iw$$iw$$iw$$iw$ArithmeticSuite$$anonfun$3.apply$mcV$sp( - division works (pending):16) at line2$object$$iw$$iw$$iw$$iw$ArithmeticSuite$$anonfun$3.apply( :16) at line2$object$$iw$$iw$$iw$$iw$ArithmeticSuite$$anonfun$3.apply( :16) at org.scalatest.FunSuite$$anon$1.apply(FunSuite.scala:992) at org.scalatest.Suite$class.withFixture(Suite.scala:1661) at line2$object$$iw$$iw$$iw$$iw$ArithmeticSuite.withFixture( :8) at org.scalatest.FunSuite$class.invokeWithFixture$1(FunSuite.scala:989) ...
If you want to change the default for multiple runs, you can import the members of your favorite Shell
configuration. For example,
if you always like to run with durations and statistics enabled, you could write:
scala> import stats.durations._
import stats.durations._
Now anytime you run statistics and durations will, by default, be enabled:
scala> run(new ArithmeticSuite) Run starting. Expected test count is: 3 ArithmeticSuite: - addition works (9 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (10 milliseconds) 1 did not equal 2 (:18) - division works (pending) Run completed in 56 milliseconds. Total number of tests run: 2 Suites: completed 1, aborted 0 Tests: succeeded 1, failed 1, ignored 1, pending 1 *** 1 TEST FAILED ***
If you want to run multiple suites, you can use the factory method in the Suites
singleton object. If you wrap a comma-separated list of suite instances inside Suites(...)
, for example,
you'll get a suite instance that contains no tests, but whose nested suites includes the suite instances you placed between
the parentheses. You can place Suites
inside Suites
to any level of depth, creating a tree of
suites to pass to run
. Here's a (contrived) example in which ArithmeticSuite
is executed four times:
scala> run(Suites(new ArithmeticSuite, new ArithmeticSuite, Suites(new ArithmeticSuite, new ArithmeticSuite))) Run starting. Expected test count is: 12 Suites: ArithmeticSuite: - addition works (0 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (1 millisecond) 1 did not equal 2 (:16) - division works (pending) ArithmeticSuite: - addition works (1 millisecond) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (0 milliseconds) 1 did not equal 2 (:16) - division works (pending) Suites: ArithmeticSuite: - addition works (0 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (0 milliseconds) 1 did not equal 2 (:16) - division works (pending) ArithmeticSuite: - addition works (0 milliseconds) - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** (0 milliseconds) 1 did not equal 2 (:16) - division works (pending) Run completed in 144 milliseconds. Total number of tests run: 8 Suites: completed 6, aborted 0 Tests: succeeded 4, failed 4, ignored 4, pending 4 *** 4 TESTS FAILED ***
The run
command also allows you to specify the name of a test to run and/or a config map. You can run
a particular test in a suite, for example, by specifying the test name after the suite instance in your call to run
, like this:
scala> run(new ArithmeticSuite, "addition works") ArithmeticSuite: - addition works
Convenience type alias allowing ShouldMatchers
to be used without qualification or another import
after a wildcard import of org.scalatest
.
Convenience type alias allowing ShouldMatchers
to be used without qualification or another import
after a wildcard import of org.scalatest
.
Facilitates a “behavior-driven” style of development (BDD), in which tests are methods, optionally nested inside singleton objects defining textual scopes.
Facilitates a “behavior-driven” style of development (BDD), in which tests are methods, optionally nested inside singleton objects defining textual scopes.
Recommended Usage:
Class Spec allows you to define tests as methods, which saves one function literal per test compared to style classes that represent tests as functions.
Fewer function literals translates into faster compile times and fewer generated class files, which can help minimize build times.
As a result, using Spec can be a good choice in large projects where build times are a concern as well as when generating large numbers of
tests programatically via static code generators.
|
Here's an example Spec
:
package org.scalatest.examples.specA
import org.scalatest.Spec
class SetSpec extends Spec {
object `A Set` { object `when empty` { def `should have size 0` { assert(Set.empty.size === 0) }
def `should produce NoSuchElementException when head is invoked` { intercept[NoSuchElementException] { Set.empty.head } } } } }
Spec
can contain scopes and tests. You define a scope
with a nested singleton object, and a test with a method. The names of both scope objects and test methods
must be expressed in back ticks and contain at least one space character.
A space placed in backticks is encoded by the Scala compiler as $u0020
, as
illustrated here:
scala> def `an example` = () an$u0020example: Unit
Spec
uses reflection to discover scope objects and test methods.
During discovery, Spec
will consider any nested singleton object whose name
includes $u0020
a scope object, and any method whose name includes $u0020
a test method.
It will ignore any singleton objects or methods that do not include a $u0020
character. Thus, Spec
would
not consider the following singleton object a scope object:
object `Set` { // Not discovered, because no space character }You can make such a scope discoverable by placing a space at the end, like this:
object `Set ` { // Discovered, because of the trailing space character }Rather than performing this discovery during construction, when instance variables used by scope objects may as yet be uninitialized,
Spec
performs discovery lazily, the first time a method needing the results of discovery is invoked.
For example, methods run
, runTests
, tags
, expectedTestCount
,
runTest
, and testNames
all ensure that scopes and tests have already been discovered prior to doing anything
else. Discovery is performed, and the results recorded, only once for each Spec
instance.
A scope names, or gives more information about, the subject (class or other entity) you are specifying
and testing. In the previous example, `A Set`
is the subject under specification and test. With each test name you provide a string (the test text) that specifies
one bit of behavior of the subject, and a block of code (the body of the test method) that verifies that behavior.
When you execute a Spec
, it will send Formatter
s in the events it sends to the
Reporter
. ScalaTest's built-in reporters will report these events in such a way
that the output is easy to read as an informal specification of the subject being tested.
For example, were you to run SetSpec
from within the Scala interpreter:
scala> new SetSpec executeYou would see:
A Set when empty - should have size 0 - should produce NoSuchElementException when head is invokedOr, to run just the test named
A Set when empty should have size 0
, you could pass that test's name, or any unique substring of the
name, such as "size 0"
or even just "0"
. Here's an example:
scala> new SetSuite execute "size 0" A Set when empty - should have size 0You can also pass to
execute
a config map of key-value
pairs, which will be passed down into suites and tests, as well as other parameters that configure the run itself.
For more information on running in the Scala interpreter, see the documentation for the
ScalaTest shell.
The execute
method invokes a run
method that takes two
parameters. This run
method, which actually executes the suite, will usually be invoked by a test runner, such
as run
, tools.Runner
, a build tool, or an IDE.
The test methods shown in this example are parameterless. This is recommended even for test methods with obvious side effects. In production code
you would normally declare no-arg, side-effecting methods as empty-paren methods, and call them with
empty parentheses, to make it more obvious to readers of the code that they have a side effect. Whether or not a test method has
a side effect, however, is a less important distinction than it is for methods in production code. Moreover, test methods are not
normally invoked directly by client code, but rather through reflection by running the Suite
that contains them, so a
lack of parentheses on an invocation of a side-effecting test method would not normally appear in any client code. Given the empty
parentheses do not add much value in the test methods case, the recommended style is to simply always leave them off.
Note: The approach of using backticks around test method names to make it easier to write descriptive test names was
inspired by the SimpleSpec
test framework, originally created by Coda Hale.
== Ignored tests ==
To support the common use case of temporarily disabling a test in a Spec
, with the
good intention of resurrecting the test at a later time, you can annotate the test method with @Ignore
.
For example, to temporarily disable the test method with the name `should have size zero"
, just annotate
it with @Ignore
, like this:
package org.scalatest.examples.spec.ignoreIf you run this version of
import org.scalatest._
class SetSpec extends Spec {
object `A Set` { object `when empty` { @Ignore def `should have size 0` { assert(Set.empty.size === 0) }
def `should produce NoSuchElementException when head is invoked` { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
with:
scala> new SetSpec executeIt will run only the second test and report that the first test was ignored:
A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invokedIf you wish to temporarily ignore an entire suite of tests, you can annotate the test class with
@Ignore
, like this:
package org.scalatest.examples.spec.ignoreallWhen you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the
import org.scalatest._
@Ignore class SetSpec extends Spec {
object `A Set` { object `when empty` { def `should have size 0` { assert(Set.empty.size === 0) }
def `should produce NoSuchElementException when head is invoked` { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSpec
in the Scala interpreter, you'll see:
scala> new SetSpec execute SetSpec: A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invoked !!! IGNORED !!!Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored class visible, to encourage the developers to eventually fix and “un-ignore” it. If you want to prevent a class from being discovered at all, use the
DoNotDiscover
annotation instead.
== Informers ==
One of the objects to Spec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by Spec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via one of its apply
methods.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
Here's an example in which the Informer
returned by info
is used implicitly by the
Given
, When
, and Then
methods of trait GivenWhenThen
:
package org.scalatest.examples.spec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends Spec with GivenWhenThen {
object `A mutable Set` { def `should allow an element to be added` { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } } }
Spec
from the interpreter, you will see the following output:
scala> new SetSpec execute
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
== Documenters ==
Spec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example Spec
that uses markup
:
package org.scalatest.examples.spec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSpec extends Spec with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
object `A mutable Set` { def `should allow an element to be added` { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.spec.noteBecause
import collection.mutable import org.scalatest._
class SetSpec extends Spec {
object `A mutable Set` { def `should allow an element to be added` {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSpec: A mutable Set + notes are sent immediately + alerts are also sent immediately - should allow an element to be added + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run.
(The code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality, has not yet been implemented.
You can mark a test as pending in Spec
by using "{ pending }
" as the body of the test method,
like this:
package org.scalatest.examples.spec.pending(Note: “
import org.scalatest._
class SetSpec extends Spec {
object `A Set` { object `when empty` { def `should have size 0` { pending }
def `should produce NoSuchElementException when head is invoked` { intercept[NoSuchElementException] { Set.empty.head } } } } }
pending
” is the body of the test. Thus the test contains just one statement, an invocation
of the pending
method, which throws TestPendingException
.)
If you run this version of SetSpec
with:
scala> new SetSpec executeIt will run both tests, but report that test "
should have size 0
" is pending. You'll see:
A Set when empty - should have size 0 (pending) - should produce NoSuchElementException when head is invoked== Tagging tests == A
Spec
's tests may be classified into groups by tagging them with string names. When executing
a Spec
, groups of tests can optionally be included and/or excluded. In this
trait's implementation, tags are indicated by annotations attached to the test method. To
create a new tag type to use in Spec
s, simply define a new Java annotation that itself is annotated with
the org.scalatest.TagAnnotation
annotation.
(Currently, for annotations to be
visible in Scala programs via Java reflection, the annotations themselves must be written in Java.) For example,
to create tags named SlowTest
and DbTest
, you would
write in Java:
package org.scalatest.examples.spec.tagging; import java.lang.annotation.*; import org.scalatest.TagAnnotation; @TagAnnotation @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.TYPE}) public @interface SlowTest {} @TagAnnotation @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.TYPE}) public @interface DbTest {}Given these annotations, you could tag
Spec
tests like this:
package org.scalatest.examples.spec.taggingThe
import org.scalatest.Spec
class SetSpec extends Spec {
object `A Set` { object `when empty` {
@SlowTest def `should have size 0` { assert(Set.empty.size === 0) }
@SlowTest @DbTest def `should produce NoSuchElementException when head is invoked` { intercept[NoSuchElementException] { Set.empty.head } } } } }
run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those with tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
with tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
A tag annotation also allows you to tag all the tests of a Spec
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.spec.getfixtureThe “
import org.scalatest.Spec import collection.mutable.ListBuffer
class ExampleSpec extends Spec {
def fixture = new { val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String] }
object `Testing ` { def `should be easy` { val f = fixture f.builder.append("easy!") assert(f.builder.toString === "ScalaTest is easy!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
def `should be fun` { val f = fixture f.builder.append("fun!") assert(f.builder.toString === "ScalaTest is fun!") assert(f.buffer.isEmpty) } } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.spec.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.Spec
class ExampleSpec extends Spec {
trait Builder { val builder = new StringBuilder("ScalaTest is ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is") }
object `Testing ` { // This test needs the StringBuilder fixture def `should be productive` { new Builder { builder.append("productive!") assert(builder.toString === "ScalaTest is productive!") } } }
object `Test code` { // This test needs the ListBuffer[String] fixture def `should be readable` { new Buffer { buffer += ("readable!") assert(buffer === List("ScalaTest", "is", "readable!")) } }
// This test needs both the StringBuilder and ListBuffer def `should be clear and concise` { new Builder with Buffer { builder.append("clear!") buffer += ("concise!") assert(builder.toString === "ScalaTest is clear!") assert(buffer === List("ScalaTest", "is", "concise!")) } } } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. In other words, instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
and send that information to the reporter:
package org.scalatest.examples.spec.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSpec extends Spec {
override def withFixture(test: NoArgTest) = {
super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
object `This test` { def `should succeed` { assert(1 + 1 === 2) }
def `should fail` { assert(1 + 1 === 3) } } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSuite execute
ExampleSuite:
This test
- should fail *** FAILED ***
2 did not equal 3 (:33)
+ Dir snapshot: hello.txt, world.txt
- should succeed
Note that the NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
package org.scalatest.examples.spec.loanfixtureAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
import java.util.concurrent.ConcurrentHashMap
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.Spec import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSpec extends Spec {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
object `Testing ` { // This test needs the file fixture def `should be productive` { withFile { (file, writer) => writer.write("productive!") writer.flush() assert(file.length === 24) } } }
object `Test code` { // This test needs the database fixture def `should be readable` { withDatabase { db => db.append("readable!") assert(db.toString === "ScalaTest is readable!") } }
// This test needs both the file and the database def `should be clear and concise` { withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("clear!") writer.write("concise!") writer.flush() assert(db.toString === "ScalaTest is clear!") assert(file.length === 21) } } } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.Spec
and overriding withFixture(OneArgTest)
.
Each test in a fixture.Spec
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. In other words, instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.spec.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSpec extends fixture.Spec {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = {
// create the fixture val file = File.createTempFile("hello", "world") val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
object `Testing ` { def `should be easy` { f: FixtureParam => f.writer.write("easy!") f.writer.flush() assert(f.file.length === 18) }
def `should be fun` { f: FixtureParam => f.writer.write("fun!") f.writer.flush() assert(f.file.length === 17) } } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.Spec
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.spec.beforeandafterNote that the only way
import org.scalatest.Spec import org.scalatest.BeforeAndAfter import collection.mutable.ListBuffer
class ExampleSpec extends Spec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
object `Testing ` { def `should be easy` { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
def `should be fun` { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.spec.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSpec extends Spec with Builder with Buffer {
object `Testing ` { def `should be easy` { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
def `should be fun` { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
Builder
and Buffer
traits, ExampleSpec
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Spec extends Spec with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Spec extends Spec with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.spec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import org.scalatest.BeforeAndAfterEach import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally buffer.clear() } }
class ExampleSpec extends Spec with Builder with Buffer {
object `Testing ` { def `should be easy` { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
def `should be fun` { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared tests ==
Because Spec
represents tests as methods, you cannot share or otherwise dynamically generate tests. Instead, use static code generation
if you want to generate tests in a Spec
. In other words, write a program that statically generates the entire source file of
a Spec
subclass.
Implementation trait for class Spec
, which facilitates a “behavior-driven” style of development (BDD), in which tests
are methods, optionally nested inside singleton objects defining textual scopes.
Implementation trait for class Spec
, which facilitates a “behavior-driven” style of development (BDD), in which tests
are methods, optionally nested inside singleton objects defining textual scopes.
Spec
is a class, not a trait, to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the behavior of Spec
into some other class, you can use this trait instead, because class Spec
does nothing more than extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed overview of Spec
.
Status implementation that can change its state over time.
Status implementation that can change its state over time.
A StatefulStatus
begins its life in a successful state, and will remain successful unless setFailed
is called.
Once setFailed
is called, the status will remain at failed. The setFailed
method can be called multiple times (even
though invoking it once is sufficient to permanently set the status to failed), but only up until setCompleted
has been called.
After setCompleted
has been called, any invocation of setFailed
will be greeted with an IllegalStateException
.
Instances of this class are thread safe.
The result status of running a test or a suite.
The result status of running a test or a suite.
This trait is the return type of the "run" lifecycle methods of trait Suite
: run
, runNestedSuites
,
runTests
, and runTest
. It can be used to determine whether a test or suite has completed, and if completed,
whether it succeeded or failed. The main use case for this trait in ScalaTest is to enable BeforeAndAfterAll
's afterAll
method to wait until all relevant tests and nested suites have completed before performing the "after all" code, even if those tests are
nested suites are run in parallel.
A Suite
class that takes zero to many Suite
s,
which will be returned from its nestedSuites
method and
executed in “stepwise” fashion by its runNestedSuites
method.
A Suite
class that takes zero to many Suite
s,
which will be returned from its nestedSuites
method and
executed in “stepwise” fashion by its runNestedSuites
method.
For example, you can define a suite that always executes a list of nested suites like this:
class StepsSuite extends Stepwise( new Step1Suite, new Step2Suite, new Step3Suite, new Step4Suite, new Step5Suite )
When StepsSuite
is executed, regardless of whether a Distributor
is passed, it will execute its
nested suites sequentially in the passed order: Step1Suite
, Step2Suite
,
Step3Suite
, Step4Suite
, and Step5Suite
.
The difference between Stepwise
and Sequential
is that although Stepwise
executes its own nested suites sequentially, it passes
whatever distributor was passed to it to those nested suites. Thus the nested suites could run their own nested
suites and tests in parallel if that distributor is defined. By contrast, Sequential
always
passes None
for the distributor to the nested suites, so any and every test and nested suite
contained within the nested suites passed to the Sequential
construtor will be executed sequentially.
if suitesToNest
, or any suite
it contains, is null
.
Trait that causes the nested suites of any suite it is mixed into to be run sequentially even if
a Distributor
is passed to runNestedSuites
.
Trait that causes the nested suites of any suite it is mixed into to be run sequentially even if
a Distributor
is passed to runNestedSuites
. This trait overrides the
runNestedSuites
method and fowards every parameter passed to it to a superclass invocation
of runNestedSuites
, except it always passes None
for the Distributor
.
Mix in this trait into any suite whose nested suites need to be run sequentially even with the rest of the
run is being executed concurrently.
Trait whose instances can accept a stop request and indicate whether a stop has already been requested.
Trait whose instances can accept a stop request and indicate whether a stop has already been requested.
This is passed in
to the run
method of Suite
, so that running suites of tests can be
requested to stop early.
A suite of tests.
A suite of tests. A Suite
instance encapsulates a conceptual
suite (i.e., a collection) of tests.
This trait provides an interface composed of "lifecycle methods" that allow suites of tests to be run.
Its implementation enables a default way of writing and executing tests. Subtraits and subclasses can
override Suite
's lifecycle methods to enable other ways of writing and executing tests.
Prior to ScalaTest 2.0.M4, trait Suite
served two purposes: 1) It served as the base
class of ScalaTest's family of style traits, and 2) It was itself a style trait in which tests are methods.
Although it will continue to serve its first purpose, it has been deprecated as a style trait. Pre-existing code
that used Suite
as a style trait to define tests as methods will continue to work during the
deprecation period, but will generate a deprecation warning. Please change all such uses of Suite
to use trait Spec
instead.
A Suite
can refer to a collection of other Suite
s,
which are called nested Suite
s. Those nested Suite
s can in turn have
their own nested Suite
s, and so on. Large test suites can be organized, therefore, as a tree of
nested Suite
s.
This trait's run
method, in addition to invoking its
test methods, invokes run
on each of its nested Suite
s.
A List
of a Suite
's nested Suite
s can be obtained by invoking its
nestedSuites
method. If you wish to create a Suite
that serves as a
container for nested Suite
s, whether or not it has test methods of its own, simply override nestedSuites
to return a List
of the nested Suite
s. Because this is a common use case, ScalaTest provides
a convenience Suites
class, which takes a variable number of nested Suite
s as constructor
parameters. Here's an example:
package org.scalatest.examples.suite.nestedIf you now run
import org.scalatest._
class ASuite extends FunSuite { test("A should have ASCII value 41 hex") { assert('A' === 0x41) } test("a should have ASCII value 61 hex") { assert('a' === 0x61) } } class BSuite extends FunSuite { test("B should have ASCII value 42 hex") { assert('B' === 0x42) } test("b should have ASCII value 62 hex") { assert('b' === 0x62) } } class CSuite extends FunSuite { test("C should have ASCII value 43 hex") { assert('C' === 0x43) } test("c should have ASCII value 63 hex") { assert('c' === 0x63) } }
class ASCIISuite extends Suites( new ASuite, new BSuite, new CSuite )
ASCIISuite
:
scala> new ASCIISuite executeYou will see reports printed to the standard output that indicate the nested suites—
ASuite
, BSuite
, and
CSuite
—were run:
ASCIISuite:
ASuite:
- A should have ASCII value 41 hex
- a should have ASCII value 61 hex
BSuite:
- B should have ASCII value 42 hex
- b should have ASCII value 62 hex
CSuite:
- C should have ASCII value 43 hex
- c should have ASCII value 63 hex
Note that Runner
can discover Suite
s automatically, so you need not
necessarily define nested Suites
explicitly. See the documentation
for Runner
for more information.
== The config map ==
In some cases you may need to pass information to a suite of tests.
For example, perhaps a suite of tests needs to grab information from a file, and you want
to be able to specify a different filename during different runs. You can accomplish this in ScalaTest by passing
the filename in a config map of key-value pairs, which is passed to run
as a ConfigMap
.
The values in the config map are called "config objects," because they can be used to configure
suites, reporters, and tests.
You can specify a string config object is via the ScalaTest Runner
, either via the command line
or ScalaTest's ant task.
(See the documentation for Runner for information on how to specify
config objects on the command line.)
The config map is passed to run
, runNestedSuites
, runTests
, and runTest
,
so one way to access it in your suite is to override one of those methods. If you need to use the config map inside your tests, you
can access it from the NoArgTest
passed to withFixture
, or the OneArgTest
passed to
withFixture
in the traits in the org.scalatest.fixture
package. (See the
documentation for fixture.Suite
for instructions on how to access the config map in tests.)
== Executing suites in parallel ==
The run
method takes as one of its parameters an optional Distributor
. If
a Distributor
is passed in, this trait's implementation of run
puts its nested
Suite
s into the distributor rather than executing them directly. The caller of run
is responsible for ensuring that some entity runs the Suite
s placed into the
distributor. The -P
command line parameter to Runner
, for example, will cause
Suite
s put into the Distributor
to be run in parallel via a pool of threads.
If you wish to execute the tests themselves in parallel, mix in ParallelTestExecution
.
== Treatment of java.lang.Error
s ==
The Javadoc documentation for java.lang.Error
states:
AnBecauseError
is a subclass ofThrowable
that indicates serious problems that a reasonable application should not try to catch. Most such errors are abnormal conditions.
Error
s are used to denote serious errors, trait Suite
and its subtypes in the ScalaTest API do not always treat a test
that completes abruptly with an Error
as a test failure, but sometimes as an indication that serious problems
have arisen that should cause the run to abort. For example, if a test completes abruptly with an OutOfMemoryError
,
it will not be reported as a test failure, but will instead cause the run to abort. Because not everyone uses Error
s only to represent serious
problems, however, ScalaTest only behaves this way for the following exception types (and their subclasses):
- java.lang.annotation.AnnotationFormatError
- java.awt.AWTError
- java.nio.charset.CoderMalfunctionError
- javax.xml.parsers.FactoryConfigurationError
- java.lang.LinkageError
- java.lang.ThreadDeath
- javax.xml.transform.TransformerFactoryConfigurationError
- java.lang.VirtualMachineError
The previous list includes all Error
s that exist as part of Java 1.5 API, excluding java.lang.AssertionError
. ScalaTest
does treat a thrown AssertionError
as an indication of a test failure. In addition, any other Error
that is not an instance of a
type mentioned in the previous list will be caught by the Suite
traits in the ScalaTest API and reported as the cause of a test failure.
Although trait Suite
and all its subtypes in the ScalaTest API consistently behave this way with regard to Error
s,
this behavior is not required by the contract of Suite
. Subclasses and subtraits that you define, for example, may treat all
Error
s as test failures, or indicate errors in some other way that has nothing to do with exceptions.
== Extensibility ==
Trait Suite
provides default implementations of its methods that should
be sufficient for most applications, but many methods can be overridden when desired. Here's
a summary of the methods that are intended to be overridden:
- run
- override this method to define custom ways to run suites of
tests.
- runNestedSuites
- override this method to define custom ways to run nested suites.
- runTests
- override this method to define custom ways to run a suite's tests.
- runTest
- override this method to define custom ways to run a single named test.
- testNames
- override this method to specify the Suite
's test names in a custom way.
- tags
- override this method to specify the Suite
's test tags in a custom way.
- nestedSuites
- override this method to specify the Suite
's nested Suite
s in a custom way.
- suiteName
- override this method to specify the Suite
's name in a custom way.
- expectedTestCount
- override this method to count this Suite
's expected tests in a custom way.
For example, this trait's implementation of testNames
performs reflection to discover methods starting with test
,
and places these in a Set
whose iterator returns the names in alphabetical order. If you wish to run tests in a different
order in a particular Suite
, perhaps because a test named testAlpha
can only succeed after a test named
testBeta
has run, you can override testNames
so that it returns a Set
whose iterator returns
testBeta
before testAlpha
. (This trait's implementation of run
will invoke tests
in the order they come out of the testNames
Set
iterator.)
Alternatively, you may not like starting your test methods with test
, and prefer using @Test
annotations in
the style of Java's JUnit 4 or TestNG. If so, you can override testNames
to discover tests using either of these two APIs
@Test
annotations, or one of your own invention. (This is in fact
how org.scalatest.junit.JUnitSuite
and org.scalatest.testng.TestNGSuite
work.)
Moreover, test in ScalaTest does not necessarily mean test method. A test can be anything that can be given a name,
that starts and either succeeds or fails, and can be ignored. In org.scalatest.FunSuite
, for example, tests are represented
as function values. This
approach might look foreign to JUnit users, but may feel more natural to programmers with a functional programming background.
To facilitate this style of writing tests, FunSuite
overrides testNames
, runTest
, and run
such that you can
define tests as function values.
You can also model existing JUnit 3, JUnit 4, or TestNG tests as suites of tests, thereby incorporating tests written in Java into a ScalaTest suite.
The "wrapper" classes in packages org.scalatest.junit
and org.scalatest.testng
exist to make this easy.
No matter what legacy tests you may have, it is likely you can create or use an existing Suite
subclass that allows you to model those tests
as ScalaTest suites and tests and incorporate them into a ScalaTest suite. You can then write new tests in Scala and continue supporting
older tests in Java.
Trait defining abstract "lifecycle" methods that are implemented in Suite
and can
be overridden in stackable modification traits.
Trait defining abstract "lifecycle" methods that are implemented in Suite
and can
be overridden in stackable modification traits.
The main purpose of SuiteMixin
is to differentiate core Suite
style traits, such as Spec
, FunSuite
, and FunSpec
from stackable
modification traits for Suite
s such as BeforeAndAfterEach
, OneInstancePerTest
,
and SequentialNestedSuiteExecution
. Because these stackable traits extend SuiteMixin
instead of Suite
, you can't define a suite by simply extending one of the stackable traits:
class MySuite extends BeforeAndAfterEach // Won't compile
Instead, you need to extend a core Suite
trait and mix the stackable BeforeAndAfterEach
trait
into that, like this:
class MySuite extends FunSuite with BeforeAndAfterEach // Compiles fine
A Suite
class that takes zero to many Suite
s in its constructor,
which will be returned from its nestedSuites
method.
A Suite
class that takes zero to many Suite
s in its constructor,
which will be returned from its nestedSuites
method.
For example, you can define a suite that always executes a list of nested suites like this:
class StepsSuite extends Suites( new Step1Suite, new Step2Suite, new Step3Suite, new Step4Suite, new Step5Suite )
If StepsSuite
is executed sequentially, it will execute its
nested suites in the passed order: Step1Suite
, Step2Suite
,
Step3Suite
, Step4Suite
, and Step5Suite
.
If StepsSuite
is executed in parallel, the nested suites will
be executed concurrently.
if suitesToNest
, or any suite
it contains, is null
.
Class whose subclasses can be used to tag tests in style traits in which tests are defined as functions.
Class whose subclasses can be used to tag tests in style traits in which tests are defined as functions.
ScalaTest has two ways to tag tests: annotations and instances of this Tag
class.
To tag a test method or an entire test class, you use a tag annotation, whereas to tag a test function,
you use a Tag
object. Though not required, it is usually a good idea to define both an annotation
and a corresponding Tag
object for each conceptual tag you want, so you can tag anything: test functions, test classes,
and test methods. The name of the conceptual tag is the fully qualified name of the annotation interface, so you must
pass this name to the Tag
constructor.
For example, imagine you want to tag integration tests that use the actual database, and are, therefore, generally slower. You could
create a tag annotation and object called DbTest
. To give them both the same simple name, you can declare them in different packages.
The tag annotation must be written in Java, not Scala, because annotations written
in Scala are not accessible at runtime. Here's an example:
package com.mycompany.myproject.testing.tags; import java.lang.annotation.*; import org.scalatest.TagAnnotation @TagAnnotation @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.TYPE}) public @interface DbTest {}
Given this annotation's fully qualified name is com.mycompany.myproject.testing.tags.DbTest
the corresponding Tag
object decaration must have that name passed to its constructor, like this:
package com.mycompany.myproject.testing.tagobjectsGiven these definitions, you could tag a test function as a
object DbTest extends Tag("com.mycompany.myproject.testing.tags.DbTest")
DbTest
in, for
example, a FlatSpec
like this:
import org.scalatest.FlatSpec import com.mycompany.myproject.testing.tagobjects.DbTestYou could tag a test method as a
class ExampleSpec extends FlatSpec {
"Integration tests" can "sometimes be slow" taggedAs(DbTest) in { Thread.sleep(1000) } }
DbTest
in, for
example, a Suite
like this:
import org.scalatest.Suite import com.mycompany.myproject.testing.tags.DbTestAnd you could tag all the tests in an entire test class by annotating the class, like this:
class ExampleSuite extends Suite {
@DbTest def `integration tests can sometimes be slow` { Thread.sleep(1000) } }
import org.scalatest.FlatSpec import com.mycompany.myproject.testing.tags.DbTestIn the previous example, both tests will be tagged as
@DBTest class ExampleSpec extends FlatSpec {
"Integration tests" can "sometimes be slow" in { Thread.sleep(1000) }
they should "likely sometimes be excluded " in { Thread.sleep(1000) } }
DBTest
s even though the
tests are not tagged as such individually.
When you run ScalaTest and want to either include or exclude DbTest
s, you'd give the fully qualified
name of the tag annotation (which is also the name passed to the corresponding Tag
constructor) to Runner
. For
example, here's how you'd exclude DbTest
s on the Runner
command line:
-l com.mycompany.myproject.testing.tags.DbTestFor examples of tagging in other style traits, see the "Tagging tests" section in the documentation for the trait: - Tagging
FeatureSpec
tests
- Tagging FlatSpec
tests
- Tagging FreeSpec
tests
- Tagging FunSpec
tests
- Tagging FunSuite
tests
- Tagging PropSpec
tests
- Tagging Spec
tests
- Tagging WordSpec
tests
Annotation used to annotate annotation interfaces that define tags for ScalaTest tests.
Annotation used to annotate annotation interfaces that define tags for ScalaTest tests.
Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible at runtime. It has been inserted into Scaladoc by pretending it is a trait.
ScalaTest will only consider annotations that are themselves annotated with TagAnnotation
as tag annotations, to avoid accidentally interpreting arbitrary annotations as tags. You use TagAnnotation
,
therefore, when you define a tag annotation (which you must do in Java). Here's an example:
package com.mycompany.myproject.testing.tags; import java.lang.annotation.*; import org.scalatest.TagAnnotation * @TagAnnotation @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.METHOD, ElementType.TYPE}) public @interface DbTest {}
For more information, see the documentation for class Tag
.
A bundle of information about the current test.
A bundle of information about the current test.
A TestData
object is passed to the withFixture
methods of traits Suite
and fixture.Suite
(both NoArgTest
and OneArgTest
extend TestData
) and to the beforeEach
and afterEach
methods of trait BeforeAndAfterEach
. This enables fixtures and tests to make use
of the test name and configuration objects in the config map.
In ScalaTest's event model, a test may be surrounded by “scopes.” Each test and scope is associated with string of text. A test's name is a concatenation of the text of any surrounding scopes followed by the text provided with the test itself, after each text element has been trimmed and one space inserted between each component. Here's an example:
package org.scalatest.examples.freespecThe above
import org.scalatest.FreeSpec
class SetSpec extends FreeSpec {
"A Set" - { "when empty" - { "should have size 0" in { assert(Set.empty.size === 0) }
"should produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
FreeSpec
contains two tests, both nested inside the same two scopes. The outermost scope names
the subject, A Set
. The nested scope qualifies the subject with when empty
. Inside that
scope are the two tests. The text of the tests are:
- should have size 0
- should produce NoSuchElementException when head is invoked
Therefore, the names of these two tests are:
- A Stack when empty should have size 0
- A Stack when empty should produce NoSuchElementException when head is invoked
The TestData
instance for the first test would contain:
- name
: "A Stack when empty should have size 0"
- scopes
: collection.immutable.IndexedSeq("A Stack", "when empty")
- text
: "should have size 0"
Trait for test registration support.
Class that tracks the progress of a series of Ordinal
s produced by invoking
next
and nextNewOldPair
on the current Ordinal
.
Class that tracks the progress of a series of Ordinal
s produced by invoking
next
and nextNewOldPair
on the current Ordinal
.
Instances of this class are thread safe. Multiple threads can invoke nextOrdinal
and nextTracker
concurrently. This facilitates multi-threaded tests that send
infoProvided
reports concurrently. When using a Dispatcher
to execute
suites in parallel, the intention is that each Tracker
will only be used by one
thread. For example, if the optional Dispatcher
passed to Suite
's implementation
of runNestedSuites is defined, that method will obtain a new Tracker
by invoking
nextTracker
for each nested suite it passes to the Dispatcher
.
Trait that provides an implicit conversion that adds success
and failure
methods
to scala.util.Try
, enabling you to make assertions about the value of a Success
or
the exception of a Failure
.
Trait that provides an implicit conversion that adds success
and failure
methods
to scala.util.Try
, enabling you to make assertions about the value of a Success
or
the exception of a Failure
.
The success
method will return the Try
on which it is invoked as a Success
if the Try
actually is a Success
, or throw TestFailedException
if not.
The failure
method will return the Try
on which it is invoked as a Failure
if the Try
actually is a Failure
, or throw TestFailedException
if not.
This construct allows you to express in one statement that an Try
should be either a Success
or a Failure
and that its value or exception, respectively,should meet some expectation. Here's an example:
try1.success.value should be > 9 try2.failure.exception should have message "/ by zero"
Or, using assertions instead of a matchers:
assert(try1.success.value > 9) assert(try2.failure.exception.getMessage == "/ by zero")
Were you to simply invoke get
on the Try
,
if the Try
wasn't a Success
, it would throw the exception contained in the Failure
:
val try2 = Try { 1 / 0 }The
try2.get should be < 9 // try2.get throws ArithmeticException
ArithmeticException
would cause the test to fail, but without providing a stack depth pointing
to the failing line of test code. This stack depth, provided by TestFailedException
(and a
few other ScalaTest exceptions), makes it quicker for
users to navigate to the cause of the failure. Without TryValues
, to get
a stack depth exception you would need to make two statements, like this:
try2 should be a 'success // throws TestFailedException try2.get should be < 9The
TryValues
trait allows you to state that more concisely:
try2.success.value should be < 9 // throws TestFailedException
Facilitates a “behavior-driven” style of development (BDD), in which tests are combined with text that specifies the behavior the tests verify.
Facilitates a “behavior-driven” style of development (BDD), in which tests are combined with text that specifies the behavior the tests verify.
Recommended Usage:
For teams coming from specs or specs2, WordSpec will feel familiar, and is often the most natural way to port specsN tests to
ScalaTest. WordSpec is very prescriptive in how text must be written, so a good fit for teams who want a high degree of discipline
enforced upon their specification text.
|
Class WordSpec
is so named because your specification text is structured by placing words after strings.
Here's an example WordSpec
:
package org.scalatest.examples.wordspecIn a
import org.scalatest.WordSpec
class SetSpec extends WordSpec {
"A Set" when { "empty" should { "have size 0" in { assert(Set.empty.size === 0) }
"produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
WordSpec
you write a one (or more) sentence specification for each bit of behavior you wish to
specify and test. Each specification sentence has a
"subject," which is sometimes called the system under test (or SUT). The
subject is entity being specified and tested and also serves as the subject of the sentences you write for each test. A subject
can be followed by one of three verbs, should
, must
, or can
, and a block. Here are some
examples:
"A Stack" should { // ... } "An Account" must { // ... } "A ShippingManifest" can { // ... }You can describe a subject in varying situations by using a
when
clause. A when
clause
follows the subject and precedes a block. In the block after the when
, you place strings that describe a situation or a state
the subject may be in using a string, each followed by a verb. Here's an example:
"A Stack" when { "empty" should { // ... } "non-empty" should { // ... } "full" should { // ... } }When you are ready to finish a sentence, you write a string followed by
in
and a block that
contains the code of the test. Here's an example:
import org.scalatest.WordSpecRunning the above
class StackSpec extends WordSpec { "A Stack" when { "empty" should { "be empty" in { // ... } "complain on peek" in { // ... } "complain on pop" in { // ... } } "full" should { "be full" in { // ... } "complain on push" in { // ... } } } }
StackSpec
in the interpreter would yield:
scala> new StackSpec execute
StackSpec:
A Stack
when empty
- should be empty
- should complain on peek
- should complain on pop
when full
- should be full
- should complain on push
Note that the output does not exactly match the input in an effort to maximize readability.
Although the WordSpec
code is nested, which can help you eliminate any repeated phrases
in the specification portion of your code, the output printed moves when
and should
down to the beginning of the next line.
Sometimes you may wish to eliminate repeated phrases inside the block following a verb
. Here's an example
in which the phrase "provide an and/or operator, which" is repeated:
import org.scalatest.WordSpecIn such situations you can place
class AndOrSpec extends WordSpec {
"The ScalaTest Matchers DSL" should { "provide an and operator, which returns silently when evaluating true and true" in {} "provide an and operator, which throws a TestFailedException when evaluating true and false" in {} "provide an and operator, which throws a TestFailedException when evaluating false and true" in {} "provide an and operator, which throws a TestFailedException when evaluating false and false" in {} "provide an or operator, which returns silently when evaluating true or true" in {} "provide an or operator, which returns silently when evaluating true or false" in {} "provide an or operator, which returns silently when evaluating false or true" in {} "provide an or operator, which throws a TestFailedException when evaluating false or false" in {} } }
which
clauses inside the verb clause, like this:
import org.scalatest.WordSpecRunning the above
class AndOrSpec extends WordSpec {
"The ScalaTest Matchers DSL" should { "provide an and operator," which { "returns silently when evaluating true and true" in {} "throws a TestFailedException when evaluating true and false" in {} "throws a TestFailedException when evaluating false and true" in {} "throws a TestFailedException when evaluating false and false" in {} } "provide an or operator," which { "returns silently when evaluating true or true" in {} "returns silently when evaluating true or false" in {} "returns silently when evaluating false or true" in {} "throws a TestFailedException when evaluating false or false" in {} } } }
AndOrSpec
in the interpreter would yield:
scala> new AndOrSpec execute
AndOrSpec:
The ScalaTest Matchers DSL
should provide an and operator, which
- returns silently when evaluating true and true
- throws a TestFailedException when evaluating true and false
- throws a TestFailedException when evaluating false and true
- throws a TestFailedException when evaluating false and false
should provide an or operator, which
- returns silently when evaluating true or true
- returns silently when evaluating true or false
- returns silently when evaluating false or true
- throws a TestFailedException when evaluating false or false
Note that unlike when
and should
/must
/can
, a which
appears
in the output right where you put it in the input, at the end of the line, to maximize readability.
If a word or phrase is repeated at the beginning of each string contained in a block, you can eliminate
that repetition by using an after word. An after word is a word or phrase that you can place
after when
, a verb, or
which
. For example, in the previous WordSpec
, the word "provide" is repeated
at the beginning of each string inside the should
block. You can factor out this duplication
like this:
import org.scalatest.WordSpecRunning the above version of
class AndOrSpec extends WordSpec {
def provide = afterWord("provide")
"The ScalaTest Matchers DSL" should provide { "an and operator," which { "returns silently when evaluating true and true" in {} "throws a TestFailedException when evaluating true and false" in {} "that throws a TestFailedException when evaluating false and true" in {} "throws a TestFailedException when evaluating false and false" in {} } "an or operator," which { "returns silently when evaluating true or true" in {} "returns silently when evaluating true or false" in {} "returns silently when evaluating false or true" in {} "throws a TestFailedException when evaluating false or false" in {} } } }
AndOrSpec
with the provide
after word in the interpreter would give you:
scala> new AndOrSpec execute
AndOrSpec:
The ScalaTest Matchers DSL
should provide
an and operator, which
- returns silently when evaluating true and true
- throws a TestFailedException when evaluating true and false
- that throws a TestFailedException when evaluating false and true
- throws a TestFailedException when evaluating false and false
an or operator, which
- returns silently when evaluating true or true
- returns silently when evaluating true or false
- returns silently when evaluating false or true
- throws a TestFailedException when evaluating false or false
Once you've defined an after word, you can place it after when
, a verb
(should
, must
, or can
), or
which
. (You can't place one after in
or is
, the
words that introduce a test.) Here's an example that has after words used in all three
places:
import org.scalatest.WordSpecRunning the previous
class ScalaTestGUISpec extends WordSpec {
def theUser = afterWord("the user") def display = afterWord("display") def is = afterWord("is")
"The ScalaTest GUI" when theUser { "clicks on an event report in the list box" should display { "a blue background in the clicked-on row in the list box" in {} "the details for the event in the details area" in {} "a rerun button," which is { "enabled if the clicked-on event is rerunnable" in {} "disabled if the clicked-on event is not rerunnable" in {} } } } }
WordSpec
in the Scala interpreter would yield:
scala> new ScalaTestGUISpec execute
ScalaTestGUISpec:
The ScalaTest GUI
when the user clicks on an event report in the list box
should display
- a blue background in the clicked-on row in the list box
- the details for the event in the details area
a rerun button, which is
- enabled if the clicked-on event is rerunnable
- disabled if the clicked-on event is not rerunnable
In case when you need to use different verb for a same subject, you can use it
or they
shorthand to avoid subject duplication:
"A Stack" when { // ... }A
it should { // ... }
WordSpec
's lifecycle has two phases: the registration phase and the
ready phase. It starts in registration phase and enters ready phase the first time
run
is called on it. It then remains in ready phase for the remainder of its lifetime.
Tests can only be registered while the WordSpec
is
in its registration phase. Any attempt to register a test after the WordSpec
has
entered its ready phase, i.e., after run
has been invoked on the WordSpec
,
will be met with a thrown TestRegistrationClosedException
. The recommended style
of using WordSpec
is to register tests during object construction as is done in all
the examples shown here. If you keep to the recommended style, you should never see a
TestRegistrationClosedException
.
Note: Class WordSpec
is in part inspired by class org.specs.Specification
, designed by
Eric Torreborre for the specs framework.
== Ignored tests ==
To support the common use case of temporarily disabling a test, with the
good intention of resurrecting the test at a later time, WordSpec
adds a method
ignore
to strings that can be used instead of in
to register a test. For example, to temporarily
disable the test with the name "A Stack should pop values in last-in-first-out order"
, just
change “in
” into “ignore
,” like this:
package org.scalatest.examples.wordspec.ignoreIf you run this version of
import org.scalatest.WordSpec
class SetSpec extends WordSpec {
"A Set" when { "empty" should { "have size 0" ignore { assert(Set.empty.size === 0) }
"produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
with:
scala> new SetSpec executeIt will run only the second test and report that the first test was ignored:
A Set when empty - should have size 0 !!! IGNORED !!! - should should produce NoSuchElementException when head is invokedIf you wish to temporarily ignore an entire suite of tests, you can annotate the test class with
@Ignore
, like this:
package org.scalatest.examples.wordspec.ignoreallWhen you mark a test class with a tag annotation, ScalaTest will mark each test defined in that class with that tag. Thus, marking the
import org.scalatest.WordSpec import org.scalatest.Ignore
@Ignore class SetSpec extends WordSpec {
"A Set" when { "empty" should { "have size 0" in { assert(Set.empty.size === 0) }
"produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
in the above example with the @Ignore
tag annotation means that both tests
in the class will be ignored. If you run the above SetSpec
in the Scala interpreter, you'll see:
scala> new SetSpec execute SetSpec: A Set when empty - should have size 0 !!! IGNORED !!! - should produce NoSuchElementException when head is invoked !!! IGNORED !!!Note that marking a test class as ignored won't prevent it from being discovered by ScalaTest. Ignored classes will be discovered and run, and all their tests will be reported as ignored. This is intended to keep the ignored class visible, to encourage the developers to eventually fix and “un-ignore” it. If you want to prevent a class from being discovered at all, use the
DoNotDiscover
annotation instead.
== Informers ==
One of the parameters to WordSpec
's run
method is a Reporter
, which
will collect and report information about the running suite of tests.
Information about suites and tests that were run, whether tests succeeded or failed,
and tests that were ignored will be passed to the Reporter
as the suite runs.
Most often the reporting done by default by WordSpec
's methods will be sufficient, but
occasionally you may wish to provide custom information to the Reporter
from a test.
For this purpose, an Informer
that will forward information to the current Reporter
is provided via the info
parameterless method.
You can pass the extra information to the Informer
via its apply
method.
The Informer
will then pass the information to the Reporter
via an InfoProvided
event.
One use case for the Informer
is to pass more information about a specification to the reporter. For example,
the GivenWhenThen
trait provides methods that use the implicit info
provided by WordSpec
to pass such information to the reporter. Here's an example:
package org.scalatest.examples.wordspec.infoIf you run this
import collection.mutable import org.scalatest._
class SetSpec extends WordSpec with GivenWhenThen {
"A mutable Set" should { "allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
info("That's all folks!") } } }
WordSpec
from the interpreter, you will see the following output:
scala> new SetSpec execute
A mutable Set
- should allow an element to be added
+ Given an empty mutable Set
+ When an element is added
+ Then the Set should have size 1
+ And the Set should contain the added element
+ That's all folks!
== Documenters ==
WordSpec
also provides a markup
method that returns a Documenter
, which allows you to send
to the Reporter
text formatted in Markdown syntax.
You can pass the extra information to the Documenter
via its apply
method.
The Documenter
will then pass the information to the Reporter
via an MarkupProvided
event.
Here's an example WordSpec
that uses markup
:
package org.scalatest.examples.wordspec.markupAlthough all of ScalaTest's built-in reporters will display the markup text in some form, the HTML reporter will format the markup information into HTML. Thus, the main purpose of
import collection.mutable import org.scalatest._
class SetSpec extends WordSpec with GivenWhenThen {
markup { """ Mutable Set ———-- A set is a collection that contains no duplicate elements. To implement a concrete mutable set, you need to provide implementations of the following methods: def contains(elem: A): Boolean def iterator: Iterator[A] def += (elem: A): this.type def -= (elem: A): this.type If you wish that methods like `take`, `drop`, `filter` return the same kind of set, you should also override: def empty: This It is also good idea to override methods `foreach` and `size` for efficiency. """ }
"A mutable Set" should { "allow an element to be added" in { Given("an empty mutable Set") val set = mutable.Set.empty[String]
When("an element is added") set += "clarity"
Then("the Set should have size 1") assert(set.size === 1)
And("the Set should contain the added element") assert(set.contains("clarity"))
markup("This test finished with a **bold** statement!") } } }
markup
is to
add nicely formatted text to HTML reports. Here's what the above SetSpec
would look like in the HTML reporter:
== Notifiers and alerters ==
ScalaTest records text passed to info
and markup
during tests, and sends the recorded text in the recordedEvents
field of
test completion events like TestSucceeded
and TestFailed
. This allows string reporters (like the standard out reporter) to show
info
and markup
text after the test name in a color determined by the outcome of the test. For example, if the test fails, string
reporters will show the info
and markup
text in red. If a test succeeds, string reporters will show the info
and markup
text in green. While this approach helps the readability of reports, it means that you can't use info
to get status
updates from long running tests.
To get immediate (i.e., non-recorded) notifications from tests, you can use note
(a Notifier
) and alert
(an Alerter
). Here's an example showing the differences:
package org.scalatest.examples.wordspec.noteBecause
import collection.mutable import org.scalatest._
class SetSpec extends WordSpec {
"A mutable Set" should { "allow an element to be added" in {
info("info is recorded") markup("markup is *also* recorded") note("notes are sent immediately") alert("alerts are also sent immediately")
val set = mutable.Set.empty[String] set += "clarity" assert(set.size === 1) assert(set.contains("clarity")) } } }
note
and alert
information is sent immediately, it will appear before the test name in string reporters, and its color will
be unrelated to the ultimate outcome of the test: note
text will always appear in green, alert
text will always appear in yellow.
Here's an example:
scala> new SetSpec execute SetSpec: A mutable Set + notes are sent immediately + alerts are also sent immediately - should allow an element to be added + info is recorded + markup is *also* recordedIn summary, use
info
and markup
for text that should form part of the specification output. Use
note
and alert
to send status notifications. (Because the HTML reporter is intended to produce a
readable, printable specification, info
and markup
text will appear in the HTML report, but
note
and alert
text will not.)
== Pending tests ==
A pending test is one that has been given a name but is not yet implemented. The purpose of
pending tests is to facilitate a style of testing in which documentation of behavior is sketched
out before tests are written to verify that behavior (and often, before the behavior of
the system being tested is itself implemented). Such sketches form a kind of specification of
what tests and functionality to implement later.
To support this style of testing, a test can be given a name that specifies one
bit of behavior required by the system being tested. The test can also include some code that
sends more information about the behavior to the reporter when the tests run. At the end of the test,
it can call method pending
, which will cause it to complete abruptly with TestPendingException
.
Because tests in ScalaTest can be designated as pending with TestPendingException
, both the test name and any information
sent to the reporter when running the test can appear in the report of a test run. (In other words,
the code of a pending test is executed just like any other test.) However, because the test completes abruptly
with TestPendingException
, the test will be reported as pending, to indicate
the actual test, and possibly the functionality it is intended to test, has not yet been implemented.
You can mark tests as pending in a WordSpec
like this:
package org.scalatest.examples.wordspec.pendingIf you run this version of
import org.scalatest._
class SetSpec extends WordSpec {
"A Set" when { "empty" should { "have size 0" in (pending)
"produce NoSuchElementException when head is invoked" in { intercept[NoSuchElementException] { Set.empty.head } } } } }
SetSpec
with:
scala> new SetSpec executeIt will run both tests but report that
should have size 0
is pending. You'll see:
A Set when empty - should have size 0 (pending) - should produce NoSuchElementException when head is invokedOne difference between an ignored test and a pending one is that an ignored test is intended to be used during a significant refactorings of the code under test, when tests break and you don't want to spend the time to fix all of them immediately. You can mark some of those broken tests as ignored temporarily, so that you can focus the red bar on just failing tests you actually want to fix immediately. Later you can go back and fix the ignored tests. In other words, by ignoring some failing tests temporarily, you can more easily notice failed tests that you actually want to fix. By contrast, a pending test is intended to be used before a test and/or the code under test is written. Pending indicates you've decided to write a test for a bit of behavior, but either you haven't written the test yet, or have only written part of it, or perhaps you've written the test but don't want to implement the behavior it tests until after you've implemented a different bit of behavior you realized you need first. Thus ignored tests are designed to facilitate refactoring of existing code whereas pending tests are designed to facilitate the creation of new code. One other difference between ignored and pending tests is that ignored tests are implemented as a test tag that is excluded by default. Thus an ignored test is never executed. By contrast, a pending test is implemented as a test that throws
TestPendingException
(which is what calling the pending
method does). Thus
the body of pending tests are executed up until they throw TestPendingException
. The reason for this difference
is that it enables your unfinished test to send InfoProvided
messages to the reporter before it completes
abruptly with TestPendingException
, as shown in the previous example on Informer
s
that used the GivenWhenThen
trait. For example, the following snippet in a WordSpec
:
"The Scala language" should { "add correctly" in { Given("two integers") When("they are added") Then("the result is the sum of the two numbers") pending } // ...Would yield the following output when run in the interpreter:
The Scala language - should add correctly (pending) + Given two integers + When they are added + Then the result is the sum of the two numbers== Tagging tests == A
WordSpec
's tests may be classified into groups by tagging them with string names.
As with any suite, when executing a WordSpec
, groups of tests can
optionally be included and/or excluded. To tag a WordSpec
's tests,
you pass objects that extend class org.scalatest.Tag
to methods
that register tests. Class Tag
takes one parameter, a string name. If you have
created tag annotation interfaces as described in the Tag
documentation, then you
will probably want to use tag names on your test functions that match. To do so, simply
pass the fully qualified names of the tag interfaces to the Tag
constructor. For example, if you've
defined tag annotation interfaces with fully qualified names, com.mycompany.tags.SlowTest
and
com.mycompany.tags.DbTest
, then you could
create matching tags for WordSpec
s like this:
package org.scalatest.examples.wordspec.taggingGiven these definitions, you could place
import org.scalatest.Tag
object SlowTest extends Tag("com.mycompany.tags.SlowTest") object DbTest extends Tag("com.mycompany.tags.DbTest")
WordSpec
tests into groups like this:
import org.scalatest.WordSpecThis code marks both tests with the
class SetSpec extends WordSpec {
"A Set" when { "empty" should { "have size 0" taggedAs(SlowTest) in { assert(Set.empty.size === 0) }
"produce NoSuchElementException when head is invoked" taggedAs(SlowTest, DbTest) in { intercept[NoSuchElementException] { Set.empty.head } } } } }
com.mycompany.tags.SlowTest
tag,
and the second test with the com.mycompany.tags.DbTest
tag.
The run
method takes a Filter
, whose constructor takes an optional
Set[String]
called tagsToInclude
and a Set[String]
called
tagsToExclude
. If tagsToInclude
is None
, all tests will be run
except those those belonging to tags listed in the
tagsToExclude
Set
. If tagsToInclude
is defined, only tests
belonging to tags mentioned in the tagsToInclude
set, and not mentioned in tagsToExclude
,
will be run.
It is recommended, though not required, that you create a corresponding tag annotation when you
create a Tag
object. A tag annotation allows you to tag all the tests of a WordSpec
in
one stroke by annotating the class. For more information and examples, see the
documentation for class Tag
.
== Shared fixtures ==
A test fixture is composed of the objects and other artifacts (files, sockets, database
connections, etc.) tests use to do their work.
When multiple tests need to work with the same fixtures, it is important to try and avoid
duplicating the fixture code across those tests. The more code duplication you have in your
tests, the greater drag the tests will have on refactoring the actual production code.
ScalaTest recommends three techniques to eliminate such code duplication:
- Refactor using Scala
- Override withFixture
- Mix in a before-and-after trait
Each technique is geared towards helping you reduce code duplication without introducing
instance var
s, shared mutable objects, or other dependencies between tests. Eliminating shared
mutable state across tests will make your test code easier to reason about and more amenable for parallel
test execution.
The following sections
describe these techniques, including explaining the recommended usage
for each. But first, here's a table summarizing the options:
Refactor using Scala when different tests need different fixtures. | |
get-fixture methods | The extract method refactor helps you create a fresh instances of mutable fixture objects in each test that needs them, but doesn't help you clean them up when you're done. |
fixture-context objects | By placing fixture methods and fields into traits, you can easily give each test just the newly created fixtures it needs by mixing together traits. Use this technique when you need different combinations of mutable fixture objects in different tests, and don't need to clean up after. |
loan-fixture methods | Factor out dupicate code with the loan pattern when different tests need different fixtures that must be cleaned up afterwards. |
Override withFixture when most or all tests need the same fixture.
|
|
withFixture(NoArgTest)
|
The recommended default approach when most or all tests need the same fixture treatment. This general technique
allows you, for example, to perform side effects at the beginning and end of all or most tests,
transform the outcome of tests, retry tests, make decisions based on test names, tags, or other test data.
Use this technique unless:
- Different tests need different fixtures (refactor using Scala instead)
- An exception in fixture code should abort the suite, not fail the test (use a before-and-after trait instead)
- You have objects to pass into tests (override withFixture(OneArgTest) instead)
|
withFixture(OneArgTest)
|
Use when you want to pass the same fixture object or objects as a parameter into all or most tests. |
Mix in a before-and-after trait when you want an aborted suite, not a failed test, if the fixture code fails. | |
BeforeAndAfter
|
Use this boilerplate-buster when you need to perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
BeforeAndAfterEach
|
Use when you want to stack traits that perform the same side-effects before and/or after tests, rather than at the beginning or end of tests. |
package org.scalatest.examples.wordspec.getfixtureThe “
import org.scalatest.WordSpec import collection.mutable.ListBuffer
class ExampleSpec extends WordSpec {
def fixture = new { val builder = new StringBuilder("ScalaTest is ") val buffer = new ListBuffer[String] }
"Testing" should { "be easy" in { val f = fixture f.builder.append("easy!") assert(f.builder.toString === "ScalaTest is easy!") assert(f.buffer.isEmpty) f.buffer += "sweet" }
"be fun" in { val f = fixture f.builder.append("fun!") assert(f.builder.toString === "ScalaTest is fun!") assert(f.buffer.isEmpty) } } }
f.
” in front of each use of a fixture object provides a visual indication of which objects
are part of the fixture, but if you prefer, you can import the the members with “import f._
” and use the names directly.
If you need to configure fixture objects differently in different tests, you can pass configuration into the get-fixture method. For example, you could pass
in an initial value for a mutable fixture object as a parameter to the get-fixture method.
==== Instantiating fixture-context objects ====
An alternate technique that is especially useful when different tests need different combinations of fixture objects is to define the fixture objects as instance variables
of fixture-context objects whose instantiation forms the body of tests. Like get-fixture methods, fixture-context objects are only
appropriate if you don't need to clean up the fixtures after using them.
To use this technique, you define instance variables intialized with fixture objects in traits and/or classes, then in each test instantiate an object that
contains just the fixture objects needed by the test. Traits allow you to mix together just the fixture objects needed by each test, whereas classes
allow you to pass data in via a constructor to configure the fixture objects. Here's an example in which fixture objects are partitioned into two traits
and each test just mixes together the traits it needs:
package org.scalatest.examples.wordspec.fixturecontext==== Overriding
import collection.mutable.ListBuffer import org.scalatest.WordSpec
class ExampleSpec extends WordSpec {
trait Builder { val builder = new StringBuilder("ScalaTest is ") }
trait Buffer { val buffer = ListBuffer("ScalaTest", "is") }
"Testing" should { // This test needs the StringBuilder fixture "be productive" in new Builder { builder.append("productive!") assert(builder.toString === "ScalaTest is productive!") } }
"Test code" should { // This test needs the ListBuffer[String] fixture "be readable" in new Buffer { buffer += ("readable!") assert(buffer === List("ScalaTest", "is", "readable!")) }
// This test needs both the StringBuilder and ListBuffer "be clear and concise" in new Builder with Buffer { builder.append("clear!") buffer += ("concise!") assert(builder.toString === "ScalaTest is clear!") assert(buffer === List("ScalaTest", "is", "concise!")) } } }
withFixture(NoArgTest)
====
Although the get-fixture method and fixture-context object approaches take care of setting up a fixture at the beginning of each
test, they don't address the problem of cleaning up a fixture at the end of the test. If you just need to perform a side-effect at the beginning or end of
a test, and don't need to actually pass any fixture objects into the test, you can override withFixture(NoArgTest)
, one of ScalaTest's
lifecycle methods defined in trait Suite
.
Trait Suite
's implementation of runTest
passes a no-arg test function to withFixture(NoArgTest)
. It is withFixture
's
responsibility to invoke that test function. Suite
's implementation of withFixture
simply
invokes the function, like this:
// Default implementation in trait Suite protected def withFixture(test: NoArgTest) = { test() }You can, therefore, override
withFixture
to perform setup before and/or cleanup after invoking the test function. If
you have cleanup to perform, you should invoke the test function inside a try
block and perform the cleanup in
a finally
clause, in case an exception propagates back through withFixture
. (If a test fails because of an exception,
the test function invoked by withFixture will result in a [[org.scalatest.Failed Failed
]] wrapping the exception. Nevertheless,
best practice is to perform cleanup in a finally clause just in case an exception occurs.)
The withFixture
method is designed to be stacked, and to enable this, you should always call the super
implementation
of withFixture
, and let it invoke the test function rather than invoking the test function directly. Instead of writing
“test()
”, you should write “super.withFixture(test)
”, like this:
// Your implementation override def withFixture(test: NoArgTest) = { // Perform setup try super.withFixture(test) // Invoke the test function finally { // Perform cleanup } }Here's an example in which
withFixture(NoArgTest)
is used to take a snapshot of the working directory if a test fails, and
send that information to the reporter:
package org.scalatest.examples.wordspec.noargtestRunning this version of
import java.io.File import org.scalatest._
class ExampleSpec extends WordSpec {
override def withFixture(test: NoArgTest) = {
super.withFixture(test) match { case failed: Failed => val currDir = new File(".") val fileNames = currDir.list() info("Dir snapshot: " + fileNames.mkString(", ")) failed case other => other } }
"This test" should { "succeed" in { assert(1 + 1 === 2) }
"fail" in { assert(1 + 1 === 3) } } }
ExampleSuite
in the interpreter in a directory with two files, hello.txt
and world.txt
would give the following output:
scala> new ExampleSuite execute
ExampleSuite:
This test
- should succeed
- should fail *** FAILED ***
2 did not equal 3 (:33)
+ Dir snapshot: hello.txt, world.txt
Note that the NoArgTest
passed to withFixture
, in addition to
an apply
method that executes the test, also includes the test name and the config
map passed to runTest
. Thus you can also use the test name and configuration objects in your withFixture
implementation.
==== Calling loan-fixture methods ====
If you need to both pass a fixture object into a test and perform cleanup at the end of the test, you'll need to use the loan pattern.
If different tests need different fixtures that require cleanup, you can implement the loan pattern directly by writing loan-fixture methods.
A loan-fixture method takes a function whose body forms part or all of a test's code. It creates a fixture, passes it to the test code by invoking the
function, then cleans up the fixture after the function returns.
The following example shows three tests that use two fixtures, a database and a file. Both require cleanup after, so each is provided via a
loan-fixture method. (In this example, the database is simulated with a StringBuffer
.)
import java.util.concurrent.ConcurrentHashMapAs demonstrated by the last test, loan-fixture methods compose. Not only do loan-fixture methods allow you to give each test the fixture it needs, they allow you to give a test multiple fixtures and clean everything up afterwards. Also demonstrated in this example is the technique of giving each test its own "fixture sandbox" to play in. When your fixtures involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is done in this example. This keeps tests completely isolated, allowing you to run them in parallel if desired. ==== Overriding
object DbServer { // Simulating a database server type Db = StringBuffer private val databases = new ConcurrentHashMap[String, Db] def createDb(name: String): Db = { val db = new StringBuffer databases.put(name, db) db } def removeDb(name: String) { databases.remove(name) } }
import org.scalatest.WordSpec import DbServer._ import java.util.UUID.randomUUID import java.io._
class ExampleSpec extends WordSpec {
def withDatabase(testCode: Db => Any) { val dbName = randomUUID.toString val db = createDb(dbName) // create the fixture try { db.append("ScalaTest is ") // perform setup testCode(db) // "loan" the fixture to the test } finally removeDb(dbName) // clean up the fixture }
def withFile(testCode: (File, FileWriter) => Any) { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) try { writer.write("ScalaTest is ") // set up the fixture testCode(file, writer) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
"Testing" should { // This test needs the file fixture "be productive" in withFile { (file, writer) => writer.write("productive!") writer.flush() assert(file.length === 24) } }
"Test code" should { // This test needs the database fixture "be readable" in withDatabase { db => db.append("readable!") assert(db.toString === "ScalaTest is readable!") }
// This test needs both the file and the database "be clear and concise" in withDatabase { db => withFile { (file, writer) => // loan-fixture methods compose db.append("clear!") writer.write("concise!") writer.flush() assert(db.toString === "ScalaTest is clear!") assert(file.length === 21) } } } }
withFixture(OneArgTest)
====
If all or most tests need the same fixture, you can avoid some of the boilerplate of the loan-fixture method approach by using a fixture.WordSpec
and overriding withFixture(OneArgTest)
.
Each test in a fixture.WordSpec
takes a fixture as a parameter, allowing you to pass the fixture into
the test. You must indicate the type of the fixture parameter by specifying FixtureParam
, and implement a
withFixture
method that takes a OneArgTest
. This withFixture
method is responsible for
invoking the one-arg test function, so you can perform fixture set up before, and clean up after, invoking and passing
the fixture into the test function.
To enable the stacking of traits that define withFixture(NoArgTest)
, it is a good idea to let
withFixture(NoArgTest)
invoke the test function instead of invoking the test
function directly. To do so, you'll need to convert the OneArgTest
to a NoArgTest
. You can do that by passing
the fixture object to the toNoArgTest
method of OneArgTest
. Instead of
writing “test(theFixture)
”, you'd delegate responsibility for
invoking the test function to the withFixture(NoArgTest)
method of the same instance by writing:
withFixture(test.toNoArgTest(theFixture))Here's a complete example:
package org.scalatest.examples.wordspec.oneargtestIn this example, the tests actually required two fixture objects, a
import org.scalatest.fixture import java.io._
class ExampleSpec extends fixture.WordSpec {
case class FixtureParam(file: File, writer: FileWriter)
def withFixture(test: OneArgTest) = { val file = File.createTempFile("hello", "world") // create the fixture val writer = new FileWriter(file) val theFixture = FixtureParam(file, writer)
try { writer.write("ScalaTest is ") // set up the fixture withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test } finally writer.close() // clean up the fixture }
"Testing" should { "be easy" in { f => f.writer.write("easy!") f.writer.flush() assert(f.file.length === 18) }
"be fun" in { f => f.writer.write("fun!") f.writer.flush() assert(f.file.length === 17) } } }
File
and a FileWriter
. In such situations you can
simply define the FixtureParam
type to be a tuple containing the objects, or as is done in this example, a case class containing
the objects. For more information on the withFixture(OneArgTest)
technique, see the documentation for fixture.WordSpec
.
==== Mixing in BeforeAndAfter
====
In all the shared fixture examples shown so far, the activities of creating, setting up, and cleaning up the fixture objects have been
performed during the test. This means that if an exception occurs during any of these activities, it will be reported as a test failure.
Sometimes, however, you may want setup to happen before the test starts, and cleanup after the test has completed, so that if an
exception occurs during setup or cleanup, the entire suite aborts and no more tests are attempted. The simplest way to accomplish this in ScalaTest is
to mix in trait BeforeAndAfter
. With this trait you can denote a bit of code to run before each test
with before
and/or after each test each test with after
, like this:
package org.scalatest.examples.wordspec.beforeandafterNote that the only way
import org.scalatest.WordSpec import org.scalatest.BeforeAndAfter import collection.mutable.ListBuffer
class ExampleSpec extends WordSpec with BeforeAndAfter {
val builder = new StringBuilder val buffer = new ListBuffer[String]
before { builder.append("ScalaTest is ") }
after { builder.clear() buffer.clear() }
"Testing" should { "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
"be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) } } }
before
and after
code can communicate with test code is via some side-effecting mechanism, commonly by
reassigning instance var
s or by changing the state of mutable objects held from instance val
s (as in this example). If using
instance var
s or mutable objects held from instance val
s you wouldn't be able to run tests in parallel in the same instance
of the test class unless you synchronized access to the shared, mutable state. This is why ScalaTest's ParallelTestExecution
trait extends
OneInstancePerTest
. By running each test in its own instance of the class, each test has its own copy of the instance variables, so you
don't need to synchronize. If you mixed ParallelTestExecution
into the ExampleSuite
above, the tests would run in parallel just fine
without any synchronization needed on the mutable StringBuilder
and ListBuffer[String]
objects.
Although BeforeAndAfter
provides a minimal-boilerplate way to execute code before and after tests, it isn't designed to enable stackable
traits, because the order of execution would be non-obvious. If you want to factor out before and after code that is common to multiple test suites, you
should use trait BeforeAndAfterEach
instead, as shown later in the next section,
composing fixtures by stacking traits.
== Composing fixtures by stacking traits ==
In larger projects, teams often end up with several different fixtures that test classes need in different combinations,
and possibly initialized (and cleaned up) in different orders. A good way to accomplish this in ScalaTest is to factor the individual
fixtures into traits that can be composed using the stackable trait pattern. This can be done, for example, by placing
withFixture
methods in several traits, each of which call super.withFixture
. Here's an example in
which the StringBuilder
and ListBuffer[String]
fixtures used in the previous examples have been
factored out into two stackable fixture traits named Builder
and Buffer
:
package org.scalatest.examples.wordspec.composingwithfixtureBy mixing in both the
import org.scalatest._ import collection.mutable.ListBuffer
trait Builder extends SuiteMixin { this: Suite =>
val builder = new StringBuilder
abstract override def withFixture(test: NoArgTest) = { builder.append("ScalaTest is ") try super.withFixture(test) // To be stackable, must call super.withFixture finally builder.clear() } }
trait Buffer extends SuiteMixin { this: Suite =>
val buffer = new ListBuffer[String]
abstract override def withFixture(test: NoArgTest) = { try super.withFixture(test) // To be stackable, must call super.withFixture finally buffer.clear() } }
class ExampleSpec extends WordSpec with Builder with Buffer {
"Testing" should { "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
"be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
Builder
and Buffer
traits, ExampleSpec
gets both fixtures, which will be
initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution.
In this case, Builder
is “super” to Buffer
. If you wanted Buffer
to be “super”
to Builder
, you need only switch the order you mix them together, like this:
class Example2Suite extends Suite with Buffer with BuilderAnd if you only need one fixture you mix in only that trait:
class Example3Suite extends Suite with BuilderAnother way to create stackable fixture traits is by extending the
BeforeAndAfterEach
and/or BeforeAndAfterAll
traits.
BeforeAndAfterEach
has a beforeEach
method that will be run before each test (like JUnit's setUp
),
and an afterEach
method that will be run after (like JUnit's tearDown
).
Similarly, BeforeAndAfterAll
has a beforeAll
method that will be run before all tests,
and an afterAll
method that will be run after all tests. Here's what the previously shown example would look like if it
were rewritten to use the BeforeAndAfterEach
methods instead of withFixture
:
package org.scalatest.examples.wordspec.composingbeforeandaftereachTo get the same ordering as
import org.scalatest._ import org.scalatest.BeforeAndAfterEach import collection.mutable.ListBuffer
trait Builder extends BeforeAndAfterEach { this: Suite =>
val builder = new StringBuilder
override def beforeEach() { builder.append("ScalaTest is ") super.beforeEach() // To be stackable, must call super.beforeEach }
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally builder.clear() } }
trait Buffer extends BeforeAndAfterEach { this: Suite =>
val buffer = new ListBuffer[String]
override def afterEach() { try super.afterEach() // To be stackable, must call super.afterEach finally buffer.clear() } }
class ExampleSpec extends WordSpec with Builder with Buffer {
"Testing" should { "be easy" in { builder.append("easy!") assert(builder.toString === "ScalaTest is easy!") assert(buffer.isEmpty) buffer += "sweet" }
"be fun" in { builder.append("fun!") assert(builder.toString === "ScalaTest is fun!") assert(buffer.isEmpty) buffer += "clear" } } }
withFixture
, place your super.beforeEach
call at the end of each
beforeEach
method, and the super.afterEach
call at the beginning of each afterEach
method, as shown in the previous example. It is a good idea to invoke super.afterEach
in a try
block and perform cleanup in a finally
clause, as shown in the previous example, because this ensures the
cleanup code is performed even if super.afterEach
throws an exception.
The difference between stacking traits that extend BeforeAndAfterEach
versus traits that implement withFixture
is
that setup and cleanup code happens before and after the test in BeforeAndAfterEach
, but at the beginning and
end of the test in withFixture
. Thus if a withFixture
method completes abruptly with an exception, it is
considered a failed test. By contrast, if any of the beforeEach
or afterEach
methods of BeforeAndAfterEach
complete abruptly, it is considered an aborted suite, which will result in a SuiteAborted
event.
== Shared tests ==
Sometimes you may want to run the same test code on different fixture objects. In other words, you may want to write tests that are "shared"
by different fixture objects. To accomplish this in a WordSpec
, you first place shared tests in behavior functions.
These behavior functions will be invoked during the construction phase of any WordSpec
that uses them, so that the tests they
contain will be registered as tests in that WordSpec
. For example, given this stack class:
import scala.collection.mutable.ListBufferYou may want to test the
class Stack[T] {
val MAX = 10 private val buf = new ListBuffer[T]
def push(o: T) { if (!full) buf.prepend(o) else throw new IllegalStateException("can't push onto a full stack") }
def pop(): T = { if (!empty) buf.remove(0) else throw new IllegalStateException("can't pop an empty stack") }
def peek: T = { if (!empty) buf(0) else throw new IllegalStateException("can't pop an empty stack") }
def full: Boolean = buf.size == MAX def empty: Boolean = buf.size == 0 def size = buf.size
override def toString = buf.mkString("Stack(", ", ", ")") }
Stack
class in different states: empty, full, with one item, with one item less than capacity,
etc. You may find you have several tests that make sense any time the stack is non-empty. Thus you'd ideally want to run
those same tests for three stack fixture objects: a full stack, a stack with a one item, and a stack with one item less than
capacity. With shared tests, you can factor these tests out into a behavior function, into which you pass the
stack fixture to use when running the tests. So in your WordSpec
for stack, you'd invoke the
behavior function three times, passing in each of the three stack fixtures so that the shared tests are run for all three fixtures. You
can define a behavior function that encapsulates these shared tests inside the WordSpec
that uses them. If they are shared
between different WordSpec
s, however, you could also define them in a separate trait that is mixed into each WordSpec
that uses them.
For example, here the nonEmptyStack
behavior function (in this case, a behavior method) is
defined in a trait along with another method containing shared tests for non-full stacks:
trait StackBehaviors { this: WordSpec =>Given these behavior functions, you could invoke them directly, but
def nonEmptyStack(newStack: => Stack[Int], lastItemAdded: Int) {
"be non-empty" in { assert(!newStack.empty) }
"return the top item on peek" in { assert(newStack.peek === lastItemAdded) }
"not remove the top item on peek" in { val stack = newStack val size = stack.size assert(stack.peek === lastItemAdded) assert(stack.size === size) }
"remove the top item on pop" in { val stack = newStack val size = stack.size assert(stack.pop === lastItemAdded) assert(stack.size === size - 1) } }
def nonFullStack(newStack: => Stack[Int]) {
"not be full" in { assert(!newStack.full) }
"add to the top on push" in { val stack = newStack val size = stack.size stack.push(7) assert(stack.size === size + 1) assert(stack.peek === 7) } } }
WordSpec
offers a DSL for the purpose,
which looks like this:
behave like nonEmptyStack(stackWithOneItem, lastValuePushed) behave like nonFullStack(stackWithOneItem)If you prefer to use an imperative style to change fixtures, for example by mixing in
BeforeAndAfterEach
and
reassigning a stack
var
in beforeEach
, you could write your behavior functions
in the context of that var
, which means you wouldn't need to pass in the stack fixture because it would be
in scope already inside the behavior function. In that case, your code would look like this:
behave like nonEmptyStack // assuming lastValuePushed is also in scope inside nonEmptyStack
behave like nonFullStack
The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example:
class SharedTestExampleSpec extends WordSpec with StackBehaviors {If you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, you'll see:
// Stack fixture creation methods def emptyStack = new Stack[Int]
def fullStack = { val stack = new Stack[Int] for (i <- 0 until stack.MAX) stack.push(i) stack }
def stackWithOneItem = { val stack = new Stack[Int] stack.push(9) stack }
def stackWithOneItemLessThanCapacity = { val stack = new Stack[Int] for (i <- 1 to 9) stack.push(i) stack }
val lastValuePushed = 9
"A Stack" when { "empty" should { "be empty" in { assert(emptyStack.empty) }
"complain on peek" in { intercept[IllegalStateException] { emptyStack.peek } }
"complain on pop" in { intercept[IllegalStateException] { emptyStack.pop } } }
"it contains one item" should { behave like nonEmptyStack(stackWithOneItem, lastValuePushed) behave like nonFullStack(stackWithOneItem) }
"it contains one item less than capacity" should { behave like nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed) behave like nonFullStack(stackWithOneItemLessThanCapacity) }
"full" should { "be full" in { assert(fullStack.full) }
behave like nonEmptyStack(fullStack, lastValuePushed)
"complain on a push" in { intercept[IllegalStateException] { fullStack.push(10) } } } } }
scala> new SharedTestExampleSpec execute
SharedTestExampleSpec:
A Stack
when empty
- should be empty
- should complain on peek
- should complain on pop
when it contains one item
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should not be full
- should add to the top on push
when it contains one item less than capacity
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should not be full
- should add to the top on push
when full
- should be full
- should be non-empty
- should return the top item on peek
- should not remove the top item on peek
- should remove the top item on pop
- should complain on a push
One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name.
If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime
complaining that multiple tests are being registered with the same test name. A good way to solve this problem in a WordSpec
is to make sure
each invocation of a behavior function is in the context of a different surrounding when
,
should
/must
/can
, or which
clause, because a test's name is the concatenation of its
surrounding clauses and after words, followed by the "spec text".
For example, the following code in a WordSpec
would register a test with the name "A Stack when empty should be empty"
:
"A Stack" when { "empty" should { "be empty" in { assert(emptyStack.empty) } } } // ...If the
"be empty"
test was factored out into a behavior function, it could be called repeatedly so long
as each invocation of the behavior function is in the context of a different surrounding when
clauses.
Implementation trait for class WordSpec
, which facilitates a “behavior-driven” style of development (BDD), in which tests
are combined with text that specifies the behavior the tests verify.
Implementation trait for class WordSpec
, which facilitates a “behavior-driven” style of development (BDD), in which tests
are combined with text that specifies the behavior the tests verify.
WordSpec
is a class, not a trait, to minimize compile time given there is a slight compiler overhead to
mixing in traits compared to extending classes. If you need to mix the behavior of WordSpec
into some other class, you can use this trait instead, because class WordSpec
does nothing more than extend this trait and add a nice toString
implementation.
See the documentation of the class for a detailed overview of WordSpec
.
Annotation to associate a wrapper suite with a non-Suite
class, so it can be run via ScalaTest.
Annotation to associate a wrapper suite with a non-Suite
class, so it can be run via ScalaTest.
Note: This is actually an annotation defined in Java, not a Scala trait. It must be defined in Java instead of Scala so it will be accessible at runtime. It has been inserted into Scaladoc by pretending it is a trait.
A class will be considered annotated with WrapWith
if it is annotated directly or one of its superclasses (but
not supertraits) are annotated with WrapWith
.
The wrapper suite must have a public, one-arg constructor that takes a Class
instance whose type parameter
is compatible with the class to wrap: i.e., the class being annotated with WrapWith
.
ScalaTest will load the class to wrap and construct a new instance of the wrapper suite, passing in the Class
instance for the class to wrap.
Here's an example:
import org.scalacheck.Properties @WrapWith(classOf[ScalaCheckPropertiesSpec]) class StringSpecification extends Properties("String") { // ... }
The ScalaCheckPropertiesSpec
would need to have a public, no-arg constructor that accepts subclasses of org.scalacheck.Properties
:
import org.scalacheck.Properties import org.scalatest.Suite class ScalaCheckPropertiesSpec(clazz: Class[_ <: Properties]) extends Suite { // ... }
AbstractSuite
has been deprecated and will be removed in a future version of ScalaTest. Please change occurances of
AbstractSuite
where serving as a base class for stackable traits to SuiteMixin
. This
is just a name change for stackable traits extending AbstractSuite
. If AbstractSuite
was
being used in any other way, change AbstractSuite
to Suite
.
AbstractSuite
has been deprecated and will be removed in a future version of ScalaTest. Please change occurances of
AbstractSuite
where serving as a base class for stackable traits to SuiteMixin
. This
is just a name change for stackable traits extending AbstractSuite
. If AbstractSuite
was
being used in any other way, change AbstractSuite
to Suite
.
The main change will be to change stackable traits defined like this:
import org.scalatest._ import concurrent.Eventually._Instead of extending
trait RetriedTests extends AbstractSuite { Suite => abstract override def withFixture(test: NoArgTest) = { eventually { super.withFixture(test) } } }
AbstractSuite
, extend SuiteMixin
instead:
import org.scalatest._ import concurrent.Eventually._
trait RetriedTests extends SuiteMixin { Suite => abstract override def withFixture(test: NoArgTest) = { eventually { super.withFixture(test) } } }
Please use SuiteMixin or Suite instead. For more info, see the Scaladoc for AbstractSuite.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.DuplicateTestNameException
to org.scalatest.exceptions.DuplicateTestNameException
.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.DuplicateTestNameException
to org.scalatest.exceptions.DuplicateTestNameException
.
Please use org.scalatest.exceptions.DuplicateTestNameException instead.
Trait FailureOf
has been deprecated and will be removed in a future version of ScalaTest.
Instead of the failureOf
method provided by this trait, please use the outcomeOf
method
provided by trait OutcomeOf
instead.
Trait FailureOf
has been deprecated and will be removed in a future version of ScalaTest.
Instead of the failureOf
method provided by this trait, please use the outcomeOf
method
provided by trait OutcomeOf
instead.
The outcomeOf
method is not just the failureOf
method with the name changed, so you will likely
need to do a bit of rewriting of your usage of failureOf
. The difference is that failureOf
returned an optional Throwable
, whereas outcomeOf
returns an Outcome
.
The FailureOf trait has been deprecated. Please use trait OutcomeOf instead.
This trait has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.ModifiableMessageXXX
to org.scalatest.exceptions.ModifiableMessageXXX
.
This trait has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.ModifiableMessageXXX
to org.scalatest.exceptions.ModifiableMessageXXX
.
Please use org.scalatest.exceptions.ModifiableMessageXXX instead.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.NotAllowedException
to org.scalatest.exceptions.NotAllowedException
.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.NotAllowedException
to org.scalatest.exceptions.NotAllowedException
.
Please use org.scalatest.exceptions.NotAllowedException instead.
Trait whose instances can rerun tests or other entities (such as suites).
Trait whose instances can rerun tests or other entities (such as suites). An object extending
this trait can be passed to a Reporter
as part of a Report
. The
test or other entity about which the report is made can then be rerun by invoking the
rerun
method on the Rerunnable
.
We are considering removing Rerunner in ScalaTest 2.0 and would like to know if anyone is using it. If you are, please email scalatest-users@googlegroups.com or and describe your use case. Thanks!
Class Specs
has been deprecated and will be removed in a future version of ScalaTest. Please
change all uses of Specs
to Suites
instead.
Class Specs
has been deprecated and will be removed in a future version of ScalaTest. Please
change all uses of Specs
to Suites
instead.
Specs has been deprecated and will be removed in a future version of ScalaTest. Please use Suites instead.
This trait has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.StackDepth
to org.scalatest.exceptions.StackDepth
.
This trait has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.StackDepth
to org.scalatest.exceptions.StackDepth
.
Please use org.scalatest.exceptions.StackDepth instead.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.StackDepthException
to org.scalatest.exceptions.StackDepthException
.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.StackDepthException
to org.scalatest.exceptions.StackDepthException
.
Please use org.scalatest.exceptions.StackDepthException instead.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.TestFailedException
to org.scalatest.exceptions.TestFailedException
.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.TestFailedException
to org.scalatest.exceptions.TestFailedException
.
Please use org.scalatest.exceptions.TestFailedException instead.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.TestPendingException
to org.scalatest.exceptions.TestPendingException
.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.TestPendingException
to org.scalatest.exceptions.TestPendingException
.
Please use org.scalatest.exceptions.TestPendingException instead.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.TestRegistrationClosedException
to org.scalatest.exceptions.TestRegistrationClosedException
.
This class has been moved to the org.scalatest.exceptions
package. The deprecated type alias that has been left in its place will
be removed in a future version of ScalaTest. Please change any uses of org.scalatest.TestRegistrationClosedException
to org.scalatest.exceptions.TestRegistrationClosedException
.
Please use org.scalatest.exceptions.TestRegistrationClosedException instead.
Please use org.scalactic.TimesOnInt instead
Companion object that facilitates the importing of AppendedClues
members as
an alternative to mixing it in.
Companion object that facilitates the importing of AppendedClues
members as
an alternative to mixing it in. One use case is to import AppendedClues
members so you can use them in the Scala interpreter.
Companion object that facilitates the importing of Assertions
members as
an alternative to mixing it in.
Companion object that facilitates the importing of Assertions
members as
an alternative to mixing it in. One use case is to import Assertions
members so you can use
them in the Scala interpreter:
$scala -classpath scalatest.jar Welcome to Scala version 2.7.3.final (Java HotSpot(TM) Client VM, Java 1.5.0_16). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest.Assertions._ import org.scalatest.Assertions._ scala> assert(1 === 2) org.scalatest.TestFailedException: 1 did not equal 2 at org.scalatest.Assertions$class.assert(Assertions.scala:211) at org.scalatest.Assertions$.assert(Assertions.scala:511) at .<init>(<console>:7) at .<clinit>(<console>) at RequestResult$.<init>(<console>:3) at RequestResult$.<clinit>(<console>) at RequestResult$result(<console>) at sun.reflect.NativeMethodAccessorImpl.invoke... scala> assertResult(3) { 1 + 3 } org.scalatest.TestFailedException: Expected 3, but got 4 at org.scalatest.Assertions$class.expect(Assertions.scala:447) at org.scalatest.Assertions$.expect(Assertions.scala:511) at .<init>(<console>:7) at .<clinit>(<console>) at RequestResult$.<init>(<console>:3) at RequestResult$.<clinit>(<console>) at RequestResult$result(<console>) at sun.reflect.NativeMethodAccessorImpl.in... scala> val caught = intercept[StringIndexOutOfBoundsException] { "hi".charAt(-1) } caught: StringIndexOutOfBoundsException = java.lang.StringIndexOutOfBoundsException: String index out of range: -1
Companion object to class Canceled
that provides, in addition to the extractor and factory method
provided by the compiler given its companion is a case class, a second factory method
that produces a Canceled
outcome given a string message.
Companion object to class Canceled
that provides, in addition to the extractor and factory method
provided by the compiler given its companion is a case class, a second factory method
that produces a Canceled
outcome given a string message.
Companion object that facilitates the importing the members of trait Checkpoints
as
an alternative to mixing it in.
Companion object that facilitates the importing the members of trait Checkpoints
as
an alternative to mixing it in. One use case is to import Checkpoints
so you can use
it in the Scala interpreter.
Companion object to class ConfigMap
containing factory methods.
Companion object to class ConfigMap
containing factory methods.
Companion object that facilitates the importing of DiagrammedAssertions
members as
an alternative to mixing it in.
Companion object that facilitates the importing of DiagrammedAssertions
members as
an alternative to mixing it in. One use case is to import DiagrammedAssertions
members so you can use
them in the Scala interpreter:
$scala -classpath scalatest.jar Welcome to Scala version 2.10.4.final (Java HotSpot(TM) Client VM, Java 1.6.0_45). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest.Assertions._ import org.scalatest.Assertions._ scala> assert(1 === 2) org.scalatest.exceptions.TestFailedException: assert(1 === 2) | | | 1 | 2 false at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:422) at org.scalatest.DiagrammedAssertions$.newAssertionFailedException(DiagrammedAssertions.scala:249) at org.scalatest.DiagrammedAssertions$DiagrammedAssertionsHelper.macroAssert(DiagrammedAssertions.scala:111) at .<init>(<console>:20) at .<clinit>(<console>) at .<init>(<console>:7) at .<clinit>(<console>) at $print(<console>) at sun.reflect.NativeMethodAccessorImpl.invoke...
DiagrammedExpr
companion object that provides factory methods to create different sub types of DiagrammedExpr
DiagrammedExpr
companion object that provides factory methods to create different sub types of DiagrammedExpr
DiagrammedExpr
is used by code generated from DiagrammedAssertionsMacro
, it needs to be public
so that the generated code can be compiled. It is expected that ScalaTest users would ever need to use DiagrammedExpr
directly.
Companion object that facilitates the importing of ValueEither
members as
an alternative to mixing it in.
Companion object that facilitates the importing of ValueEither
members as
an alternative to mixing it in. One use case is to import EitherValues
's members so you can use
left.value
and right.value
on Either
in the Scala interpreter:
$ scala -cp scalatest-1.7.jar Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest._ import org.scalatest._ scala> import matchers.ShouldMatchers._ import matchers.ShouldMatchers._ scala> import EitherValues._ import EitherValues._ scala> val e: Either[String, Int] = Left("Muchas problemas") e: Either[String,Int] = Left(Muchas problemas) scala> e.left.value should be ("Muchas problemas") scala> e.right.value should be < 9 org.scalatest.TestFailedException: The Either on which rightValue was invoked was not defined. at org.scalatest.EitherValues$RightValuable.value(EitherValues.scala:148) at .<init>(<console>:18) ...
Companion object to class Exceptional
that provides a factory method and an extractor that enables
patterns that match both Failed
and Canceled
outcomes and
extracts the contained exception and a factory method.
Companion object to class Exceptional
that provides a factory method and an extractor that enables
patterns that match both Failed
and Canceled
outcomes and
extracts the contained exception and a factory method.
Singleton status that represents an already completed run with at least one failed test or aborted suite.
Singleton status that represents an already completed run with at least one failed test or aborted suite.
Note: the difference between this FailedStatus
object and the similarly named Failed
class is that a Failed
instance indicates one test failed, whereas this FailedStatus
object indicates either one or more tests failed
and/or one or more suites aborted during a run. Both are used as the result type of Suite
lifecycle methods, but Failed
is a possible result of withFixture
, whereas FailedStatus
is a possible result of run
, runNestedSuites
,
runTests
, or runTest
. In short, Failed
is always just about one test, whereas FailedStatus
could be
about something larger: multiple tests or an entire suite.
Companion object that facilitates the importing of the inside
construct as
an alternative to mixing it in.
Companion object that facilitates the importing of the inside
construct as
an alternative to mixing it in. One use case is to import the inside
construct so you can use
it in the Scala interpreter:
$ scala -cp scalatest-1.8.jar Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest._ import org.scalatest._ scala> import matchers.ShouldMatchers._ import matchers.ShouldMatchers._ scala> import Inside._ import Inside._ scala> inside (List(1, 2, 3)) { case List(x, y, z) => | y should equal (2) | } scala> inside (List(1, 2, 3)) { case List(x, y, z) => | x should equal (2) | } org.scalatest.TestFailedException: 1 did not equal 2, inside List(1, 2, 3) at org.scalatest.matchers.Matchers$class.newTestFailedException(Matchers.scala:150) at org.scalatest.matchers.ShouldMatchers$.newTestFailedException(ShouldMatchers.scala:2331) at org.scalatest.matchers.ShouldMatchers$ShouldMethodHelper$.shouldMatcher(ShouldMatchers.scala:873) ...
Companion object that facilitates the importing of Inspectors
members as
an alternative to mixing it in.
Companion object that facilitates the importing of Inspectors
members as
an alternative to mixing it in. One use case is to import Inspectors
's members so you can use
them in the Scala interpreter.
Companion object that facilitates the importing of LoneElement
members as
an alternative to mixing it in.
Companion object that facilitates the importing of LoneElement
members as
an alternative to mixing it in. One use case is to import LoneElement
's members so you can use
loneElement
in the Scala interpreter.
Companion object that facilitates the importing of Matchers
members as
an alternative to mixing it the trait.
Companion object that facilitates the importing of Matchers
members as
an alternative to mixing it the trait. One use case is to import Matchers
members so you can use
them in the Scala interpreter.
Companion object that facilitates the importing of Matchers
members as
an alternative to mixing it the trait.
Companion object that facilitates the importing of Matchers
members as
an alternative to mixing it the trait. One use case is to import Matchers
members so you can use
them in the Scala interpreter.
Companion object that facilitates the importing of the members of trait Assertions
without importing the implicit conversions
it provides by default.
Companion object that facilitates the importing of the members of trait Assertions
without importing the implicit conversions
it provides by default. One use case for this object is to import the non-implicit Assertions
members so you can use
them in the Scala interpreter along with another library whose implicits conflict with those provided by Assertions
:
$ scala -cp scalatest-1.7.jar Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest._ import org.scalatest._ scala> import NonImplicitAssertions._ import NonImplicitAssertions._ scala> assert(1 + 1 === 2) <console>:14: error: value === is not a member of Int assert(1 + 1 === 2) ^ scala> assert(1 + 1 == 2) scala> expect(2) { 1 + 1 } scala> expect(2) { 1 + 1 + 1 } org.scalatest.TestFailedException: Expected 2, but got 3 at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:318) at org.scalatest.NonImplicitAssertions$.newAssertionFailedException(NonImplicitAssertions.scala:73) ... scala> intercept[IndexOutOfBoundsException] { "hi".charAt(-1) } res3: IndexOutOfBoundsException = java.lang.StringIndexOutOfBoundsException: String index out of range: -1
Companion object that facilitates the importing of OptionValues
members as
an alternative to mixing it in.
Companion object that facilitates the importing of OptionValues
members as
an alternative to mixing it in. One use case is to import OptionValues
's members so you can use
value
on option in the Scala interpreter:
$ scala -cp scalatest-1.7.jar Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest._ import org.scalatest._ scala> import matchers.ShouldMatchers._ import matchers.ShouldMatchers._ scala> import OptionValues._ import OptionValues._ scala> val opt1: Option[Int] = Some(1) opt1: Option[Int] = Some(1) scala> val opt2: Option[Int] = None opt2: Option[Int] = None scala> opt1.value should be < 10 scala> opt2.value should be < 10 org.scalatest.TestFailedException: The Option on which value was invoked was not defined. at org.scalatest.OptionValues$Valuable.value(OptionValues.scala:68) at .<init>(<console>:18) ...
Companion object for trait Outcome
that contains an implicit method that enables
collections of Outcome
s to be flattened into a collections of contained exceptions.
Companion object for trait Outcome
that contains an implicit method that enables
collections of Outcome
s to be flattened into a collections of contained exceptions.
Companion object that facilitates the importing of OutcomeOf
's method as
an alternative to mixing it in.
Companion object that facilitates the importing of OutcomeOf
's method as
an alternative to mixing it in. One use case is to import OutcomeOf
's method so you can use
it in the Scala interpreter.
Companion object that facilitates the importing of PartialFunctionValues
members as
an alternative to mixing it in.
Companion object that facilitates the importing of PartialFunctionValues
members as
an alternative to mixing it in. One use case is to import PartialFunctionValues
's members so you can use
the valueAt
method on PartialFunction
in the Scala interpreter:
$ scala -cp scalatest-1.7.jar Welcome to Scala version 2.9.1.final (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_29). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest._ import org.scalatest._ scala> import matchers.ShouldMatchers._ import matchers.ShouldMatchers._ scala> import PartialFunctionValues._ import PartialFunctionValues._ scala> val pf: PartialFunction[String, Int] = Map("I" -> 1, "II" -> 2, "III" -> 3, "IV" -> 4) pf: PartialFunction[String,Int] = Map(I -> 1, II -> 2, III -> 3, IV -> 4) scala> pf("IV") should equal (4) scala> pf("V") should equal (5) java.util.NoSuchElementException: key not found: V at scala.collection.MapLike$class.default(MapLike.scala:224) at scala.collection.immutable.Map$Map4.default(Map.scala:167) ...
Companion object that facilitates the importing of Payloads
members as
an alternative to mixing it in.
Companion object that facilitates the importing of Payloads
members as
an alternative to mixing it in. One use case is to import Payloads
members so you can use them in the Scala interpreter.
Outcome for a test that was pending, which contains an optional string giving more information on what exactly is needed for the test to become non-pending.
Companion object that facilitates the importing of PrivateMethodTester
members as
an alternative to mixing it in.
Companion object that facilitates the importing of PrivateMethodTester
members as
an alternative to mixing it in. One use case is to import PrivateMethodTester
members so you can use
them in the Scala interpreter:
$scala -classpath scalatest.jar Welcome to Scala version 2.7.5.final (Java HotSpot(TM) Client VM, Java 1.5.0_16). Type in expressions to have them evaluated. Type :help for more information. scala> import org.scalatest.PrivateMethodTester._ import org.scalatest.PrivateMethodTester._ scala> class Example { | private def addSesame(prefix: String) = prefix + " sesame" | } defined class Example scala> val example = new Example example: Example = Example@d8b6fe scala> val addSesame = PrivateMethod[String]('addSesame) addSesame: org.scalatest.PrivateMethodTester.PrivateMethod[String] = org.scalatest.PrivateMethodTester$PrivateMethod@5cdf95 scala> example invokePrivate addSesame("open") res0: String = open sesame@author Bill Venners
Companion object to trait Retries
that enables its members to be imported as an
alternative to mixing them in.
Companion object to trait Retries
that enables its members to be imported as an
alternative to mixing them in.
Companion object to class Sequential
that offers an apply
factory method
for creating a Sequential
instance.
Companion object to class Sequential
that offers an apply
factory method
for creating a Sequential
instance.
One use case for this object is to run multiple specification-style suites in the Scala interpreter, like this:
scala> Sequential(new MyFirstSuite, new MyNextSuite).execute()
Companion object to class Stepwise
that offers an apply
factory method
for creating a Stepwise
instance.
Companion object to class Stepwise
that offers an apply
factory method
for creating a Stepwise
instance.
One use case for this object is to run multiple specification-style suites in the Scala interpreter, like this:
scala> Stepwise(new MyFirstSuite, new MyNextSuite).execute()
Companion object to Stopper that holds a factory method that produces a new Stopper
whose
stopRequested
method returns false until after its requestStop
has been
invoked.
Companion object to Stopper that holds a factory method that produces a new Stopper
whose
stopRequested
method returns false until after its requestStop
has been
invoked.
Outcome for a test that succeeded.
Outcome for a test that succeeded.
Note: the difference between this Succeeded
object and the similarly named SucceededStatus
object is that this object indicates one test succeeded, whereas the SucceededStatus
object indicates the absence of any failed tests or
aborted suites during a run. Both are used as the result type of Suite
lifecycle methods, but Succeeded
is a possible result of withFixture
, whereas SucceededStatus
is a possible result of run
, runNestedSuites
,
runTests
, or runTest
. In short, Succeeded
is always just about one test, whereas SucceededStatus
could be
about something larger: multiple tests or an entire suite.
Singleton status that represents an already completed run with no tests failed and no suites aborted.
Singleton status that represents an already completed run with no tests failed and no suites aborted.
Note: the difference between this SucceededStatus
object and the similarly named Succeeded
object is that the Succeeded
object indicates one test succeeded, whereas this SucceededStatus
object indicates the absence
of any failed tests or aborted suites during a run. Both are used as the result type of Suite
lifecycle methods, but Succeeded
is a possible result of withFixture
, whereas SucceededStatus
is a possible result of run
, runNestedSuites
,
runTests
, or runTest
. In short, Succeeded
is always just about one test, whereas SucceededStatus
could be
about something larger: multiple tests or an entire suite.
Companion object to class Suites
that offers an apply
factory method
for creating a Suites
instance.
Companion object to class Suites
that offers an apply
factory method
for creating a Suites
instance.
One use case for this object is to run multiple specification-style suites in the Scala interpreter, like this:
scala> Suites(new MyFirstSuite, new MyNextSuite).execute()
Companion object for Tag
, which offers a factory method.
Companion object for Tag
, which offers a factory method.
Companion object that facilitates the importing of TryValues
members as
an alternative to mixing it in.
Companion object that facilitates the importing of TryValues
members as
an alternative to mixing it in. One use case is to import TryValues
's members so you can use
success
and failure
on Try
in the Scala interpreter.
Returns a copy of this Shell
with colorPassed
configuration parameter set to true
.
Returns a copy of this Shell
with colorPassed
configuration parameter set to true
.
Returns a copy of this Shell
with durationsPassed
configuration parameter set to true
.
Returns a copy of this Shell
with durationsPassed
configuration parameter set to true
.
Returns a copy of this Shell
with fullStacksPassed
configuration parameter set to true
.
Returns a copy of this Shell
with fullStacksPassed
configuration parameter set to true
.
Returns a copy of this Shell
with colorPassed
configuration parameter set to false
.
Returns a copy of this Shell
with colorPassed
configuration parameter set to false
.
Returns a copy of this Shell
with durationsPassed
configuration parameter set to false
.
Returns a copy of this Shell
with durationsPassed
configuration parameter set to false
.
Returns a copy of this Shell
with shortStacksPassed
configuration parameter set to false
.
Returns a copy of this Shell
with shortStacksPassed
configuration parameter set to false
.
Returns a copy of this Shell
with statsPassed
configuration parameter set to false
.
Returns a copy of this Shell
with statsPassed
configuration parameter set to false
.
Package object to hold deprecated type aliases for exception classes moved from org.
Package object to hold deprecated type aliases for exception classes moved from org.scalatest.prop to org.scalatest.exceptions.
Singleton object providing an apply
method for the ScalaTest shell and a
main
method for ScalaTest's simple runner.
Singleton object providing an apply
method for the ScalaTest shell and a
main
method for ScalaTest's simple runner.
The apply
method can be used in the ScalaTest Shell (its DSL for the Scala
interpreter) in this way:
scala> import org.scalatest._ import org.scalatest._ scala> class ArithmeticSuite extends FunSuite with ShouldMatchers { | test("addition works") { | 1 + 1 should equal (2) | } | ignore("subtraction works") { | 1 - 1 should equal (0) | } | test("multiplication works") { | 1 * 1 should equal (2) | } | test("division works") (pending) | } defined class ArithmeticSuite scala> run(new ArithmeticSuite) ArithmeticSuite: - addition works - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** 1 did not equal 2 (:16) - division works (pending)
The last command is calling the apply
method on the run
singleton object. In other
words, you could alternatively call it this way:
scala> run.apply(new ArithmeticSuite) ArithmeticSuite: - addition works - subtraction works !!! IGNORED !!! - multiplication works *** FAILED *** 1 did not equal 2 (:16) - division works (pending)
The run
singleton object also serves a different purpose. Its main
method
allows users to "run" run
as a Scala application. ScalaTest's Runner
application is very
powerful, but doesn't provide the simplest out-of-box experience for people trying ScalaTest for the first time. For example,
to run an ExampleSpec
in the unnamed package from the directory where it is compiled with
Runner
's standard out reporter requires this command:
$ scala -cp scalatest-RELEASE.jar org.scalatest.tools.Runner -R . -o -s ExampleSpec
Running it with the run
application is simpler:
$ scala -cp scalatest-RELEASE.jar org.scalatest.run ExampleSpec
Returns a copy of this Shell
with shortStacksPassed
configuration parameter set to true
.
Returns a copy of this Shell
with shortStacksPassed
configuration parameter set to true
.
Returns a copy of this Shell
with statsPassed
configuration parameter set to true
.
Returns a copy of this Shell
with statsPassed
configuration parameter set to true
.
The FailureOf object has been deprecated. Please use object OutcomeOf instead.
Object Specs
has been deprecated and will be removed in a future version of ScalaTest. Please
change all uses of Specs
to Suites
instead.
Object Specs
has been deprecated and will be removed in a future version of ScalaTest. Please
change all uses of Specs
to Suites
instead.
Specs has been deprecated and will be removed in a future version of ScalaTest. Please use Suites instead.
ScalaTest's main traits, classes, and other members, including members supporting ScalaTest's DSL for the Scala interpreter.