org.scalatest.WordSpec.scala Maven / Gradle / Ivy
Show all versions of scalatest_2.11.0-M3 Show documentation
/* * Copyright 2001-2008 Artima, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.scalatest import verb.{CanVerb, ResultOfAfterWordApplication, ShouldVerb, BehaveWord, MustVerb, StringVerbBlockRegistration} import NodeFamily._ import scala.collection.immutable.ListSet import org.scalatest.exceptions.StackDepthExceptionHelper.getStackDepth import java.util.concurrent.atomic.AtomicReference import java.util.ConcurrentModificationException import org.scalatest.events._ import Suite.anErrorThatShouldCauseAnAbort /** * Trait that facilitates a “behavior-driven” style of development (BDD), in which tests * are combined with text that specifies the behavior the tests verify. * (In BDD, the word example is usually used instead of test. The word test will not appear * in your code if you use
Buffer. If you wantedWordSpec
, so if you prefer the word example you can use it. However, in this documentation * the word test will be used, for clarity and to be consistent with the rest of ScalaTest.) * TraitWordSpec
is so named because * you specification text is structured by placing words after strings. * Here's an exampleWordSpec
: * ** import org.scalatest.WordSpec * import scala.collection.mutable.Stack * * class StackSpec extends WordSpec { * * "A Stack" should { * * "pop values in last-in-first-out order" in { * val stack = new Stack[Int] * stack.push(1) * stack.push(2) * assert(stack.pop() === 2) * assert(stack.pop() === 1) * } * * "throw NoSuchElementException if an empty stack is popped" in { * val emptyStack = new Stack[String] * intercept[NoSuchElementException] { * emptyStack.pop() * } * } * } * } ** ** Note: Trait
* *WordSpec
is in part inspired by classorg.specs.Specification
, designed by * Eric Torreborre for the specs framework. ** See also: Getting started with
* *WordSpec
. ** In a
* *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
, orcan
, 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. Awhen
clause * follows the subject and precedes a block. In the block after thewhen
, 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.WordSpec * * 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 { * // ... * } * } * } * } ** ** Running the above
* *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 moveswhen
andshould
* 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.WordSpec * * 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 {} * } * } ** ** In such situations you can place
* *which
clauses inside the verb clause, like this: ** import org.scalatest.WordSpec * * 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 {} * } * } * } ** ** Running the above
* *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
andshould
/must
/can
, awhich
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 previousWordSpec
, the word "provide" is repeated * at the beginning of each string inside theshould
block. You can factor out this duplication * like this: ** import org.scalatest.WordSpec * * 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 {} * } * } * } ** ** Running the above version of
* *AndOrSpec
with theprovide
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
, orcan
), or *which
. (You can't place one afterin
oris
, the * words that introduce a test.) Here's an example that has after words used in all three * places: ** import org.scalatest.WordSpec * * 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 {} * } * } * } * } ** ** Running the previous
* *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 *
* ** A
* *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 theWordSpec
has * entered its ready phase, i.e., afterrun
has been invoked on theWordSpec
, * will be met with a thrownTestRegistrationClosedException
. The recommended style * of usingWordSpec
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,WordSpec
adds a method *ignore
to strings that can be used instead ofin
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: * * ** import org.scalatest.WordSpec * import scala.collection.mutable.Stack * * class StackSpec extends WordSpec { * * "A Stack" should { * * "pop values in last-in-first-out order" ignore { * val stack = new Stack[Int] * stack.push(1) * stack.push(2) * assert(stack.pop() === 2) * assert(stack.pop() === 1) * } * * "throw NoSuchElementException if an empty stack is popped" in { * val emptyStack = new Stack[String] * intercept[NoSuchElementException] { * emptyStack.pop() * } * } * } * } ** ** If you run this version of
* *StackSpec
with: ** scala> (new StackSpec).execute() ** ** It will run only the second test and report that the first test was ignored: *
* ** StackSpec: * A Stack * - should pop values in last-in-first-out order !!! IGNORED !!! * - should throw NoSuchElementException if an empty stack is popped ** *Informers
* ** One of the parameters to the
* *run
method is aReporter
, 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 theReporter
as the suite runs. * Most often the reporting done by default byWordSpec
's methods will be sufficient, but * occasionally you may wish to provide custom information to theReporter
from a test. * For this purpose, anInformer
that will forward information to the currentReporter
* is provided via theinfo
parameterless method. * You can pass the extra information to theInformer
via itsapply
method. * TheInformer
will then pass the information to theReporter
via anInfoProvided
event. * Here's an example: ** import org.scalatest.WordSpec * * class ArithmeticSpec extends WordSpec { * * "The Scala language" should { * "add correctly" in { * val sum = 2 + 3 * assert(sum === 5) * info("addition seems to work") * } * * "subtract correctly" in { * val diff = 7 - 2 * assert(diff === 5) * } * } * } ** ** If you run this
* *WordSpec
from the interpreter, you will see the following message * included in the printed report: ** scala> (new ArithmeticSpec).execute() * ArithmeticSpec: * The Scala language * - should add correctly * + addition seems to work * - should subtract correctly *
* ** One use case for the
* *Informer
is to pass more information about a specification to the reporter. For example, * theGivenWhenThen
trait provides methods that use the implicitinfo
provided byWordSpec
* to pass such information to the reporter. Here's an example: ** import org.scalatest.WordSpec * import org.scalatest.GivenWhenThen * * class ArithmeticSpec extends WordSpec with GivenWhenThen { * * "The Scala language" should { * * "add correctly" in { * * given("two integers") * val x = 2 * val y = 3 * * when("they are added") * val sum = x + y * * then("the result is the sum of the two numbers") * assert(sum === 5) * } * * "subtract correctly" in { * * given("two integers") * val x = 7 * val y = 2 * * when("one is subtracted from the other") * val diff = x - y * * then("the result is the difference of the two numbers") * assert(diff === 5) * } * } * } ** ** If you run this
* *WordSpec
from the interpreter, you will see the following messages * included in the printed report: ** scala> (new ArithmeticSpec).execute() * ArithmeticSpec: * The Scala language * - should add correctly * + Given two integers * + When they are added * + Then the result is the sum of the two numbers * - should subtract correctly * + Given two integers * + When one is subtracted from the other * + Then the result is the difference of the two numbers *
* *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 withTestPendingException
. ** 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 * withTestPendingException
, 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 aWordSpec
like this: ** import org.scalatest.WordSpec * * class ArithmeticSpec extends WordSpec { * * // Sharing fixture objects via instance variables * val shared = 5 * * "The Scala language" should { * "add correctly" in { * val sum = 2 + 3 * assert(sum === shared) * } * * "subtract correctly" is (pending) * } * } ** ** If you run this version of
* *ArithmeticSpec
with: ** scala> (new ArithmeticSpec).execute() ** ** It will run both tests but report that
* *The Scala language should subtract correctly
is pending. You'll see: ** The Scala language * - should add correctly * - should subtract correctly (pending) ** ** One 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 thepending
method does). Thus * the body of pending tests are executed up until they throwTestPendingException
. The reason for this difference * is that it enables your unfinished test to sendInfoProvided
messages to the reporter before it completes * abruptly withTestPendingException
, as shown in the previous example onInformer
s * that used theGivenWhenThen
trait. For example, the following snippet in aWordSpec
: ** "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
* * AWordSpec
's tests may be classified into groups by tagging them with string names. * As with any suite, when executing aWordSpec
, groups of tests can * optionally be included and/or excluded. To tag aWordSpec
's tests, * you pass objects that extend abstract classorg.scalatest.Tag
totaggedAs
method * invoked on the string that describes the test you want to tag. ClassTag
takes one parameter, * a string name. If you have * created Java annotation interfaces for use as group names in direct subclasses oforg.scalatest.Suite
, * then you will probably want to use group names on yourWordSpec
s that match. To do so, simply * pass the fully qualified names of the Java interfaces to theTag
constructor. For example, if you've * defined Java annotation interfaces with fully qualified names,com.mycompany.tags.SlowTest
andcom.mycompany.tags.DbTest
, then you could * create matching groups forWordSpec
s like this: * * ** import org.scalatest.Tag * * object SlowTest extends Tag("com.mycompany.tags.SlowTest") * object DbTest extends Tag("com.mycompany.tags.DbTest") ** ** Given these definitions, you could place
* *WordSpec
tests into groups like this: ** import org.scalatest.WordSpec * * class ExampleSpec extends WordSpec { * * "The Scala language" should { * * "add correctly" taggedAs(SlowTest) in { * val sum = 1 + 1 * assert(sum === 2) * } * * "subtract correctly" taggedAs(SlowTest, DbTest) in { * val diff = 4 - 1 * assert(diff === 3) * } * } * } ** ** This code marks both tests with the
* *com.mycompany.tags.SlowTest
tag, * and test"The Scala language should subtract correctly"
with thecom.mycompany.tags.DbTest
tag. ** The
* *run
method takes aFilter
, whose constructor takes an optional *Set[String]
calledtagsToInclude
and aSet[String]
called *tagsToExclude
. IftagsToInclude
isNone
, all tests will be run * except those those belonging to tags listed in the *tagsToExclude
Set
. IftagsToInclude
is defined, only tests * belonging to tags mentioned in thetagsToInclude
set, and not mentioned intagsToExclude
, * will be run. *Shared fixtures
* ** A test fixture is objects or other artifacts (such as files, sockets, database * connections, etc.) used by tests to do their work. * If a fixture is used by only one test method, then the definitions of the fixture objects can * be local to the method, such as the objects assigned to
* *sum
anddiff
in the * previousExampleSpec
examples. If multiple methods need to share an immutable fixture, one approach * is to assign them to instance variables. ** In some cases, however, shared mutable fixture objects may be changed by test methods such that * they need to be recreated or reinitialized before each test. Shared resources such * as files or database connections may also need to * be created and initialized before, and cleaned up after, each test. JUnit 3 offered methods
* *setUp
and *tearDown
for this purpose. In ScalaTest, you can use theBeforeAndAfterEach
trait, * which will be described later, to implement an approach similar to JUnit'ssetUp
* andtearDown
, however, this approach usually involves reassigningvar
s or mutating objects * between tests. Before going that route, you may wish to consider some more functional approaches that * avoid side effects. *Calling create-fixture methods
* ** One approach is to write one or more create-fixture methods * that return a new instance of a needed fixture object (or an holder object containing multiple needed fixture objects) each time it * is called. You can then call a create-fixture method at the beginning of each * test method that needs the fixture, storing the returned object or objects in local variables. Here's an example: *
* ** 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) * } * } * } ** ** The “
* *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. *Instantiating fixture traits
* ** A related technique is to place * the fixture objects in a fixture trait and run your test code in the context of a new anonymous class instance that mixes in * the fixture trait, like this: *
* ** import org.scalatest.WordSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends WordSpec { * * trait Fixture { * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * } * * "Testing" should { * * "be easy" in { * new Fixture { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * } * * "be fun" in { * new Fixture { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * } * } * } * } ** *Mixing in
* *OneInstancePerTest
* If every test method requires the same set of * mutable fixture objects, one other approach you can take is make them simply
* *val
s and mix in trait *OneInstancePerTest
. If you mix inOneInstancePerTest
, each test * will be run in its own instance of theSuite
, similar to the way JUnit tests are executed. Here's an example: ** import org.scalatest.WordSpec * import org.scalatest.OneInstancePerTest * import collection.mutable.ListBuffer * * class ExampleSpec extends WordSpec with OneInstancePerTest { * * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * * "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) * } * } * } ** ** Although the create-fixture, fixture-trait, and
* *OneInstancePerTest
approaches take care of setting up a fixture before each * test, they don't address the problem of cleaning up a fixture after the test completes. In this situation, you'll need to either * use side effects or the loan pattern. *Mixing in
* *BeforeAndAfter
* One way to use side effects is to mix in the
* *BeforeAndAfter
trait. * With this trait you can denote a bit of code to run before each test withbefore
and/or after each test * each test withafter
, like this: ** 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) * } * } * } ** *Overriding
* *withFixture(NoArgTest)
* An alternate way to take care of setup and cleanup via side effects * is to override
* *withFixture
. TraitSuite
's implementation of *runTest
, which is inherited by this trait, passes a no-arg test function towithFixture
. It iswithFixture
's * responsibility to invoke that test function.Suite
's implementation ofwithFixture
simply * invokes the function, like this: ** // Default implementation * protected def withFixture(test: NoArgTest) { * test() * } ** ** You can, therefore, override
* *withFixture
to perform setup before, and cleanup after, invoking the test function. If * you have cleanup to perform, you should invoke the test function * inside atry
block and perform the cleanup in afinally
clause. * Here's an example: ** import org.scalatest.WordSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends WordSpec { * * val builder = new StringBuilder * val buffer = new ListBuffer[String] * * override def withFixture(test: NoArgTest) { * builder.append("ScalaTest is ") // perform setup * try { * test() // invoke the test function * } * finally { * builder.clear() // perform cleanup * 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) * buffer += "clear" * } * } * } ** ** Note that the
* *NoArgTest
passed towithFixture
, in addition to * anapply
method that executes the test, also includes the test name as well as the config * map passed torunTest
. Thus you can also use the test name and configuration objects inwithFixture
. ** The reason you should perform cleanup in a
* *finally
clause is thatwithFixture
is called by *runTest
, which expects an exception to be thrown to indicate a failed test. Thus when you invoke * thetest
function insidewithFixture
, it may complete abruptly with an exception. Thefinally
* clause will ensure the fixture cleanup happens as that exception propagates back up the call stack torunTest
. *Overriding
* *withFixture(OneArgTest)
* To use the loan pattern, you can extend
* *WordSpec
(from theorg.scalatest.fixture
package) instead of *WordSpec
. Each test in aWordSpec
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 specifyingFixtureParam
, and implement a *withFixture
method that takes aOneArgTest
. ThiswithFixture
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. Here's an example: ** import org.scalatest.fixture * import java.io.FileWriter * import java.io.File * * class ExampleSpec extends fixture.WordSpec { * * final val tmpFile = "temp.txt" * * type FixtureParam = FileWriter * * def withFixture(test: OneArgTest) { * * val writer = new FileWriter(tmpFile) // set up the fixture * try { * test(writer) // "loan" the fixture to the test * } * finally { * writer.close() // clean up the fixture * } * } * * "Testing" should { * * "be easy" in { writer => * writer.write("Hello, test!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * * "be fun" in { writer => * writer.write("Hi, test!") * writer.flush() * assert(new File(tmpFile).length === 9) * } * } * } ** ** For more information, see the documentation for
* *org.scalatest.fixture.WordSpec
. *Providing different fixtures to different tests
* ** If different tests in the same
* *WordSpec
require different fixtures, you can combine the previous techniques and * provide each test with just the fixture or fixtures it needs. Here's an example in which aStringBuilder
and a *ListBuffer
are provided via fixture traits, and file writer (that requires cleanup) is provided via the loan pattern: ** import java.io.FileWriter * import java.io.File * import collection.mutable.ListBuffer * import org.scalatest.WordSpec * * class ExampleSpec extends WordSpec { * * final val tmpFile = "temp.txt" * * trait Builder { * val builder = new StringBuilder("ScalaTest is ") * } * * trait Buffer { * val buffer = ListBuffer("ScalaTest", "is") * } * * def withWriter(testCode: FileWriter => Any) { * val writer = new FileWriter(tmpFile) // set up the fixture * try { * testCode(writer) // "loan" the fixture to the test * } * finally { * writer.close() // clean up the fixture * } * } * * "Testing" should { * * "be productive" in { // This test needs the StringBuilder fixture * new Builder { * builder.append("productive!") * assert(builder.toString === "ScalaTest is productive!") * } * } * * "be readable" in { // This test needs the ListBuffer[String] fixture * new Buffer { * buffer += ("readable!") * assert(buffer === List("ScalaTest", "is", "readable!")) * } * } * * "be user-friendly" in { // This test needs the FileWriter fixture * withWriter { writer => * writer.write("Hello, user!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * } * * "be clear and concise" in { // This test needs the StringBuilder and ListBuffer * new Builder with Buffer { * builder.append("clear!") * buffer += ("concise!") * assert(builder.toString === "ScalaTest is clear!") * assert(buffer === List("ScalaTest", "is", "concise!")) * } * } * * "be composable" in { // This test needs all three fixtures * new Builder with Buffer { * builder.append("clear!") * buffer += ("concise!") * assert(builder.toString === "ScalaTest is clear!") * assert(buffer === List("ScalaTest", "is", "concise!")) * withWriter { writer => * writer.write(builder.toString) * writer.flush() * assert(new File(tmpFile).length === 19) * } * } * } * } * } ** ** In the previous example,
* *be productive
uses only theStringBuilder
fixture, so it just instantiates * anew Builder
, whereasbe readable
uses only theListBuffer
fixture, so it just intantiates * anew Buffer
.be friendly
needs just theFileWriter
fixture, so it invokes *withWriter
, which prepares and passes aFileWriter
to the test (and takes care of closing it afterwords). ** Two tests need multiple fixtures:
* *be clear and concise
needs both theStringBuilder
and the *ListBuffer
, so it instantiates a class that mixes in both fixture traits withnew Builder with Buffer
. *be composable
needs all three fixtures, so in addition tonew Builder with Buffer
it also invokes *withWriter
, wrapping just the of the test code that needs the fixture. ** Note that in this case, the loan pattern is being implemented via the
* *withWriter
method that takes a function, not * by overridingWordSpec
'swithFixture(OneArgTest)
method.WordSpec
makes the most sense * if all (or at least most) tests need the same fixture, whereas in thisSuite
only two tests need the *FileWriter
. ** In the previous example, the
* *withWriter
method passed an object into * the tests. Passing fixture objects into tests is generally a good idea when possible, but sometimes a side affect is unavoidable. * For example, if you need to initialize a database running on a server across a network, your with-fixture * method will likely have nothing to pass. In such cases, simply create a with-fixture method that takes a by-name parameter and * performs setup and cleanup via side effects, like this: ** def withDataInDatabase(test: => Any) { * // initialize the database across the network * try { * test // "loan" the initialized database to the test * } * finally { * // clean up the database * } * } ** ** You can then use it like: *
* ** "A user" can { * "log onto the system" in { * withDataInDatabase { * // test user logging in scenario * } * } * } ** *Composing stackable fixture 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 callsuper.withFixture
. Here's an example in * which theStringBuilder
andListBuffer[String]
fixtures used in the previous examples have been * factored out into two stackable fixture traits namedBuilder
andBuffer
: ** import org.scalatest.WordSpec * import org.scalatest.AbstractSuite * import collection.mutable.ListBuffer * * trait Builder extends AbstractSuite { 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 AbstractSuite { 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" * } * } * } ** ** By mixing in both the
Builder
andBuffer
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" toBuffer
to be "super" * toBuilder
, you need only switch the order you mix them together, like this: * * ** class Example2Spec extends WordSpec with Buffer with Builder ** ** And if you only need one fixture you mix in only that trait: *
* ** class Example3Spec extends WordSpec with Builder ** ** Another way to create stackable fixture traits is by extending the
* *BeforeAndAfterEach
* and/orBeforeAndAfterAll
traits. *BeforeAndAfterEach
has abeforeEach
method that will be run before each test (like JUnit'ssetUp
), * and anafterEach
method that will be run after (like JUnit'stearDown
). * Similarly,BeforeAndAfterAll
has abeforeAll
method that will be run before all tests, * and anafterAll
method that will be run after all tests. Here's what the previously shown example would look like if it * were rewritten to use theBeforeAndAfterEach
methods instead ofwithFixture
: ** import org.scalatest.WordSpec * 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" * } * } * } ** ** To get the same ordering as
* *withFixture
, place yoursuper.beforeEach
call at the end of each *beforeEach
method, and thesuper.afterEach
call at the beginning of eachafterEach
* method, as shown in the previous example. It is a good idea to invokesuper.afterEach
in atry
* block and perform cleanup in afinally
clause, as shown in the previous example, because this ensures the * cleanup code is performed even ifsuper.afterAll
throws an exception. ** One difference to bear in mind between the before-and-after traits and the
* *withFixture
methods, is that if * awithFixture
method completes abruptly with an exception, it is considered a failed test. By contrast, if any of the * methods on the before-and-after traits (i.e.,before
andafter
ofBeforeAndAfter
, *beforeEach
andafterEach
ofBeforeAndAfterEach
, * andbeforeAll
andafterAll
ofBeforeAndAfterAll
) complete abruptly, it is considered a * failed suite, which will result in aSuiteAborted
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 anyWordSpec
that uses them, so that the tests they * contain will be registered as tests in thatWordSpec
. For example, given this stack class: ** import scala.collection.mutable.ListBuffer * * 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(", ", ", ")") * } ** ** You may want to test the
* *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 yourWordSpec
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 theWordSpec
that uses them. If they are shared * between differentWordSpec
s, however, you could also define them in a separate trait that is mixed into eachWordSpec
* 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 => * * 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) * } * } * } ** * ** Given these behavior functions, you could invoke them directly, but
* *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 astack
var
inbeforeEach
, you could write your behavior functions * in the context of thatvar
, 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 { * * // 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) * } * } * } * } * } ** ** If you load these classes into the Scala interpreter (with scalatest's JAR file on the class path), and execute it, * you'll see: *
* ** 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 surroundingwhen
, *should
/must
/can
, orwhich
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 aWordSpec
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
* * @author Bill Venners */ trait WordSpec extends Suite with ShouldVerb with MustVerb with CanVerb { thisSuite => private final val engine = new Engine("concurrentWordSpecMod", "WordSpec") import engine._ /** * Returns an"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 surroundingwhen
clauses. *Informer
that during test execution will forward strings (and other objects) passed to its *apply
method to the current reporter. If invoked in a constructor, it * will register the passed string for forwarding later during test execution. If invoked while this *WordSpec
is being executed, such as from inside a test function, it will forward the information to * the current reporter immediately. If invoked at any other time, it will * throw an exception. This method can be called safely by any thread. */ implicit protected def info: Informer = atomicInformer.get /** * Register a test with the given spec text, optional tags, and test function value that takes no arguments. * An invocation of this method is called an “example.” * * This method will register the test for later execution via an invocation of one of theexecute
* methods. The name of the test will be a concatenation of the text of all surrounding describers, * from outside in, and the passed spec text, with one space placed between each item. (See the documenation * fortestNames
for an example.) The resulting test name must not have been registered previously on * thisWordSpec
instance. * * @param specText the specification text, which will be combined with the descText of any surrounding describers * to form the test name * @param testTags the optional list of tags for this test * @param methodName Caller's methodName * @param testFun the test function * @throws DuplicateTestNameException if a test with the same name has been registered previously * @throws TestRegistrationClosedException if invoked afterrun
has been invoked on this suite * @throws NullPointerException ifspecText
or any passed test tag isnull
*/ private def registerTestToRun(specText: String, testTags: List[Tag], methodName: String, testFun: () => Unit) { registerTest(specText, testFun, "itCannotAppearInsideAnotherIt", "WordSpec.scala", methodName, 1, None, None, testTags: _*) } /** * Register a test to ignore, which has the given spec text, optional tags, and test function value that takes no arguments. * This method will register the test for later ignoring via an invocation of one of theexecute
* methods. This method exists to make it easy to ignore an existing test by changing the call toit
* toignore
without deleting or commenting out the actual test code. The test will not be executed, but a * report will be sent that indicates the test was ignored. The name of the test will be a concatenation of the text of all surrounding describers, * from outside in, and the passed spec text, with one space placed between each item. (See the documenation * fortestNames
for an example.) The resulting test name must not have been registered previously on * thisWordSpec
instance. * * @param specText the specification text, which will be combined with the descText of any surrounding describers * to form the test name * @param testTags the optional list of tags for this test * @param methodName Caller's methodName * @param testFun the test function * @throws DuplicateTestNameException if a test with the same name has been registered previously * @throws TestRegistrationClosedException if invoked afterrun
has been invoked on this suite * @throws NullPointerException ifspecText
or any passed test tag isnull
*/ private def registerTestToIgnore(specText: String, testTags: List[Tag], methodName: String, testFun: () => Unit) { registerIgnoredTest(specText, testFun, "ignoreCannotAppearInsideAnIt", "WordSpec.scala", methodName, 1, testTags: _*) } private def registerBranch(description: String, childPrefix: Option[String], methodName:String, fun: () => Unit) { registerNestedBranch(description, childPrefix, fun(), "describeCannotAppearInsideAnIt", "WordSpec.scala", methodName, 1) } /** * Class that supports the registration of tagged tests. * ** Instances of this class are returned by the
* * @author Bill Venners */ protected final class ResultOfTaggedAsInvocationOnString(specText: String, tags: List[Tag]) { /** * Supports tagged test registration. * *taggedAs
method of * classWordSpecStringWrapper
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) in { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def in(testFun: => Unit) { registerTestToRun(specText, tags, "in", testFun _) } /** * Supports registration of tagged, pending tests. * *WordSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) is (pending) * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(specText, tags, "is", testFun _) } /** * Supports registration of tagged, ignored tests. * *WordSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) ignore { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(specText, tags, "ignore", testFun _) } } /** * A class that via an implicit conversion (namedWordSpec
. *convertToWordSpecStringWrapper
) enables * methodswhen
,which
,in
,is
,taggedAs
* andignore
to be invoked onString
s. * ** This class provides much of the syntax for
* * @author Bill Venners */ protected final class WordSpecStringWrapper(string: String) { /** * Supports test registration. * *WordSpec
, however, it does not add * the verb methods (should
,must
, andcan
) toString
. * Instead, these are added via theShouldVerb
,MustVerb
, andCanVerb
* traits, whichWordSpec
mixes in, to avoid a conflict with implicit conversions provided * inShouldMatchers
andMustMatchers
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" in { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def in(f: => Unit) { registerTestToRun(string, List(), "in", f _) } /** * Supports ignored test registration. * *WordSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" ignore { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def ignore(f: => Unit) { registerTestToIgnore(string, List(), "ignore", f _) } /** * Supports pending test registration. * *WordSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" is (pending) * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def is(f: => PendingNothing) { registerTestToRun(string, List(), "is", f _) } /** * Supports tagged test registration. * *WordSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) in { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def taggedAs(firstTestTag: Tag, otherTestTags: Tag*) = { val tagList = firstTestTag :: otherTestTags.toList new ResultOfTaggedAsInvocationOnString(string, tagList) } /** * Registers aWordSpec
. *when
clause. * ** For example, this method supports syntax such as the following: *
* ** "A Stack" when { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def when(f: => Unit) { registerBranch(string, Some("when"), "when", f _) } /** * Registers aWordSpec
. *when
clause that is followed by an after word. * ** For example, this method supports syntax such as the following: *
* ** val theUser = afterWord("the user") * * "A Stack" when theUser { ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def when(resultOfAfterWordApplication: ResultOfAfterWordApplication) { registerBranch(string, Some("when " + resultOfAfterWordApplication.text), "when", resultOfAfterWordApplication.f) } /** *WordSpec
. *that
has been deprecated and will be used for a different purpose in a future version of ScalaTest. Please * usewhich
instead. (Warning: this change will likely have a shorter than usual deprecation cycle: less than a year.) */ @deprecated("Please use \"which\" instead of \"that\".") def that(f: => Unit) { registerBranch(string + " that", None, "that", f _) } /** * Registers awhich
clause. * ** For example, this method supports syntax such as the following: *
* ** "a rerun button" which { * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def which(f: => Unit) { registerBranch(string + " which", None, "which", f _) } /** *WordSpec
. *that
has been deprecated and will be used for a different purpose in a future version of ScalaTest. Please * usewhich
instead. (Warning: this change will likely have a shorter than usual deprecation cycle: less than a year.) */ @deprecated("Please use \"which\" instead of \"that\".") def that(resultOfAfterWordApplication: ResultOfAfterWordApplication) { registerBranch(string + " that " + resultOfAfterWordApplication.text, None, "that", resultOfAfterWordApplication.f) } /** * Registers awhich
clause that is followed by an after word. * ** For example, this method supports syntax such as the following: *
* ** def is = afterWord("is") * * "a rerun button" which is { * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def which(resultOfAfterWordApplication: ResultOfAfterWordApplication) { registerBranch(string + " which " + resultOfAfterWordApplication.text, None, "which", resultOfAfterWordApplication.f) } } /** * Class whose instances are after words, which can be used to reduce text duplication. * *WordSpec
. ** If you are repeating a word or phrase at the beginning of each string inside * a block, you can "move the word or phrase" out of the block with an after word. * You create an after word by passing the repeated word or phrase to the
* *afterWord
method. * Once created, you can place the after word afterwhen
, a verb * (should
,must
, orcan
), or *which
. (You can't place one afterin
oris
, the * words that introduce a test.) Here's an example that has after words used in all three * places: ** import org.scalatest.WordSpec * * 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 {} * } * } * } * } ** ** Running the previous
* *WordSpec
in the Scala interpreter would yield: ** scala> (new ScalaTestGUISpec).execute() * 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 * - should display the details for the event in the details area * - should display a rerun button that is enabled if the clicked-on event is rerunnable * - should display a rerun button that is disabled if the clicked-on event is not rerunnable *
*/ protected final class AfterWord(text: String) { /** * Supports the use of after words. * ** This method transforms a block of code into a
*/ def apply(f: => Unit) = new ResultOfAfterWordApplication(text, f _) } /** * Creates an after word that an be used to reduce text duplication. * *ResultOfAfterWordApplication
, which * is accepted bywhen
,should
,must
,can
, andwhich
* methods. For more information, see the main documentation for traitWordSpec
. ** If you are repeating a word or phrase at the beginning of each string inside * a block, you can "move the word or phrase" out of the block with an after word. * You create an after word by passing the repeated word or phrase to the
* *afterWord
method. * Once created, you can place the after word afterwhen
, a verb * (should
,must
, orcan
), or *which
. (You can't place one afterin
oris
, the * words that introduce a test.) Here's an example that has after words used in all three * places: ** import org.scalatest.WordSpec * * 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 {} * } * } * } * } ** ** Running the previous
* *WordSpec
in the Scala interpreter would yield: ** scala> (new ScalaTestGUISpec).execute() * 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 * - should display the details for the event in the details area * - should display a rerun button that is enabled if the clicked-on event is rerunnable * - should display a rerun button that is disabled if the clicked-on event is not rerunnable *
*/ protected def afterWord(text: String) = new AfterWord(text) /** * Implicitly convertsString
s toWordSpecStringWrapper
, which enables * methodswhen
,which
,in
,is
,taggedAs
* andignore
to be invoked onString
s. */ protected implicit def convertToWordSpecStringWrapper(s: String) = new WordSpecStringWrapper(s) // Used to enable should/can/must to take a block (except one that results in type string. May // want to mention this as a gotcha.) /* import org.scalatest.WordSpec class MySpec extends WordSpec { "bla bla bla" should { "do something" in { assert(1 + 1 === 2) } "now it is a string" } } delme.scala:6: error: no implicit argument matching parameter type (String, String, String) => org.scalatest.verb.ResultOfStringPassedToVerb was found. "bla bla bla" should { ^ one error found */ /** * Supports the registration of subjects. * ** For example, this method enables syntax such as the following: *
* ** "A Stack" should { ... * ^ ** ** This function is passed as an implicit parameter to a
*/ protected implicit val subjectRegistrationFunction: StringVerbBlockRegistration = new StringVerbBlockRegistration { def apply(left: String, verb: String, f: () => Unit) = registerBranch(left, Some(verb), "apply", f) } /** * Supports the registration of subject descriptions with after words. * *should
method * provided inShouldVerb
, amust
method * provided inMustVerb
, and acan
method * provided inCanVerb
. When invoked, this function registers the * subject and executes the block. ** For example, this method enables syntax such as the following: *
* ** def provide = afterWord("provide") * * "The ScalaTest Matchers DSL" can provide { ... } * ^ ** ** This function is passed as an implicit parameter to a
*/ protected implicit val subjectWithAfterWordRegistrationFunction: (String, String, ResultOfAfterWordApplication) => Unit = { (left, verb, resultOfAfterWordApplication) => { val afterWordFunction = () => { registerBranch(resultOfAfterWordApplication.text, None, "subjectWithAfterWordRegistrationFunction", resultOfAfterWordApplication.f) } registerBranch(left, Some(verb), "subjectWithAfterWordRegistrationFunction", afterWordFunction) } } /** * Ashould
method * provided inShouldVerb
, amust
method * provided inMustVerb
, and acan
method * provided inCanVerb
. When invoked, this function registers the * subject and executes the block. *Map
whose keys areString
tag names to which tests in thisWordSpec
belong, and values * theSet
of test names that belong to each tag. If thisWordSpec
contains no tags, this method returns an emptyMap
. * ** This trait's implementation returns tags that were passed as strings contained in
*/ override def tags: Map[String, Set[String]] = atomic.get.tagsMap /** * Run a test. This trait's implementation runs the test registered with the name specified by *Tag
objects passed to * methodstest
andignore
. *testName
. Each test's name is a concatenation of the text of all describers surrounding a test, * from outside in, and the test's spec text, with one space placed between each item. (See the documenation * fortestNames
for an example.) * * @param testName the name of one test to execute. * @param reporter theReporter
to which results will be reported * @param stopper theStopper
that will be consulted to determine whether to stop execution early. * @param configMap aMap
of properties that can be used by thisWordSpec
's executing tests. * @throws NullPointerException if any oftestName
,reporter
,stopper
, orconfigMap
* isnull
. */ protected override def runTest(testName: String, reporter: Reporter, stopper: Stopper, configMap: Map[String, Any], tracker: Tracker) { def invokeWithFixture(theTest: TestLeaf) { val theConfigMap = configMap withFixture( new NoArgTest { def name = testName def apply() { theTest.testFun() } def configMap = theConfigMap } ) } runTestImpl(thisSuite, testName, reporter, stopper, configMap, tracker, true, invokeWithFixture) } /** * Run zero to many of thisWordSpec
's tests. * ** This method takes a
* *testName
parameter that optionally specifies a test to invoke. * IftestName
isSome
, this trait's implementation of this method * invokesrunTest
on this object, passing in: *
-
*
testName
- theString
value of thetestName
Option
passed * to this method
* reporter
- theReporter
passed to this method, or one that wraps and delegates to it
* stopper
- theStopper
passed to this method, or one that wraps and delegates to it
* configMap
- theconfigMap
passed to this method, or one that wraps and delegates to it
*
* This method takes a Set
of tag names that should be included (tagsToInclude
), and a Set
* that should be excluded (tagsToExclude
), when deciding which of this Suite
's tests to execute.
* If tagsToInclude
is empty, all tests will be executed
* except those those belonging to tags listed in the tagsToExclude
Set
. If tagsToInclude
is non-empty, only tests
* belonging to tags mentioned in tagsToInclude
, and not mentioned in tagsToExclude
* will be executed. However, if testName
is Some
, tagsToInclude
and tagsToExclude
are essentially ignored.
* Only if testName
is None
will tagsToInclude
and tagsToExclude
be consulted to
* determine which of the tests named in the testNames
Set
should be run. For more information on trait tags, see the main documentation for this trait.
*
* If testName
is None
, this trait's implementation of this method
* invokes testNames
on this Suite
to get a Set
of names of tests to potentially execute.
* (A testNames
value of None
essentially acts as a wildcard that means all tests in
* this Suite
that are selected by tagsToInclude
and tagsToExclude
should be executed.)
* For each test in the testName
Set
, in the order
* they appear in the iterator obtained by invoking the elements
method on the Set
, this trait's implementation
* of this method checks whether the test should be run based on the tagsToInclude
and tagsToExclude
Set
s.
* If so, this implementation invokes runTest
, passing in:
*
-
*
testName
- theString
name of the test to run (which will be one of the names in thetestNames
Set
)
* reporter
- theReporter
passed to this method, or one that wraps and delegates to it
* stopper
- theStopper
passed to this method, or one that wraps and delegates to it
* configMap
- theconfigMap
passed to this method, or one that wraps and delegates to it
*
None
, all relevant tests should be run.
* I.e., None
acts like a wildcard that means run all relevant tests in this Suite
.
* @param reporter the Reporter
to which results will be reported
* @param stopper the Stopper
that will be consulted to determine whether to stop execution early.
* @param filter a Filter
with which to filter tests based on their tags
* @param configMap a Map
of key-value pairs that can be used by the executing Suite
of tests.
* @param distributor an optional Distributor
, into which to put nested Suite
s to be run
* by another entity, such as concurrently by a pool of threads. If None
, nested Suite
s will be run sequentially.
* @param tracker a Tracker
tracking Ordinal
s being fired by the current thread.
* @throws NullPointerException if any of the passed parameters is null
.
* @throws IllegalArgumentException if testName
is defined, but no test with the specified test name
* exists in this Suite
*/
protected override def runTests(testName: Option[String], reporter: Reporter, stopper: Stopper, filter: Filter,
configMap: Map[String, Any], distributor: Option[Distributor], tracker: Tracker) {
runTestsImpl(thisSuite, testName, reporter, stopper, filter, configMap, distributor, tracker, info, true, runTest)
}
/**
* An immutable Set
of test names. If this WordSpec
contains no tests, this method returns an
* empty Set
.
*
*
* This trait's implementation of this method will return a set that contains the names of all registered tests. The set's
* iterator will return those names in the order in which the tests were registered. Each test's name is composed
* of the concatenation of the text of each surrounding describer, in order from outside in, and the text of the
* example itself, with all components separated by a space. For example, consider this WordSpec
:
*
* import org.scalatest.WordSpec * * class StackSpec { * "A Stack" when { * "not empty" must { * "allow me to pop" in {} * } * "not full" must { * "allow me to push" in {} * } * } * } ** *
* Invoking testNames
on this WordSpec
will yield a set that contains the following
* two test name strings:
*
* "A Stack (when not empty) must allow me to pop" * "A Stack (when not full) must allow me to push" **/ override def testNames: Set[String] = { // I'm returning a ListSet here so that they tests will be run in registration order ListSet(atomic.get.testNamesList.toArray: _*) } override def run(testName: Option[String], reporter: Reporter, stopper: Stopper, filter: Filter, configMap: Map[String, Any], distributor: Option[Distributor], tracker: Tracker) { runImpl(thisSuite, testName, reporter, stopper, filter, configMap, distributor, tracker, super.run) } /** * Supports shared test registration in
WordSpec
s.
*
* * This field enables syntax such as the following: *
* ** behave like nonFullStack(stackWithOneItem) * ^ ** *
* For more information and examples of the use of