org.scalatest.FunSuite.scala Maven / Gradle / Ivy
Show all versions of scalatest_2.11.0-M3 Show documentation
/* * Copyright 2001-2011 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 scala.collection.immutable.ListSet import java.util.ConcurrentModificationException import java.util.concurrent.atomic.AtomicReference import org.scalatest.exceptions.StackDepthExceptionHelper.getStackDepth import org.scalatest.events._ import Suite.anErrorThatShouldCauseAnAbort import Suite.checkRunTestParamsForNull /** * A suite of tests in which each test is represented as a function value. The “
Buffer. If you wantedFun
” inFunSuite
stands * for “function.” Here's an exampleFunSuite
: * ** import org.scalatest.FunSuite * * class ExampleSuite extends FunSuite { * * test("addition") { * val sum = 1 + 1 * assert(sum === 2) * } * * test("subtraction") { * val diff = 4 - 1 * assert(diff === 3) * } * } ** ** “
* *test
” is a method, defined inFunSuite
, which will be invoked * by the primary constructor ofExampleSuite
. You specify the name of the test as * a string between the parentheses, and the test code itself between curly braces. * The test code is a function passed as a by-name parameter totest
, which registers * it for later execution. One benefit ofFunSuite
compared toSuite
is you need not name all your * tests starting with “test
.” In addition, you can more easily give long names to * your tests, because you need not encode them in camel case. ** A
* *FunSuite
's lifecycle has two phases: the registration phase and the * ready phase. It starts in registration phase and enters ready phase the first time *run
is called on it. It then remains in ready phase for the remainder of its lifetime. ** Tests can only be registered with the
* *test
method while theFunSuite
is * in its registration phase. Any attempt to register a test after theFunSuite
has * entered its ready phase, i.e., afterrun
has been invoked on theFunSuite
, * will be met with a thrownTestRegistrationClosedException
. The recommended style * of usingFunSuite
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
* *FunSuite
. *Ignored tests
* ** To support the common use case of “temporarily” disabling a test, with the * good intention of resurrecting the test at a later time,
* *FunSuite
provides registration * methods that start withignore
instead oftest
. For example, to temporarily * disable the test namedaddition
, just change “test
” into “ignore
,” like this: ** import org.scalatest.FunSuite * * class ExampleSuite extends FunSuite { * * ignore("addition") { * val sum = 1 + 1 * assert(sum === 2) * } * * test("subtraction") { * val diff = 4 - 1 * assert(diff === 3) * } * } ** ** If you run this version of
* *ExampleSuite
with: ** scala> (new ExampleSuite).execute() ** ** It will run only
* *subtraction
and report thataddition
was ignored: ** ExampleSuite: * - addition !!! IGNORED !!! * - 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 byFunSuite
'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 one of itsapply
methods. * TheInformer
will then pass the information to theReporter
via anInfoProvided
event. * Here's an example: ** import org.scalatest.FunSuite * * class ExampleSuite extends FunSuite { * * test("addition") { * val sum = 1 + 1 * assert(sum === 2) * assert(sum + 2 === 4) * info("Addition seems to work") * } * } ** * If you run thisFunSuite
from the interpreter, you will see the following message * included in the printed report: * ** ExampleSuite: * - addition * + Addition seems to work *
* *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. ** Although pending tests may be used more often in specification-style suites, such as *
* *org.scalatest.FunSpec
, you can also use it inFunSuite
, like this: ** import org.scalatest.FunSuite * * class ExampleSuite extends FunSuite { * * test("addition") { * val sum = 1 + 1 * assert(sum === 2) * assert(sum + 2 === 4) * } * * test("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 ofExampleSuite
with: ** scala> (new ExampleSuite).execute() ** ** It will run both tests, but report that
* *subtraction
is pending. You'll see: ** ExampleSuite: * - addition * - subtraction (pending) ** *Tagging tests
* ** A
* *FunSuite
's tests may be classified into groups by tagging them with string names. * As with any suite, when executing aFunSuite
, groups of tests can * optionally be included and/or excluded. To tag aFunSuite
'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 yourFunSuite
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 forFunSuite
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
* *FunSuite
tests into groups like this: ** import org.scalatest.FunSuite * * class ExampleSuite extends FunSuite { * * test("addition", SlowTest) { * val sum = 1 + 1 * assert(sum === 2) * } * * test("subtraction", SlowTest, DbTest) { * val diff = 4 - 1 * assert(diff === 3) * } * } ** ** 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 * previousExampleSuite
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.FunSuite * import collection.mutable.ListBuffer * * class ExampleSuite extends FunSuite { * * def fixture = * new { * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * } * * test("easy") { * val f = fixture * f.builder.append("easy!") * assert(f.builder.toString === "ScalaTest is easy!") * assert(f.buffer.isEmpty) * f.buffer += "sweet" * } * * test("fun") { * 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.FunSuite * import collection.mutable.ListBuffer * * class ExampleSuite extends FunSuite { * * trait Fixture { * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * } * * test("easy") { * new Fixture { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * } * * test("fun") { * 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.FunSuite * import org.scalatest.OneInstancePerTest * import collection.mutable.ListBuffer * * class ExampleSuite extends FunSuite with OneInstancePerTest { * * val builder = new StringBuilder("ScalaTest is ") * val buffer = new ListBuffer[String] * * test("easy") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * test("fun") { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * } * } ** ** 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.FunSuite * import org.scalatest.BeforeAndAfter * import collection.mutable.ListBuffer * * class ExampleSuite extends FunSuite with BeforeAndAfter { * * val builder = new StringBuilder * val buffer = new ListBuffer[String] * * before { * builder.append("ScalaTest is ") * } * * after { * builder.clear() * buffer.clear() * } * * test("easy") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * test("fun") { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * } * } ** *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.FunSuite * import collection.mutable.ListBuffer * * class ExampleSuite extends FunSuite { * * 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() * } * } * * test("easy") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * test("fun") { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * 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.FunSuite
(from theorg.scalatest.fixture
package) instead of *FunSuite
. Each test in afixture.FunSuite
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 ExampleSuite extends fixture.FunSuite { * * 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 * } * } * * test("easy") { writer => * writer.write("Hello, test!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * * test("fun") { writer => * writer.write("Hi, test!") * writer.flush() * assert(new File(tmpFile).length === 9) * } * } ** ** For more information, see the documentation for
* *fixture.FunSuite
. *Providing different fixtures to different tests
* ** If different tests in the same
* *FunSuite
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.FunSuite * * class ExampleSuite extends FunSuite { * * 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 * } * } * * test("productive") { // This test needs the StringBuilder fixture * new Builder { * builder.append("productive!") * assert(builder.toString === "ScalaTest is productive!") * } * } * * test("readable") { // This test needs the ListBuffer[String] fixture * new Buffer { * buffer += ("readable!") * assert(buffer === List("ScalaTest", "is", "readable!")) * } * } * * test("friendly") { // This test needs the FileWriter fixture * withWriter { writer => * writer.write("Hello, user!") * writer.flush() * assert(new File(tmpFile).length === 12) * } * } * * test("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!")) * } * } * * test("composable") { // 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,
* *productive
uses only theStringBuilder
fixture, so it just instantiates * anew Builder
, whereasreadable
uses only theListBuffer
fixture, so it just intantiates * anew Buffer
.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:
* *clear and concise
needs both theStringBuilder
and the *ListBuffer
, so it instantiates a class that mixes in both fixture traits withnew Builder with Buffer
. *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.FunSuite
'swithFixture(OneArgTest)
method.fixture.FunSuite
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: *
* ** test("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.FunSuite * 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 ExampleSuite extends FunSuite with Builder with Buffer { * * test("easy") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * test("fun") { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * buffer += "clear" * } * } ** ** By mixing in both the
Builder
andBuffer
traits,ExampleSuite
gets both fixtures, which will be * initialized before each test and cleaned up after. The order the traits are mixed together determines the order of execution. * In this case,Builder
is "super" toBuffer
to be "super" * toBuilder
, you need only switch the order you mix them together, like this: * * ** class Example2Suite extends FunSuite with Buffer with Builder ** ** And if you only need one fixture you mix in only that trait: *
* ** class Example3Suite extends FunSuite 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.FunSuite * import org.scalatest.BeforeAndAfterEach * import collection.mutable.ListBuffer * * trait Builder extends BeforeAndAfterEach { this: Suite => * * val builder = new StringBuilder * * override def beforeEach() { * builder.append("ScalaTest is ") * super.beforeEach() // To be stackable, must call super.beforeEach * } * * override def afterEach() { * try { * super.afterEach() // To be stackable, must call super.afterEach * } * finally { * builder.clear() * } * } * } * * trait Buffer extends BeforeAndAfterEach { this: Suite => * * val buffer = new ListBuffer[String] * * override def afterEach() { * try { * super.afterEach() // To be stackable, must call super.afterEach * } * finally { * buffer.clear() * } * } * } * * class ExampleSuite extends FunSuite with Builder with Buffer { * * test("easy") { * builder.append("easy!") * assert(builder.toString === "ScalaTest is easy!") * assert(buffer.isEmpty) * buffer += "sweet" * } * * test("fun") { * builder.append("fun!") * assert(builder.toString === "ScalaTest is fun!") * assert(buffer.isEmpty) * 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
* *FunSuite
, you first place shared tests in * behavior functions. These behavior functions will be * invoked during the construction phase of anyFunSuite
that uses them, so that the tests they contain will * be registered as tests in thatFunSuite
. * 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 yourFunSuite
for stack, you'd invoke the * behavior function three times, passing in each of the three stack fixtures so that the shared tests are run for all three fixtures. ** You can define a behavior function that encapsulates these shared tests inside the
* *FunSuite
that uses them. If they are shared * between differentFunSuite
s, however, you could also define them in a separate trait that is mixed into * eachFunSuite
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 tests for non-full stacks: ** import org.scalatest.FunSuite * * trait FunSuiteStackBehaviors { this: FunSuite => * * def nonEmptyStack(createNonEmptyStack: => Stack[Int], lastItemAdded: Int) { * * test("empty is invoked on this non-empty stack: " + createNonEmptyStack.toString) { * val stack = createNonEmptyStack * assert(!stack.empty) * } * * test("peek is invoked on this non-empty stack: " + createNonEmptyStack.toString) { * val stack = createNonEmptyStack * val size = stack.size * assert(stack.peek === lastItemAdded) * assert(stack.size === size) * } * * test("pop is invoked on this non-empty stack: " + createNonEmptyStack.toString) { * val stack = createNonEmptyStack * val size = stack.size * assert(stack.pop === lastItemAdded) * assert(stack.size === size - 1) * } * } * * def nonFullStack(createNonFullStack: => Stack[Int]) { * * test("full is invoked on this non-full stack: " + createNonFullStack.toString) { * val stack = createNonFullStack * assert(!stack.full) * } * * test("push is invoked on this non-full stack: " + createNonFullStack.toString) { * val stack = createNonFullStack * val size = stack.size * stack.push(7) * assert(stack.size === size + 1) * assert(stack.peek === 7) * } * } * } ** ** Given these behavior functions, you could invoke them directly, but
* *FunSuite
offers a DSL for the purpose, * which looks like this: ** testsFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) * testsFor(nonFullStack(stackWithOneItem)) ** ** If you prefer to use an imperative style to change fixtures, for example by mixing in
* *BeforeAndAfterEach
and * reassigning 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: ** testsFor(nonEmptyStack) // assuming lastValuePushed is also in scope inside nonEmptyStack * testsFor(nonFullStack) ** ** The recommended style, however, is the functional, pass-all-the-needed-values-in style. Here's an example: *
* ** import org.scalatest.FunSuite * * class StackFunSuite extends FunSuite with FunSuiteStackBehaviors { * * // Stack fixture creation methods * def emptyStack = new Stack[Int] * * def fullStack = { * val stack = new Stack[Int] * for (i <- 0 until stack.MAX) * stack.push(i) * stack * } * * def stackWithOneItem = { * val stack = new Stack[Int] * stack.push(9) * stack * } * * def stackWithOneItemLessThanCapacity = { * val stack = new Stack[Int] * for (i <- 1 to 9) * stack.push(i) * stack * } * * val lastValuePushed = 9 * * test("empty is invoked on an empty stack") { * val stack = emptyStack * assert(stack.empty) * } * * test("peek is invoked on an empty stack") { * val stack = emptyStack * intercept[IllegalStateException] { * stack.peek * } * } * * test("pop is invoked on an empty stack") { * val stack = emptyStack * intercept[IllegalStateException] { * emptyStack.pop * } * } * * testsFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) * testsFor(nonFullStack(stackWithOneItem)) * * testsFor(nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed)) * testsFor(nonFullStack(stackWithOneItemLessThanCapacity)) * * test("full is invoked on a full stack") { * val stack = fullStack * assert(stack.full) * } * * testsFor(nonEmptyStack(fullStack, lastValuePushed)) * * test("push is invoked on a full stack") { * val stack = fullStack * intercept[IllegalStateException] { * stack.push(10) * } * } * } ** ** 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 StackFunSuite).execute() * StackFunSuite: * - empty is invoked on an empty stack * - peek is invoked on an empty stack * - pop is invoked on an empty stack * - empty is invoked on this non-empty stack: Stack(9) * - peek is invoked on this non-empty stack: Stack(9) * - pop is invoked on this non-empty stack: Stack(9) * - full is invoked on this non-full stack: Stack(9) * - push is invoked on this non-full stack: Stack(9) * - empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1) * - peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1) * - pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1) * - full is invoked on this non-full stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1) * - push is invoked on this non-full stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1) * - full is invoked on a full stack * - empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0) * - peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0) * - pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1, 0) * - push is invoked on a full stack *
* ** One thing to keep in mind when using shared tests is that in ScalaTest, each test in a suite must have a unique name. * If you register the same tests repeatedly in the same suite, one problem you may encounter is an exception at runtime * complaining that multiple tests are being registered with the same test name. * In a
* *FunSuite
there is no nesting construct analogous 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 *FunSuite
, you'll need to pass in a prefix or suffix string to add to each test name. You can pass this string * the same way you pass any other data needed by the shared tests, or just calltoString
on the shared fixture object. * This is the approach taken by the previousFunSuiteStackBehaviors
example. ** Given this
* *FunSuiteStackBehaviors
trait, calling it with thestackWithOneItem
fixture, like this: ** testsFor(nonEmptyStack(stackWithOneItem, lastValuePushed)) ** ** yields test names: *
* *
-
*
empty is invoked on this non-empty stack: Stack(9)
* peek is invoked on this non-empty stack: Stack(9)
* pop is invoked on this non-empty stack: Stack(9)
*
* Whereas calling it with the stackWithOneItemLessThanCapacity
fixture, like this:
*
* testsFor(nonEmptyStack(stackWithOneItemLessThanCapacity, lastValuePushed)) ** *
* yields different test names: *
* *-
*
empty is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
* peek is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
* pop is invoked on this non-empty stack: Stack(9, 8, 7, 6, 5, 4, 3, 2, 1)
*
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
* FunSuite
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 specified name, optional tags, and function value that takes no arguments.
* This method will register the test for later execution via an invocation of one of the run
* methods. The passed test name must not have been registered previously on
* this FunSuite
instance.
*
* @param testName the name of the test
* @param testTags the optional list of tags for this test
* @param testFun the test function
* @throws TestRegistrationClosedException if invoked after run
has been invoked on this suite
* @throws DuplicateTestNameException if a test with the same name has been registered previously
* @throws NotAllowedException if testName
had been registered previously
* @throws NullPointerException if testName
or any passed test tag is null
*/
protected def test(testName: String, testTags: Tag*)(testFun: => Unit) {
registerTest(testName, testFun _, "testCannotAppearInsideAnotherTest", "FunSuite.scala", "test", 2, None, None, testTags: _*)
}
/**
* Register a test to ignore, which has the specified name, optional tags, and function value that takes no arguments.
* This method will register the test for later ignoring via an invocation of one of the run
* methods. This method exists to make it easy to ignore an existing test by changing the call to test
* to ignore
without deleting or commenting out the actual test code. The test will not be run, but a
* report will be sent that indicates the test was ignored. The passed test name must not have been registered previously on
* this FunSuite
instance.
*
* @param testName the name of the test
* @param testTags the optional list of tags for this test
* @param testFun the test function
* @throws TestRegistrationClosedException if invoked after run
has been invoked on this suite
* @throws DuplicateTestNameException if a test with the same name has been registered previously
* @throws NotAllowedException if testName
had been registered previously
*/
protected def ignore(testName: String, testTags: Tag*)(testFun: => Unit) {
registerIgnoredTest(testName, testFun _, "ignoreCannotAppearInsideATest", "FunSuite.scala", "ignore", 1, testTags: _*)
}
/**
* An immutable Set
of test names. If this FunSuite
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. *
*/ 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: _*) } /** * Run a test. This trait's implementation runs the test registered with the name specified bytestName
.
*
* @param testName the name of one test to run.
* @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 the executing Suite
of tests.
* @throws IllegalArgumentException if testName
is defined but a test with that name does not exist on this FunSuite
* @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, true, invokeWithFixture)
}
/**
* A Map
whose keys are String
tag names to which tests in this FunSuite
belong, and values
* the Set
of test names that belong to each tag. If this FunSuite
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
.
*
FunSuite
's tests.
*
* @param testName an optional name of one test to run. If None
, all relevant tests should be run.
* I.e., None
acts like a wildcard that means run all relevant tests in this Suite
.
* @param reporter the Reporter
to which results will be reported
* @param stopper the Stopper
that will be consulted to determine whether to stop execution early.
* @param filter a Filter
with which to filter tests based on their tags
* @param configMap a Map
of key-value pairs that can be used by the executing Suite
of tests.
* @param distributor an optional Distributor
, into which to put nested Suite
s to be run
* by another entity, such as concurrently by a pool of threads. If None
, nested Suite
s will be run sequentially.
* @param tracker a Tracker
tracking Ordinal
s being fired by the current thread.
* @throws NullPointerException if any of the passed parameters is null
.
* @throws IllegalArgumentException if testName
is defined, but no test with the specified test name
* exists in this Suite
*/
protected override def runTests(testName: Option[String], reporter: Reporter, stopper: Stopper, filter: Filter,
configMap: Map[String, Any], distributor: Option[Distributor], tracker: Tracker) {
runTestsImpl(thisSuite, testName, reporter, stopper, filter, configMap, distributor, tracker, info, true, runTest)
}
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 tests.
*
*
* This method enables the following syntax for shared tests in a FunSuite
:
*
* testsFor(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 tests. For examples of shared tests, see the
* Shared tests section in the main documentation for this trait.
*