org.scalatest.FlatSpec.scala Maven / Gradle / Ivy
Show all versions of scalatest_2.11.0-M3 Show documentation
/* * Copyright 2001-2009 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.{ResultOfTaggedAsInvocation, ResultOfStringPassedToVerb, BehaveWord, ShouldVerb, MustVerb, CanVerb} 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 wantedFlatSpec
, 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.) * TraitFlatSpec
is so named because * your specification text and tests line up flat against the left-side indentation level, with no nesting needed. * * **
* *FlatSpec
's no-nesting approach contrasts with traitsFunSpec
andWordSpec
, which use nesting * to reduce duplication of specification text. Although nesting does have the advantage of reducing text duplication, * figuring out the full specification text for one test can require back-tracking out of several levels of nesting, mentally prepending * each fragment of text encountered. Thus the tradeoff with the nesting approach ofFunSpec
andWordSpec
is that * they have less duplicated text at the cost of being a bit challenging to read. TraitFlatSpec
offers the opposite * tradeoff. In aFlatSpec
text is duplicated more, but figuring out the full specification text for a particular test is * easier. Here's an exampleFlatSpec
: ** import org.scalatest.FlatSpec * import scala.collection.mutable.Stack * * class StackSpec extends FlatSpec { * * behavior of "A Stack" * * it 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) * } * * it should "throw NoSuchElementException if an empty stack is popped" in { * val emptyStack = new Stack[String] * intercept[NoSuchElementException] { * emptyStack.pop() * } * } * } ** ** Note: you can you
* *must
orcan
as well asshould
in aFlatSpec
. For example, instead of *it should "pop
..., you could writeit must "pop
... orit can "pop
.... ** Instead of using a
* *behavior of
clause, you can alternatively use a shorthand syntax in which you replace * the firstit
with the subject string, like this: ** import org.scalatest.FlatSpec * import scala.collection.mutable.Stack * * class StackSpec extends FlatSpec { * * "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) * } * * it should "throw NoSuchElementException if an empty stack is popped" in { * val emptyStack = new Stack[String] * intercept[NoSuchElementException] { * emptyStack.pop() * } * } * } ** ** Running either of the two previous three versions of
* *StackSpec
in the Scala interpreter would yield: ** A Stack * - should pop values in last-in-first-out order * - should throw NoSuchElementException if an empty stack is popped *
* ** In a
* *FlatSpec
you write a one (or more) sentence specification for each bit of behavior you wish to * specify and test. Each specification sentence has a * "subject," which is sometimes called the system under test (or SUT). The * subject is the entity being specified and tested and also serves as the subject of the sentences you write for each test. * Often you will want to write multiple tests for the same subject. In aFlatSpec
, you name the subject once, * with abehavior of
clause or its shorthand, then write tests for that subject withit should
/must
can "do something"
phrases. * Eachit
refers to the most recently declared subject. For example, the four tests shown in this snippet are all testing * a stack that contains one item: ** behavior of "A Stack (with one item)" * * it should "be non-empty" in {} * * it should "return the top item on peek" in {} * * it should "not remove the top item on peek" in {} * * it should "remove the top item on pop" in {} ** ** The same is true if the tests are written using the shorthand notation: *
* ** "A Stack (with one item)" should "be non-empty" in {} * * it should "return the top item on peek" in {} * * it should "not remove the top item on peek" in {} * * it should "remove the top item on pop" in {} ** ** In a
* *FlatSpec
, therefore, to figure out what "it
" means, you just scan vertically until you find the most * recent use ofbehavior of
or the shorthand notation. ** A
* *FlatSpec
's lifecycle has two phases: the registration phase and the * ready phase. It starts in registration phase and enters ready phase the first time *run
is called on it. It then remains in ready phase for the remainder of its lifetime. ** Tests can only be registered while the
* *FlatSpec
is * in its registration phase. Any attempt to register a test after theFlatSpec
has * entered its ready phase, i.e., afterrun
has been invoked on theFlatSpec
, * will be met with a thrownTestRegistrationClosedException
. The recommended style * of usingFlatSpec
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
. ** See also: Getting started with
* *FlatSpec
. *Ignored tests
* * To support the common use case of “temporarily” disabling a test, with the * good intention of resurrecting the test at a later time,FlatSpec
provides a method *ignore
that can be used instead ofit
to register a test. For example, to temporarily * disable the test with the name"A Stack should throw NoSuchElementException if an empty stack is popped"
, just * change “it
” into “ignore
,” like this: * * ** import org.scalatest.FlatSpec * import scala.collection.mutable.Stack * * class StackSpec extends FlatSpec { * * "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) * } * * ignore should "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 first test and report that the second test was ignored: *
* ** A Stack * - should pop values in last-in-first-out order * - should throw NoSuchElementException if an empty stack is popped !!! IGNORED !!! ** ** When using shorthand notation, you won't have an
* *it
to change intoignore
for * the first test of each new subject. To ignore such tests, you must instead changein
toignore
. * For example, to temporarily disable the test with the name"A Stack should pop values in last-in-first-out order"
, * change “in
” into “ignore
” like this: ** import org.scalatest.FlatSpec * import scala.collection.mutable.Stack * * class StackSpec extends FlatSpec { * * "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) * } * * it should "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: *
* ** 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 byFlatSpec
'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.FlatSpec * * class ArithmeticSpec extends FlatSpec { * * "The Scala language" must "add correctly" in { * val sum = 2 + 3 * assert(sum === 5) * info("addition seems to work") * } * * it must "subtract correctly" in { * val diff = 7 - 2 * assert(diff === 5) * } * } ** ** If you run this
* *FlatSpec
from the interpreter, you will see the following message * included in the printed report: ** scala> (new ArithmeticSpec).execute() * The Scala language * - must add correctly * + addition seems to work * - must 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 byFlatSpec
* to pass such information to the reporter. Here's an example: ** import org.scalatest.FlatSpec * import org.scalatest.GivenWhenThen * * class ArithmeticSpec extends FlatSpec with GivenWhenThen { * * "The Scala language" must "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) * } * * it must "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) * } * } ** ** scala> (new ArithmeticSpec).execute() * The Scala language * - must add correctly * + Given two integers * + When they are added * + Then the result is the sum of the two numbers * - must 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 inFlatSpec
like this: ** import org.scalatest.FlatSpec * * class ArithmeticSpec extends FlatSpec { * * // Sharing fixture objects via instance variables * val shared = 5 * * "The Scala language" must "add correctly" in { * val sum = 2 + 3 * assert(sum === shared) * } * * it must "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 must subtract correctly
is pending. You'll see: ** The Scala language * - must add correctly * - must 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 aFlatSpec
: ** "The Scala language" must "add correctly" in { * given("two integers") * when("they are added") * then("the result is the sum of the two numbers") * pending * } * // ... ** ** Would yield the following output when run in the interpreter: *
* ** The Scala language * - must add correctly (pending) * + Given two integers * + When they are added * + Then the result is the sum of the two numbers ** *Tagging tests
* * AFlatSpec
's tests may be classified into groups by tagging them with string names. * As with any suite, when executing aFlatSpec
, groups of tests can * optionally be included and/or excluded. To tag aFlatSpec
'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 yourFlatSpec
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 forFlatSpec
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
* *FlatSpec
tests into groups like this: ** import org.scalatest.FlatSpec * * class ExampleSpec extends FlatSpec { * * "The Scala language" must "add correctly" taggedAs(SlowTest) in { * val sum = 1 + 1 * assert(sum === 2) * } * * it must "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.FlatSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends FlatSpec { * * def fixture = * new { * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * } * * "Testing" should "be easy" in { * val f = fixture * f.builder.append("easy!") * assert(f.builder.toString === "ScalaTest is easy!") * assert(f.buffer.isEmpty) * f.buffer += "sweet" * } * * it should "be fun" in { * val f = fixture * f.builder.append("fun!") * assert(f.builder.toString === "ScalaTest is fun!") * assert(f.buffer.isEmpty) * } * } ** ** 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.FlatSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends FlatSpec { * * 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" * } * } * * it should "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.FlatSpec * import org.scalatest.OneInstancePerTest * import collection.mutable.ListBuffer * * class ExampleSpec extends FlatSpec 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" * } * * it should "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.FlatSpec * import org.scalatest.BeforeAndAfter * import collection.mutable.ListBuffer * * class ExampleSpec extends FlatSpec with BeforeAndAfter { * * val builder = new StringBuilder * val buffer = new ListBuffer[String] * * before { * builder.append("ScalaTest is ") * } * * after { * builder.clear() * buffer.clear() * } * * "Testing" should "be easy" in { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * it should "be fun" in { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * } * } ** *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.FlatSpec * import collection.mutable.ListBuffer * * class ExampleSpec extends FlatSpec { * * 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" * } * * it should "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
* *fixture.FlatSpec
(from theorg.scalatest.fixture
package) instead of *FlatSpec
. Each test in afixture.FlatSpec
takes a fixture as a parameter, allowing you to pass the fixture into * the test. You must indicate the type of the fixture parameter by 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.FlatSpec { * * 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) * } * * it should "be fun" in { writer => * writer.write("Hi, test!") * writer.flush() * assert(new File(tmpFile).length === 9) * } * } ** ** For more information, see the documentation for
* *fixture.FlatSpec
. *Providing different fixtures to different tests
* ** If different tests in the same
* *FlatSpec
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.FlatSpec * * class ExampleSpec extends FlatSpec { * * 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!") * } * } * * it should "be readable" in { // This test needs the ListBuffer[String] fixture * new Buffer { * buffer += ("readable!") * assert(buffer === List("ScalaTest", "is", "readable!")) * } * } * * it should "be user-friendly" in { // This test needs the FileWriter fixture * withWriter { writer => * writer.write("Hello, user!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * } * * "Test code" should "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!")) * } * } * * it should "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,
* *ScalaTest should be productive
uses only theStringBuilder
fixture, so it just instantiates * anew Builder
, whereasit should be readable
uses only theListBuffer
fixture, so it just intantiates * anew Buffer
.it should be 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 should 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
. *it should 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 overridingfixture.FlatSpec
'swithFixture(OneArgTest)
method.fixture.FlatSpec
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" should "be able to 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.FlatSpec * 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 FlatSpec with Builder with Buffer { * * "Testing" should "be easy" in { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * it should "be fun" in { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * buffer += "clear" * } * } ** ** 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 FlatSpec with Buffer with Builder ** ** And if you only need one fixture you mix in only that trait: *
* ** class Example3Spec extends FlatSpec 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.FlatSpec * 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 FlatSpec with Builder with Buffer { * * "Testing" should "be easy" in { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * it should "be fun" in { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * buffer += "clear" * } * } ** ** 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
* *FlatSpec
, you first place shared tests in behavior functions. * These behavior functions will be invoked during the construction phase of anyFlatSpec
that uses them, so that the tests they * contain will be registered as tests in thatFlatSpec
. 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 yourFlatSpec
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 theFlatSpec
that uses them. If they are shared * between differentFlatSpec
s, however, you could also define them in a separate trait that is mixed into eachFlatSpec
* that uses them. ** For example, here the
* *nonEmptyStack
behavior function (in this case, a behavior method) is * defined in a trait along with another method containing shared tests for non-full stacks: ** trait StackBehaviors { this: FlatSpec => * * def nonEmptyStack(newStack: => Stack[Int], lastItemAdded: Int) { * * it should "be non-empty" in { * assert(!newStack.empty) * } * * it should "return the top item on peek" in { * assert(newStack.peek === lastItemAdded) * } * * it should "not remove the top item on peek" in { * val stack = newStack * val size = stack.size * assert(stack.peek === lastItemAdded) * assert(stack.size === size) * } * * it should "remove the top item on pop" in { * val stack = newStack * val size = stack.size * assert(stack.pop === lastItemAdded) * assert(stack.size === size - 1) * } * } * * def nonFullStack(newStack: => Stack[Int]) { * * it should "not be full" in { * assert(!newStack.full) * } * * it should "add to the top on push" in { * val stack = newStack * val size = stack.size * stack.push(7) * assert(stack.size === size + 1) * assert(stack.peek === 7) * } * } * } ** * ** Given these behavior functions, you could invoke them directly, but
* *FlatSpec
offers a DSL for the purpose, * which looks like this: ** it should behave like nonEmptyStack(stackWithOneItem, lastValuePushed) * it should behave like nonFullStack(stackWithOneItem) ** ** If you prefer to use an imperative style to change fixtures, for example by mixing in
* *BeforeAndAfterEach
and * reassigning 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: ** it should behave like nonEmptyStack // assuming lastValuePushed is also in scope inside nonEmptyStack * it should behave like nonFullStack ** ** The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example: *
* ** class SharedTestExampleSpec extends FlatSpec with StackBehaviors { * * // Stack fixture creation methods * def emptyStack = new Stack[Int] * * def fullStack = { * val stack = new Stack[Int] * for (i <- 0 until stack.MAX) * stack.push(i) * stack * } * * def stackWithOneItem = { * val stack = new Stack[Int] * stack.push(9) * stack * } * * def stackWithOneItemLessThanCapacity = { * val stack = new Stack[Int] * for (i <- 1 to 9) * stack.push(i) * stack * } * * val lastValuePushed = 9 * * "A Stack (when empty)" should "be empty" in { * assert(emptyStack.empty) * } * * it should "complain on peek" in { * intercept[IllegalStateException] { * emptyStack.peek * } * } * * it should "complain on pop" in { * intercept[IllegalStateException] { * emptyStack.pop * } * } * * "A Stack (with one item)" should behave like nonEmptyStack(stackWithOneItem, lastValuePushed) * * it should behave like nonFullStack(stackWithOneItem) * * "A Stack (with one item less than capacity)" should behave like nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed) * * it should behave like nonFullStack(stackWithOneItemLessThanCapacity) * * "A Stack (full)" should "be full" in { * assert(fullStack.full) * } * * it should behave like nonEmptyStack(fullStack, lastValuePushed) * * it should "complain on a push" in { * intercept[IllegalStateException] { * fullStack.push(10) * } * } * } ** ** 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() * A Stack (when empty) * - should be empty * - should complain on peek * - should complain on pop * A Stack (with one item) * - should be non-empty * - should return the top item on peek * - should not remove the top item on peek * - should remove the top item on pop * - should not be full * - should add to the top on push * A Stack (with one item less than capacity) * - should be non-empty * - should return the top item on peek * - should not remove the top item on peek * - should remove the top item on pop * - should not be full * - should add to the top on push * A Stack (full) * - should be full * - should be non-empty * - should return the top item on peek * - should not remove the top item on peek * - should remove the top item on pop * - should complain on a push *
* ** One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name. * If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime * complaining that multiple tests are being registered with the same test name. A good way to solve this problem in a
* *WordSpec
is to make sure * each invocation of a behavior function is in the context of a different set ofwhen
, verb (should
, *must
, or can), andthat
clauses, * which will prepend a string to each test name. * For example, the following code in aWordSpec
would register a test with the name"A Stack (when empty) should be empty"
: ** behavior of "A Stack (when empty)" * * it should "be empty" in { * assert(emptyStack.empty) * } * // ... ** ** Or, using the shorthand notation: *
* ** "A Stack" when { * "empty" should { * "be empty" in { * assert(emptyStack.empty) * } * } * } * // ... ** ** If the
* * @author Bill Venners */ trait FlatSpec extends Suite with ShouldVerb with MustVerb with CanVerb { thisSuite => private final val engine = new Engine("concurrentSpecMod", "Spec") import engine._ /** * Returns an"should be empty"
test was factored out into a behavior function, it could be called repeatedly so long * as each invocation of the behavior function is in the context of a different combination * ofwhen
, verb, andthat
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 *FlatSpec
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 * thisFlatSpec
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 method name of the caller * @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) { // TODO: This is what was being used before but it is wrong registerTest(specText, testFun, "itCannotAppearInsideAnotherIt", "FlatSpec.scala", methodName, 1, None, None, testTags: _*) } /** * Class that supports the registration of a “subject” being specified and tested via the * instance referenced fromFlatSpec
'sbehavior
field. * ** This field enables syntax such as the following subject registration: *
* ** behavior of "A Stack" * ^ ** ** For more information and examples of the use of the
*/ protected final class BehaviorWord { /** * Supports the registration of a “subject” being specified and tested via the * instance referenced frombehavior
field, see the main documentation * for traitFlatSpec
. *FlatSpec
'sbehavior
field. * ** This method enables syntax such as the following subject registration: *
* ** behavior of "A Stack" * ^ ** ** For more information and examples of the use of this method, see the main documentation * for trait
*/ def of(description: String) { // TODO: This is what was here, but it needs fixing. registerFlatBranch(description, "describeCannotAppearInsideAnIt", "FlatSpec.scala", "of", 1) } } /** * Supports the registration of a “subject” being specified and tested. * *FlatSpec
. ** This field enables syntax such as the following subject registration: *
* ** behavior of "A Stack" * ^ ** ** For more information and examples of the use of the
*/ protected val behavior = new BehaviorWord /** * Class that supports the registration of tagged tests via thebehavior
field, see the main documentation * for this trait. *ItWord
instance * referenced fromFlatSpec
'sit
field. * ** This class enables syntax such as the following tagged test registration: *
* ** it should "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** It also enables syntax such as the following registration of an ignored, tagged test: *
* ** it should "pop values in last-in-first-out order" taggedAs(SlowTest) ignore { ... } * ^ ** ** In addition, it enables syntax such as the following registration of a pending, tagged test: *
* ** it should "pop values in last-in-first-out order" taggedAs(SlowTest) is (pending) * ^ ** ** For more information and examples of the use of the
*/ protected final class ItVerbStringTaggedAs(verb: String, name: String, tags: List[Tag]) { /** * Supports the registration of tagged tests in ait
field to register tagged tests, see * the Tagging tests section in the main documentation for traitFlatSpec
. * For examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of tagged test registration, see * the Tagging tests section in the main documentation for trait
*/ def in(testFun: => Unit) { registerTestToRun(verb + " " + name, tags, "in", testFun _) } /** * Supports the registration of pending, tagged tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" taggedAs(SlowTest) is (pending) * ^ ** ** For examples of pending test registration, see the Pending tests section in the main documentation * for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(verb + " " + name, tags, "is", testFun _) } /** * Supports the registration of ignored, tagged tests in aFlatSpec
. And for examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" taggedAs(SlowTest) ignore { ... } * ^ ** ** For examples of ignored test registration, see the Ignored tests section in the main documentation * for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(verb + " " + name, tags, "ignore", testFun _) } } /** * Class that supports test registration via theFlatSpec
. And for examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *ItWord
instance referenced fromFlatSpec
'sit
field. * ** This class enables syntax such as the following test registration: *
* ** it should "pop values in last-in-first-out order" in { ... } * ^ ** ** It also enables syntax such as the following registration of an ignored test: *
* ** it should "pop values in last-in-first-out order" ignore { ... } * ^ ** ** In addition, it enables syntax such as the following registration of a pending test: *
* ** it should "pop values in last-in-first-out order" is (pending) * ^ ** ** And finally, it also enables syntax such as the following tagged test registration: *
* ** it should "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For more information and examples of the use of the
*/ protected final class ItVerbString(verb: String, name: String) { /** * Supports the registration of tests in ait
field, see the main documentation * for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def in(testFun: => Unit) { registerTestToRun(verb + " " + name, List(), "in", testFun _) } /** * Supports the registration of pending tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" is (pending) * ^ ** ** For examples of pending test registration, see the Pending tests section in the main documentation * for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(verb + " " + name, List(), "is", testFun _) } /** * Supports the registration of ignored tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" ignore { ... } * ^ ** ** For examples of ignored test registration, see the Ignored tests section in the main documentation * for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(verb + " " + name, List(), "ignore", testFun _) } /** * Supports the registration of tagged tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of tagged test registration, see the Tagging tests section in the main documentation * for trait
*/ def taggedAs(firstTestTag: Tag, otherTestTags: Tag*) = { val tagList = firstTestTag :: otherTestTags.toList new ItVerbStringTaggedAs(verb, name, tagList) } } /** * Class that supports test (and shared test) registration via the instance referenced fromFlatSpec
. *FlatSpec
'sit
field. * ** This class enables syntax such as the following test registration: *
* ** it should "pop values in last-in-first-out order" in { ... } * ^ ** ** It also enables syntax such as the following shared test registration: *
* ** it should behave like nonEmptyStack(lastItemPushed) * ^ ** ** For more information and examples of the use of the
*/ protected final class ItWord { /** * Supports the registration of tests withit
field, see the main documentation * for this trait. *should
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** it should "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def should(string: String) = new ItVerbString("should", string) /** * Supports the registration of tests withFlatSpec
. *must
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** it must "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def must(string: String) = new ItVerbString("must", string) /** * Supports the registration of tests withFlatSpec
. *can
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** it can "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def can(string: String) = new ItVerbString("can", string) /** * Supports the registration of shared tests withFlatSpec
. *should
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** it should behave like nonFullStack(stackWithOneItem) * ^ ** ** For examples of shared tests, see the Shared tests section * in the main documentation for trait
*/ def should(behaveWord: BehaveWord) = behaveWord /** * Supports the registration of shared tests withFlatSpec
. *must
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** it must behave like nonFullStack(stackWithOneItem) * ^ ** ** For examples of shared tests, see the Shared tests section * in the main documentation for trait
*/ def must(behaveWord: BehaveWord) = behaveWord /** * Supports the registration of shared tests withFlatSpec
. *can
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** it can behave like nonFullStack(stackWithOneItem) * ^ ** ** For examples of shared tests, see the Shared tests section * in the main documentation for trait
*/ def can(behaveWord: BehaveWord) = behaveWord } /** * Supports test (and shared test) registration inFlatSpec
. *FlatSpec
s. * ** This field enables syntax such as the following test registration: *
* ** it should "pop values in last-in-first-out order" in { ... } * ^ ** ** It also enables syntax such as the following shared test registration: *
* ** it should behave like nonEmptyStack(lastItemPushed) * ^ ** ** For more information and examples of the use of the
*/ protected val it = new ItWord /** * Class that supports registration of ignored, tagged tests via theit
field, see the main documentation * for this trait. *IgnoreWord
instance referenced * fromFlatSpec
'signore
field. * ** This class enables syntax such as the following registration of an ignored, tagged test: *
* ** ignore should "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** In addition, it enables syntax such as the following registration of an ignored, tagged, pending test: *
* ** ignore should "pop values in last-in-first-out order" taggedAs(SlowTest) is (pending) * ^ ** ** Note: the
* *is
method is provided for completeness and design symmetry, given there's no way * to prevent changingis
toignore
and marking a pending test as ignored that way. * Although it isn't clear why someone would want to mark a pending test as ignored, it can be done. ** For more information and examples of the use of the
*/ protected final class IgnoreVerbStringTaggedAs(verb: String, name: String, tags: List[Tag]) { /** * Supports the registration of ignored, tagged tests in aignore
field, see the Ignored tests section * in the main documentation for traitFlatSpec
. For examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of the registration of ignored tests, see the Ignored tests section * in the main documentation for trait
*/ def in(testFun: => Unit) { registerTestToIgnore(verb + " " + name, tags, "in", testFun _) } /** * Supports the registration of ignored, tagged, pending tests in aFlatSpec
. For examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore must "pop values in last-in-first-out order" taggedAs(SlowTest) is (pending) * ^ ** ** Note: this
* *is
method is provided for completeness and design symmetry, given there's no way * to prevent changingis
toignore
and marking a pending test as ignored that way. * Although it isn't clear why someone would want to mark a pending test as ignored, it can be done. ** For examples of pending test registration, see the Pending tests section in the main documentation * for trait
*/ def is(testFun: => PendingNothing) { registerTestToIgnore(verb + " " + name, tags, "is", testFun _) } // Note: no def ignore here, so you can't put two ignores in the same line } /** * Class that supports registration of ignored tests via theFlatSpec
. For examples of the registration of ignored tests, * see the Ignored tests section * in the main documentation for traitFlatSpec
. For examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *IgnoreWord
instance referenced * fromFlatSpec
'signore
field. * ** This class enables syntax such as the following registration of an ignored test: *
* ** ignore should "pop values in last-in-first-out order" in { ... } * ^ ** ** In addition, it enables syntax such as the following registration of an ignored, pending test: *
* ** ignore should "pop values in last-in-first-out order" is (pending) * ^ ** ** Note: the
* *is
method is provided for completeness and design symmetry, given there's no way * to prevent changingis
toignore
and marking a pending test as ignored that way. * Although it isn't clear why someone would want to mark a pending test as ignored, it can be done. ** And finally, it also enables syntax such as the following ignored, tagged test registration: *
* ** ignore should "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For more information and examples of the use of the
*/ protected final class IgnoreVerbString(verb: String, name: String) { /** * Supports the registration of ignored tests in aignore
field, see the Ignored tests section * in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore must "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of the registration of ignored tests, see the Ignored tests section * in the main documentation for trait
*/ def in(testFun: => Unit) { registerTestToIgnore(verb + " " + name, List(), "in", testFun _) } /** * Supports the registration of ignored, pending tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore must "pop values in last-in-first-out order" is (pending) * ^ ** ** Note: this
* *is
method is provided for completeness and design symmetry, given there's no way * to prevent changingis
toignore
and marking a pending test as ignored that way. * Although it isn't clear why someone would want to mark a pending test as ignored, it can be done. ** For examples of pending test registration, see the Pending tests section in the main documentation * for trait
*/ def is(testFun: => PendingNothing) { registerTestToIgnore(verb + " " + name, List(), "is", testFun _) } /** * Supports the registration of ignored, tagged tests in aFlatSpec
. For examples of the registration of ignored tests, * see the Ignored tests section * in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of tagged test registration, see the Tagging tests section in the main documentation * for trait
*/ def taggedAs(firstTestTag: Tag, otherTestTags: Tag*) = { val tagList = firstTestTag :: otherTestTags.toList new IgnoreVerbStringTaggedAs(verb, name, tagList) } } /** * Class that supports registration of ignored tests via theFlatSpec
. For examples of the registration of ignored tests, * see the Ignored tests section * in the main documentation for traitFlatSpec
. *ItWord
instance * referenced fromFlatSpec
'signore
field. * ** This class enables syntax such as the following registration of an ignored test: *
* ** ignore should "pop values in last-in-first-out order" in { ... } * ^ ** ** For more information and examples of the use of the
*/ protected final class IgnoreWord { /** * Supports the registration of ignored tests withignore
field, see Ignored tests section * in the main documentation for this trait. *should
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore should "pop values in last-in-first-out order" in { ... } * ^ ** ** For more information and examples of the use of the
*/ def should(string: String) = new IgnoreVerbString("should", string) /** * Supports the registration of ignored tests withignore
field, see Ignored tests section * in the main documentation for traitFlatSpec
. *must
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore must "pop values in last-in-first-out order" in { ... } * ^ ** ** For more information and examples of the use of the
*/ def must(string: String) = new IgnoreVerbString("must", string) /** * Supports the registration of ignored tests withignore
field, see Ignored tests section * in the main documentation for traitFlatSpec
. *can
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** ignore can "pop values in last-in-first-out order" in { ... } * ^ ** ** For more information and examples of the use of the
*/ def can(string: String) = new IgnoreVerbString("can", string) } /** * Supports registration of ignored tests inignore
field, see Ignored tests section * in the main documentation for traitFlatSpec
. *FlatSpec
s. * ** This field enables syntax such as the following registration of an ignored test: *
* ** ignore should "pop values in last-in-first-out order" in { ... } * ^ ** ** For more information and examples of the use of the
*/ protected val ignore = new IgnoreWord /** * Class that supports the registration of tagged tests via theignore
field, see the Ignored tests section * in the main documentation for this trait. *TheyWord
instance * referenced fromFlatSpec
'sthey
field. * ** This class enables syntax such as the following tagged test registration: *
* ** they should "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** It also enables syntax such as the following registration of an ignored, tagged test: *
* ** they should "pop values in last-in-first-out order" taggedAs(SlowTest) ignore { ... } * ^ ** ** In addition, it enables syntax such as the following registration of a pending, tagged test: *
* ** they should "pop values in last-in-first-out order" taggedAs(SlowTest) is (pending) * ^ ** ** For more information and examples of the use of the
*/ protected final class TheyVerbStringTaggedAs(verb: String, name: String, tags: List[Tag]) { /** * Supports the registration of tagged tests in athey
field to register tagged tests, see * the Tagging tests section in the main documentation for traitFlatSpec
. * For examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of tagged test registration, see * the Tagging tests section in the main documentation for trait
*/ def in(testFun: => Unit) { registerTestToRun(verb + " " + name, tags, "in", testFun _) } /** * Supports the registration of pending, tagged tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" taggedAs(SlowTest) is (pending) * ^ ** ** For examples of pending test registration, see the Pending tests section in the main documentation * for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(verb + " " + name, tags, "is", testFun _) } /** * Supports the registration of ignored, tagged tests in aFlatSpec
. And for examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" taggedAs(SlowTest) ignore { ... } * ^ ** ** For examples of ignored test registration, see the Ignored tests section in the main documentation * for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(verb + " " + name, tags, "ignore", testFun _) } } /** * Class that supports test registration via theFlatSpec
. And for examples of tagged test registration, see * the Tagging tests section in the main documentation for traitFlatSpec
. *TheyWord
instance referenced fromFlatSpec
'sthey
field. * ** This class enables syntax such as the following test registration: *
* ** they should "pop values in last-in-first-out order" in { ... } * ^ ** ** It also enables syntax such as the following registration of an ignored test: *
* ** they should "pop values in last-in-first-out order" ignore { ... } * ^ ** ** In addition, it enables syntax such as the following registration of a pending test: *
* ** they should "pop values in last-in-first-out order" is (pending) * ^ ** ** And finally, it also enables syntax such as the following tagged test registration: *
* ** they should "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For more information and examples of the use of the
*/ protected final class TheyVerbString(verb: String, name: String) { /** * Supports the registration of tests in ait
field, see the main documentation * for traitFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def in(testFun: => Unit) { registerTestToRun(verb + " " + name, List(), "in", testFun _) } /** * Supports the registration of pending tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" is (pending) * ^ ** ** For examples of pending test registration, see the Pending tests section in the main documentation * for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(verb + " " + name, List(), "is", testFun _) } /** * Supports the registration of ignored tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" ignore { ... } * ^ ** ** For examples of ignored test registration, see the Ignored tests section in the main documentation * for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(verb + " " + name, List(), "ignore", testFun _) } /** * Supports the registration of tagged tests in aFlatSpec
. *FlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of tagged test registration, see the Tagging tests section in the main documentation * for trait
*/ def taggedAs(firstTestTag: Tag, otherTestTags: Tag*) = { val tagList = firstTestTag :: otherTestTags.toList new ItVerbStringTaggedAs(verb, name, tagList) } } /** * Class that supports test (and shared test) registration via the instance referenced fromFlatSpec
. *FlatSpec
'sit
field. * ** This class enables syntax such as the following test registration: *
* ** they should "pop values in last-in-first-out order" in { ... } * ^ ** ** It also enables syntax such as the following shared test registration: *
* ** they should behave like nonEmptyStack(lastItemPushed) * ^ ** ** For more information and examples of the use of the
*/ protected final class TheyWord { /** * Supports the registration of tests withit
field, see the main documentation * for this trait. *should
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** they should "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def should(string: String) = new ItVerbString("should", string) /** * Supports the registration of tests withFlatSpec
. *must
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** they must "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def must(string: String) = new ItVerbString("must", string) /** * Supports the registration of tests withFlatSpec
. *can
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** they can "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def can(string: String) = new ItVerbString("can", string) /** * Supports the registration of shared tests withFlatSpec
. *should
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** they should behave like nonFullStack(stackWithOneItem) * ^ ** ** For examples of shared tests, see the Shared tests section * in the main documentation for trait
*/ def should(behaveWord: BehaveWord) = behaveWord /** * Supports the registration of shared tests withFlatSpec
. *must
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** they must behave like nonFullStack(stackWithOneItem) * ^ ** ** For examples of shared tests, see the Shared tests section * in the main documentation for trait
*/ def must(behaveWord: BehaveWord) = behaveWord /** * Supports the registration of shared tests withFlatSpec
. *can
in aFlatSpec
. * ** This method supports syntax such as the following: *
* ** they can behave like nonFullStack(stackWithOneItem) * ^ ** ** For examples of shared tests, see the Shared tests section * in the main documentation for trait
*/ def can(behaveWord: BehaveWord) = behaveWord } /** * Supports test (and shared test) registration inFlatSpec
. *FlatSpec
s. * ** This field enables syntax such as the following test registration: *
* ** they should "pop values in last-in-first-out order" in { ... } * ^ ** ** It also enables syntax such as the following shared test registration: *
* ** they should behave like nonEmptyStack(lastItemPushed) * ^ ** ** For more information and examples of the use of the
*/ protected val they = new TheyWord /** * Class that supports test registration in shorthand form. * *it
field, see the main documentation * for this trait. ** For example, this class enables syntax such as the following test registration * in shorthand form: *
* ** "A Stack (when empty)" should "be empty" in { ... } * ^ ** ** This class also enables syntax such as the following ignored test registration * in shorthand form: *
* ** "A Stack (when empty)" should "be empty" ignore { ... } * ^ ** ** This class is used via an implicit conversion (named
* * @author Bill Venners */ protected final class InAndIgnoreMethods(resultOfStringPassedToVerb: ResultOfStringPassedToVerb) { import resultOfStringPassedToVerb.verb import resultOfStringPassedToVerb.rest /** * Supports the registration of tests in shorthand form. * *convertToInAndIgnoreMethods
) * fromResultOfStringPassedToVerb
. TheResultOfStringPassedToVerb
class * does not declare any methods namedin
, because the * type passed toin
differs in aFlatSpec
and afixture.FlatSpec
. * Afixture.FlatSpec
needs twoin
methods, one that takes a no-arg * test function and another that takes a one-arg test function (a test that takes a *Fixture
as its parameter). By constrast, aFlatSpec
needs * only onein
method that takes a by-name parameter. As a result, *FlatSpec
andfixture.FlatSpec
each provide an implicit conversion * fromResultOfStringPassedToVerb
to a type that provides the appropriate *in
methods. ** This method supports syntax such as the following: *
* ** "A Stack" must "pop values in last-in-first-out order" in { ... } * ^ ** ** For examples of test registration, see the main documentation * for trait
*/ def in(testFun: => Unit) { registerTestToRun(verb + " " + rest, List(), "in", testFun _) } /** * Supports the registration of ignored tests in shorthand form. * *FlatSpec
. ** This method supports syntax such as the following: *
* ** "A Stack" must "pop values in last-in-first-out order" ignore { ... } * ^ ** ** For examples of ignored test registration, see the Ignored tests section * in the main documentation for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(verb + " " + rest, List(), "ignore", testFun _) } } /** * Implicitly converts an object of typeFlatSpec
. *ResultOfStringPassedToVerb
to an *InAndIgnoreMethods
, to enablein
andignore
* methods to be invokable on that object. */ protected implicit def convertToInAndIgnoreMethods(resultOfStringPassedToVerb: ResultOfStringPassedToVerb) = new InAndIgnoreMethods(resultOfStringPassedToVerb) /** * Class that supports tagged test registration in shorthand form. * ** For example, this class enables syntax such as the following tagged test registration * in shorthand form: *
* ** "A Stack (when empty)" should "be empty" taggedAs() in { ... } * ^ ** ** This class also enables syntax such as the following tagged, ignored test registration * in shorthand form: *
* ** "A Stack (when empty)" should "be empty" taggedAs(SlowTest) ignore { ... } * ^ ** ** This class is used via an implicit conversion (named
* * @author Bill Venners */ protected final class InAndIgnoreMethodsAfterTaggedAs(resultOfTaggedAsInvocation: ResultOfTaggedAsInvocation) { import resultOfTaggedAsInvocation.verb import resultOfTaggedAsInvocation.rest import resultOfTaggedAsInvocation.{tags => tagsList} /** * Supports the registration of tagged tests in shorthand form. * *convertToInAndIgnoreMethodsAfterTaggedAs
) * fromResultOfTaggedAsInvocation
. TheResultOfTaggedAsInvocation
class * does not declare any methods namedin
, because the * type passed toin
differs in aFlatSpec
and afixture.FlatSpec
. * Afixture.FlatSpec
needs twoin
methods, one that takes a no-arg * test function and another that takes a one-arg test function (a test that takes a *Fixture
as its parameter). By constrast, aFlatSpec
needs * only onein
method that takes a by-name parameter. As a result, *FlatSpec
andfixture.FlatSpec
each provide an implicit conversion * fromResultOfTaggedAsInvocation
to a type that provides the appropriate *in
methods. ** This method supports syntax such as the following: *
* ** "A Stack" must "pop values in last-in-first-out order" taggedAs(SlowTest) in { ... } * ^ ** ** For examples of tagged test registration, see the Tagging tests section * in the main documentation for trait
*/ def in(testFun: => Unit) { registerTestToRun(verb + " " + rest, tagsList, "in", testFun _) } /** * Supports the registration of tagged, ignored tests in shorthand form. * *FlatSpec
. ** This method supports syntax such as the following: *
* ** "A Stack" must "pop values in last-in-first-out order" taggedAs(SlowTest) ignore { ... } * ^ ** ** For examples of ignored test registration, see the Ignored tests section * in the main documentation for trait
*/ def ignore(testFun: => Unit) { registerTestToIgnore(verb + " " + rest, tagsList, "ignore", testFun _) } } /** * Implicitly converts an object of typeFlatSpec
. * For examples of tagged test registration, see the Tagging tests section * in the main documentation for traitFlatSpec
. *ResultOfTaggedAsInvocation
to an *InAndIgnoreMethodsAfterTaggedAs
, to enablein
andignore
* methods to be invokable on that object. */ protected implicit def convertToInAndIgnoreMethodsAfterTaggedAs(resultOfTaggedAsInvocation: ResultOfTaggedAsInvocation) = new InAndIgnoreMethodsAfterTaggedAs(resultOfTaggedAsInvocation) /** * Supports the shorthand form of test registration. * ** For example, this method enables syntax such as the following: *
* ** "A Stack (when empty)" should "be empty" in { ... } * ^ ** ** This function is passed as an implicit parameter to a
*/ protected implicit val shorthandTestRegistrationFunction: (String, String, String) => ResultOfStringPassedToVerb = { (subject, verb, rest) => { behavior.of(subject) new ResultOfStringPassedToVerb(verb, rest) { def is(testFun: => PendingNothing) { registerTestToRun(verb + " " + rest, List(), "is", testFun _) } // Note, won't have an is method that takes fixture => PendingNothing one, because don't want // to say is (fixture => pending), rather just say is (pending) def taggedAs(firstTestTag: Tag, otherTestTags: Tag*) = { val tagList = firstTestTag :: otherTestTags.toList new ResultOfTaggedAsInvocation(verb, rest, tagList) { // "A Stack" should "bla bla" taggedAs(SlowTest) is (pending) // ^ def is(testFun: => PendingNothing) { registerTestToRun(verb + " " + rest, tags, "is", testFun _) } } } } } } /** * Supports the shorthand form of shared test registration. * *should
method * provided inShouldVerb
, amust
method * provided inMustVerb
, and acan
method * provided inCanVerb
. When invoked, this function registers the * subject description (the first parameter to the function) and returns aResultOfStringPassedToVerb
* initialized with the verb and rest parameters (the second and third parameters to * the function, respectively). ** For example, this method enables syntax such as the following in: *
* ** "A Stack (with one item)" should behave like nonEmptyStack(stackWithOneItem, lastValuePushed) * ^ ** ** This function is passed as an implicit parameter to a
*/ protected implicit val shorthandSharedTestRegistrationFunction: (String) => BehaveWord = { (left) => { behavior.of(left) new BehaveWord } } /** * 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 theshould
method * provided inShouldVerb
, amust
method * provided inMustVerb
, and acan
method * provided inCanVerb
. When invoked, this function registers the * subject description (the parameter to the function) and returns aBehaveWord
. *execute
* 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 * thisFlatSpec
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 method name * @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) { // TODO: This is how these were, but it needs attention. Mentions "it". registerIgnoredTest(specText, testFun, "ignoreCannotAppearInsideAnIt", "FlatSpec.scala", methodName, 1, testTags: _*) } /** * AMap
whose keys areString
tag names to which tests in thisFlatSpec
belong, and values * theSet
of test names that belong to each tag. If thisFlatSpec
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 thisFlatSpec
'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 thisFlatSpec
'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 executed.
* I.e., None
acts like a wildcard that means execute all relevant tests in this FlatSpec
.
* @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 tagsToInclude a Set
of String
tag names to include in the execution of this FlatSpec
* @param tagsToExclude a Set
of String
tag names to exclude in the execution of this FlatSpec
* @param configMap a Map
of key-value pairs that can be used by this FlatSpec
's executing tests.
* @throws NullPointerException if any of testName
, reporter
, stopper
, tagsToInclude
,
* tagsToExclude
, or configMap
is null
.
*/
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 FlatSpec
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 FlatSpec
:
*
* import org.scalatest.FlatSpec * * class StackSpec extends FlatSpec { * * "A Stack (when not empty)" must "allow me to pop" in {} * it must "not be empty" in {} * * "A Stack (when not full)" must "allow me to push" in {} * it must "not be full" in {} * } ** *
* Invoking testNames
on this FlatSpec
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 empty) must not be empty" * "A Stack (when not full) must allow me to push" * "A Stack (when not full) must not be full" **/ 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
FlatSpec
s.
*
* * This field supports syntax such as the following: *
* ** it should behave like nonFullStack(stackWithOneItem) * ^ ** *
* For more information and examples of the use of behave
, see the Shared tests section
* in the main documentation for this trait.
*