org.scalatest.FeatureSpec.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 NodeFamily._ import scala.collection.immutable.ListSet import org.scalatest.exceptions.StackDepthExceptionHelper.getStackDepthFun import java.util.concurrent.atomic.AtomicReference import java.util.ConcurrentModificationException import org.scalatest.events._ import Suite.anErrorThatShouldCauseAnAbort /** * A suite of tests in which each test represents one scenario of a feature. *
Buffer. If you wantedFeatureSpec
is intended for writing tests that are "higher level" than unit tests, for example, integration * tests, functional tests, and acceptance tests. You can useFeatureSpec
for unit testing if you prefer, however. * Here's an example: * ** import org.scalatest.FeatureSpec * import org.scalatest.GivenWhenThen * import scala.collection.mutable.Stack * * class StackFeatureSpec extends FeatureSpec with GivenWhenThen { * * feature("The user can pop an element off the top of the stack") { * * info("As a programmer") * info("I want to be able to pop items off the stack") * info("So that I can get them in last-in-first-out order") * * scenario("pop is invoked on a non-empty stack") { * * given("a non-empty stack") * val stack = new Stack[Int] * stack.push(1) * stack.push(2) * val oldSize = stack.size * * when("when pop is invoked on the stack") * val result = stack.pop() * * then("the most recently pushed element should be returned") * assert(result === 2) * * and("the stack should have one less item than before") * assert(stack.size === oldSize - 1) * } * * scenario("pop is invoked on an empty stack") { * * given("an empty stack") * val emptyStack = new Stack[String] * * when("when pop is invoked on the stack") * then("NoSuchElementException should be thrown") * intercept[NoSuchElementException] { * emptyStack.pop() * } * * and("the stack should still be empty") * assert(emptyStack.isEmpty) * } * } * } ** ** A
* *FeatureSpec
contains feature clauses and scenarios. You define a feature clause * withfeature
, and a scenario withscenario
. Both *feature
andscenario
are methods, defined in *FeatureSpec
, which will be invoked * by the primary constructor ofStackFeatureSpec
. * 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 stack. The feature being specified and tested is * the ability for a user (a programmer in this case) to pop an element off the top of the stack. 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 theFeatureSpec
is * in its registration phase. Any attempt to register a scenario after theFeatureSpec
has * entered its ready phase, i.e., afterrun
has been invoked on theFeatureSpec
, * will be met with a thrownTestRegistrationClosedException
. The recommended style * of usingFeatureSpec
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 aFeatureSpec
, therefore, you must take care * to ensure that each test has a unique name (in other words, that eachscenario
has unique spec text). ** When you run a
* *FeatureSpec
, it will sendFormatter
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, if you ranStackFeatureSpec
from within the Scala interpreter: ** scala> (new StackFeatureSpec).execute() ** ** You would see: *
* ** Feature: The user can pop an element off the top of the stack * As a programmer * I want to be able to pop items off the stack * So that I can get them in last-in-first-out order * Scenario: pop is invoked on a non-empty stack * Given a non-empty stack * When when pop is invoked on the stack * Then the most recently pushed element should be returned * And the stack should have one less item than before * Scenario: pop is invoked on an empty stack * Given an empty stack * When when pop is invoked on the stack * Then NoSuchElementException should be thrown * And the stack should still be empty *
* ** See also: Getting started with
* *FeatureSpec
. *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 withignore
instead ofscenario
. For example, to temporarily * disable the test namedaddition
, just change “scenario
” into “ignore
,” like this: ** import org.scalatest.FeatureSpec * * class ArithmeticSpec extends FeatureSpec { * * // Sharing fixture objects via instance variables * val shared = 5 * * feature("Integer arithmetic") { * * ignore("addition") { * val sum = 2 + 3 * assert(sum === shared) * } * * scenario("subtraction") { * val diff = 7 - 2 * assert(diff === shared) * } * } * } ** ** If you run this version of
* *ArithmeticSpec
with: ** scala> (new ArithmeticSpec).execute() ** ** It will run only
* *subtraction
and report thataddition
was ignored: ** Feature: Integer arithmetic * Scenario: addition !!! IGNORED !!! * Scenario: subtraction ** *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 byFeatureSpec
'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.FeatureSpec * * class ArithmeticSpec extends FeatureSpec { * * feature("Integer arithmetic") { * * scenario("addition") { * val sum = 2 + 3 * assert(sum === 5) * info("Addition seems to work") * } * * scenario("subtraction") { * val diff = 7 - 2 * assert(diff === 5) * } * } * } ** * If you run thisArithmeticSpec
from the interpreter, you will see the following message * included in the printed report: * ** Feature: Integer arithmetic * Scenario: addition * Addition seems to work *
* ** One use case for the
* *Informer
is to pass more information about a scenario to the reporter. For example, * theGivenWhenThen
trait provides methods that use the implicitinfo
provided byFeatureSpec
* to pass such information to the reporter. Here's an example: ** import org.scalatest.FeatureSpec * import org.scalatest.GivenWhenThen * * class ArithmeticSpec extends FeatureSpec with GivenWhenThen { * * feature("Integer arithmetic") { * * scenario("addition") { * * 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) * } * * scenario("subtraction") { * * 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
* *FeatureSpec
from the interpreter, you will see the following messages * included in the printed report: ** scala> (new ArithmeticSpec).execute() * Feature: Integer arithmetic * Scenario: addition * Given two integers * When they are added * Then the result is the sum of the two numbers * Scenario: subtraction * 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, has not yet been implemented. * You can mark tests as pending in aFeatureSpec
like this: ** import org.scalatest.FeatureSpec * * class ArithmeticSpec extends FeatureSpec { * * // Sharing fixture objects via instance variables * val shared = 5 * * feature("Integer arithmetic") { * * scenario("addition") { * val sum = 2 + 3 * assert(sum === shared) * } * * scenario("subtraction") (pending) * } * } ** ** (Note: "
* *(pending)
" is the body of the test. Thus the test contains just one statement, an invocation * of thepending
method, which throwsTestPendingException
.) * If you run this version ofArithmeticSpec
with: ** scala> (new ArithmeticSpec).execute() ** ** It will run both tests, but report that
* *subtraction
is pending. You'll see: ** Feature: Integer arithmetic * Scenario: addition * Scenario: subtraction (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 aFeatureSpec
: ** feature("Integer arithmetic") { * * scenario("addition") { * 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: *
* ** Feature: Integer arithmetic * Scenario: addition (pending) * Given two integers * When they are added * Then the result is the sum of the two numbers ** *Tagging tests
* ** A
* *FeatureSpec
's tests may be classified into groups by tagging them with string names. * As with any suite, when executing aFeatureSpec
, groups of tests can * optionally be included and/or excluded. To tag aFeatureSpec
's tests, * you pass objects that extend abstract classorg.scalatest.Tag
to methods * that register tests,test
andignore
. 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 yourFeatureSpec
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
and *com.mycompany.tags.DbTest
, then you could * create matching groups forFeatureSpec
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
* *FeatureSpec
tests into groups like this: ** import org.scalatest.FeatureSpec * * class ArithmeticSpec extends FeatureSpec { * * // Sharing fixture objects via instance variables * val shared = 5 * * feature("Integer arithmetic") { * * scenario("addition", SlowTest) { * val sum = 2 + 3 * assert(sum === shared) * } * * scenario("subtraction", SlowTest, DbTest) { * val diff = 7 - 2 * assert(diff === shared) * } * } * } ** ** This code marks both tests, "addition" and "subtraction," with the
* *com.mycompany.tags.SlowTest
tag, * and test "subtraction" 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.FeatureSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends FeatureSpec { * * def fixture = * new { * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * } * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * val f = fixture * f.builder.append("easy!") * assert(f.builder.toString === "ScalaTest is easy!") * assert(f.buffer.isEmpty) * f.buffer += "sweet" * } * * scenario("user enjoys writing tests with shared fixtures") { * 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.FeatureSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends FeatureSpec { * * trait Fixture { * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * } * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * new Fixture { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * } * * scenario("user enjoys writing tests with shared fixtures") { * 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.FeatureSpec * import org.scalatest.OneInstancePerTest * import collection.mutable.ListBuffer * * class ExampleSpec extends FeatureSpec with OneInstancePerTest { * * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * scenario("user enjoys writing tests with shared fixtures") { * 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.FeatureSpec * import org.scalatest.BeforeAndAfter * import collection.mutable.ListBuffer * * class ExampleSpec extends FeatureSpec with BeforeAndAfter { * * val builder = new StringBuilder * val buffer = new ListBuffer[String] * * before { * builder.append("ScalaTest is ") * } * * after { * builder.clear() * buffer.clear() * } * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * scenario("user enjoys writing tests with shared fixtures") { * 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.FeatureSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends FeatureSpec { * * 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() * } * } * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * scenario("user enjoys writing tests with shared fixtures") { * 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
* *FeatureSpec
(from theorg.scalatest.fixture
package) instead of *FeatureSpec
. Each test in aFeatureSpec
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.FeatureSpec { * * 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 * } * } * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { writer => * writer.write("Hello, test!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * * scenario("user enjoys writing tests with shared fixtures") { writer => * writer.write("Hi, test!") * writer.flush() * assert(new File(tmpFile).length === 9) * } * } * } ** ** For more information, see the documentation for
* *FeatureSpec
. *Providing different fixtures to different tests
* ** If different tests in the same
* *FeatureSpec
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.FeatureSpec * * class ExampleSpec extends FeatureSpec { * * 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 * } * } * * scenario("user is productive using the test framework") { // This test needs the StringBuilder fixture * new Builder { * builder.append("productive!") * assert(builder.toString === "ScalaTest is productive!") * } * } * * scenario("tests are readable") { // This test needs the ListBuffer[String] fixture * new Buffer { * buffer += ("readable!") * assert(buffer === List("ScalaTest", "is", "readable!")) * } * } * * scenario("the test framework is user-friendly") { // This test needs the FileWriter fixture * withWriter { writer => * writer.write("Hello, user!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * } * * scenario("test code is clear and concise") { // 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!")) * } * } * * scenario("user composes test artifacts") { // 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,
* *"user is productive using the test framework
uses only theStringBuilder
fixture, so it just instantiates * anew Builder
, whereastests are readable
uses only theListBuffer
fixture, so it just intantiates * anew Buffer
.the test framework is user-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:
* *test code is clear and concise
needs both theStringBuilder
and the *ListBuffer
, so it instantiates a class that mixes in both fixture traits withnew Builder with Buffer
. *user composes test artifacts
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 overridingFeatureSpec
'swithFixture(OneArgTest)
method.FeatureSpec
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: *
* ** scenario("user logs 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.FeatureSpec * 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 FeatureSpec with Builder with Buffer { * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * scenario("user enjoys writing tests with shared fixtures") { * 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 FeatureSpec with Buffer with Builder ** ** And if you only need one fixture you mix in only that trait: *
* ** class Example3Spec extends FeatureSpec 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.FeatureSpec * 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 FeatureSpec with Builder with Buffer { * * feature("Fixtures can be shared") { * * scenario("user learns how to share fixtures") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * scenario("user enjoys writing tests with shared fixtures") { * 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 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 anyFeatureSpec
that uses them, so that the scenarios they contain will * be registered as scenarios in thatFeatureSpec
. * 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 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 yourFeatureSpec
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 differentFeatureSpec
s, however, you could also define them in a separate trait that is mixed into * eachFeatureSpec
that uses them. * For example, here thenonEmptyStack
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.Stack * * 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) * } * } * } ** ** Given these behavior functions, you could invoke them directly, but
* *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 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: ** 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.Stack * * 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) * } * } * } * } ** ** 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 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 toFunSpec
'sdescribe
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 calltoString
on the shared fixture object. * This is the approach taken by the previousFeatureSpecStackBehaviors
example. ** Given this
* *FeatureSpecStackBehaviors
trait, calling it with thestackWithOneItem
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)
*
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
* FeatureSpec
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 the execute
* 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
* for testNames
for an example.) The resulting test name must not have been registered previously on
* this FeatureSpec
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 testFun the test function
* @throws DuplicateTestNameException if a test with the same name has been registered previously
* @throws TestRegistrationClosedException if invoked after run
has been invoked on this suite
* @throws NullPointerException if specText
or any passed test tag is null
*/
protected def scenario(specText: String, testTags: Tag*)(testFun: => Unit) {
registerTest(Resources("scenario", specText), testFun _, "scenarioCannotAppearInsideAnotherScenario", "FeatureSpec.scala", "scenario", 2, 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 the execute
* methods. This method exists to make it easy to ignore an existing test by changing the call to it
* to ignore
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
* for testNames
for an example.) The resulting test name must not have been registered previously on
* this FeatureSpec
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 testFun the test function
* @throws DuplicateTestNameException if a test with the same name has been registered previously
* @throws TestRegistrationClosedException if invoked after run
has been invoked on this suite
* @throws NullPointerException if specText
or any passed test tag is null
*/
protected def ignore(specText: String, testTags: Tag*)(testFun: => Unit) {
registerIgnoredTest(Resources("scenario", specText), testFun _, "ignoreCannotAppearInsideAScenario", "FeatureSpec.scala", "ignore", 1, testTags: _*)
}
/**
* Describe a “subject” being specified and tested by the passed function value. The
* passed function value may contain more describers (defined with describe
) and/or tests
* (defined with it
). This trait's implementation of this method will register the
* description string and immediately invoke the passed function.
*/
protected def feature(description: String)(fun: => Unit) {
if (!currentBranchIsTrunk)
throw new NotAllowedException(Resources("cantNestFeatureClauses"), getStackDepthFun("FeatureSpec.scala", "feature"))
registerNestedBranch(description, None, fun, "featureCannotAppearInsideAScenario", "FeatureSpec.scala", "feature", 1)
}
/**
* A Map
whose keys are String
tag names to which tests in this FeatureSpec
belong, and values
* the Set
of test names that belong to each tag. If this FeatureSpec
contains no tags, this method returns an empty Map
.
*
*
* This trait's implementation returns tags that were passed as strings contained in Tag
objects passed to
* methods test
and ignore
.
*
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
* for testNames
for an example.)
*
* @param testName the name of one test to execute.
* @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 configMap a Map
of properties that can be used by this FeatureSpec
's executing tests.
* @throws NullPointerException if any of testName
, reporter
, stopper
, or configMap
* is null
.
*/
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, false, invokeWithFixture)
}
/**
* Run zero to many of this FeatureSpec
's tests.
*
*
* This method takes a testName
parameter that optionally specifies a test to invoke.
* If testName
is Some
, this trait's implementation of this method
* invokes runTest
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, false, runTest)
}
/**
* An immutable Set
of test names. If this FeatureSpec
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 FeatureSpec
:
*
* import org.scalatest.FeatureSpec * * class StackSpec extends FeatureSpec { * feature("A Stack") { * scenario("(when not empty) must allow me to pop") {} * scenario("(when not full) must allow me to push") {} * } * } ** *
* Invoking testNames
on this FeatureSpec
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] = ListSet(atomic.get.testsList.map(_.testName): _*) 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) } /** * Registers shared scenarios. * *
* This method enables the following syntax for shared scenarios in a FeatureSpec
:
*
* scenariosFor(nonEmptyStack(lastValuePushed)) ** *
* This method just provides syntax sugar intended to make the intent of the code clearer.
* Because the parameter passed to it is
* type Unit
, the expression will be evaluated before being passed, which
* is sufficient to register the shared scenarios. For examples of shared scenarios, see the
* Shared scenarios section in the main documentation for this trait.
*