org.scalatest.fixture.FreeSpec.scala Maven / Gradle / Ivy
Show all versions of scalatest_2.9.0 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.fixture import org.scalatest._ import FixtureNodeFamily._ import verb.{CanVerb, ResultOfAfterWordApplication, ShouldVerb, BehaveWord, MustVerb, StringVerbBlockRegistration} 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 org.scalatest.Suite.anErrorThatShouldCauseAnAbort import org.scalatest.Suite.autoTagClassAnnotations /** * A sister trait to
, see the Shared tests section * in the main documentation for traitorg.scalatest.FreeSpec
that can pass a fixture object into its tests. * ** *
* Recommended Usage: * Use trait fixture.FreeSpec
in situations for whichFreeSpec
* would be a good choice, when all or most tests need the same fixture objects * that must be cleaned up afterwords. Note:fixture.FreeSpec
is intended for use in special situations, with traitFreeSpec
used for general needs. For * more insight into wherefixture.FreeSpec
fits in the big picture, see thewithFixture(OneArgTest)
subsection of the Shared fixtures section in the documentation for traitFreeSpec
. ** Trait
* *fixture.FreeSpec
behaves similarly to traitorg.scalatest.FreeSpec
, except that tests may have a * fixture parameter. The type of the * fixture parameter is defined by the abstractFixtureParam
type, which is declared as a member of this trait. * This trait also declares an abstractwithFixture
method. ThiswithFixture
method * takes aOneArgTest
, which is a nested trait defined as a member of this trait. *OneArgTest
has anapply
method that takes aFixtureParam
. * Thisapply
method is responsible for running a test. * This trait'srunTest
method delegates the actual running of each test towithFixture(OneArgTest)
, passing * in the test code to run via theOneArgTest
argument. ThewithFixture(OneArgTest)
method (abstract in this trait) is responsible * for creating the fixture argument and passing it to the test function. ** Subclasses of this trait must, therefore, do three things differently from a plain old
* *org.scalatest.FreeSpec
: **
* *- define the type of the fixture parameter by specifying type
*FixtureParam
- define the
*withFixture(OneArgTest)
method- write tests that take a fixture parameter
*- (You can also define tests that don't take a fixture parameter.)
** If the fixture you want to pass into your tests consists of multiple objects, you will need to combine * them into one object to use this trait. One good approach to passing multiple fixture objects is * to encapsulate them in a case class. Here's an example: *
* ** case class F(file: File, writer: FileWriter) * type FixtureParam = F ** ** To enable the stacking of traits that define
* *withFixture(NoArgTest)
, it is a good idea to let *withFixture(NoArgTest)
invoke the test function instead of invoking the test * function directly. To do so, you'll need to convert theOneArgTest
to aNoArgTest
. You can do that by passing * the fixture object to thetoNoArgTest
method ofOneArgTest
. In other words, instead of * writing “test(theFixture)
”, you'd delegate responsibility for * invoking the test function to thewithFixture(NoArgTest)
method of the same instance by writing: ** withFixture(test.toNoArgTest(theFixture)) ** ** Here's a complete example: *
* ** package org.scalatest.examples.freespec.oneargtest * * import org.scalatest.fixture * import java.io._ * * class ExampleSpec extends fixture.FreeSpec { * * case class F(file: File, writer: FileWriter) * type FixtureParam = F * * def withFixture(test: OneArgTest) { * * // create the fixture * val file = File.createTempFile("hello", "world") * val writer = new FileWriter(file) * val theFixture = F(file, writer) * * try { * writer.write("ScalaTest is ") // set up the fixture * withFixture(test.toNoArgTest(theFixture)) // "loan" the fixture to the test * } * finally writer.close() // clean up the fixture * } * * "Testing" - { * "should be easy" in { f => * f.writer.write("easy!") * f.writer.flush() * assert(f.file.length === 18) * } * * "should be fun" in { f => * f.writer.write("fun!") * f.writer.flush() * assert(f.file.length === 17) * } * } * } ** ** If a test fails, the
* *OneArgTest
function will complete abruptly with an exception describing the failure. * To ensure clean up happens even if a test fails, you should invoke the test function from inside atry
block and do the cleanup in a *finally
clause, as shown in the previous example. *Sharing fixtures across classes
* ** If multiple test classes need the same fixture, you can define the
* *FixtureParam
andwithFixture(OneArgTest)
implementations * in a trait, then mix that trait into the test classes that need it. For example, if your application requires a database and your integration tests * use that database, you will likely have many test classes that need a database fixture. You can create a "database fixture" trait that creates a * database with a unique name, passes the connector into the test, then removes the database once the test completes. This is shown in the following example: ** package org.scalatest.examples.fixture.freespec.sharing * * import java.util.concurrent.ConcurrentHashMap * import org.scalatest.fixture * import DbServer._ * import java.util.UUID.randomUUID * * object DbServer { // Simulating a database server * type Db = StringBuffer * private val databases = new ConcurrentHashMap[String, Db] * def createDb(name: String): Db = { * val db = new StringBuffer * databases.put(name, db) * db * } * def removeDb(name: String) { * databases.remove(name) * } * } * * trait DbFixture { this: fixture.Suite => * * type FixtureParam = Db * * // Allow clients to populate the database after * // it is created * def populateDb(db: Db) {} * * def withFixture(test: OneArgTest) { * val dbName = randomUUID.toString * val db = createDb(dbName) // create the fixture * try { * populateDb(db) // setup the fixture * withFixture(test.toNoArgTest(db)) // "loan" the fixture to the test * } * finally removeDb(dbName) // clean up the fixture * } * } * * class ExampleSpec extends fixture.FreeSpec with DbFixture { * * override def populateDb(db: Db) { // setup the fixture * db.append("ScalaTest is ") * } * * "Testing" - { * "should be easy" in { db => * db.append("easy!") * assert(db.toString === "ScalaTest is easy!") * } * * "should be fun" in { db => * db.append("fun!") * assert(db.toString === "ScalaTest is fun!") * } * } * * // This test doesn't need a Db * "Test code" - { * "should be clear" in { () => * val buf = new StringBuffer * buf.append("ScalaTest code is ") * buf.append("clear!") * assert(buf.toString === "ScalaTest code is clear!") * } * } * } ** ** Often when you create fixtures in a trait like
* *DbFixture
, you'll still need to enable individual test classes * to "setup" a newly created fixture before it gets passed into the tests. A good way to accomplish this is to pass the newly * created fixture into a setup method, likepopulateDb
in the previous example, before passing it to the test * function. Classes that need to perform such setup can override the method, as doesExampleSpec
. ** If a test doesn't need the fixture, you can indicate that by providing a no-arg instead of a one-arg function, as is done in the * third test in the previous example, “
* *Test code should be clear
”. In other words, instead of starting your function literal * with something like “db =>
”, you'd start it with “() =>
”. For such tests,runTest
* will not invokewithFixture(OneArgTest)
. It will instead directly invokewithFixture(NoArgTest)
. ** Both examples shown above demonstrate the technique of giving each test its own "fixture sandbox" to play in. When your fixtures * involve external side-effects, like creating files or databases, it is a good idea to give each file or database a unique name as is * done in these examples. This keeps tests completely isolated, allowing you to run them in parallel if desired. You could mix *
* * @author Bill Venners */ @Finders(Array("org.scalatest.finders.FreeSpecFinder")) trait FreeSpec extends Suite { thisSuite => private final val engine = new FixtureEngine[FixtureParam]("concurrentFixtureFreeSpecMod", "FixtureFreeSpec") import engine._ private[scalatest] val sourceFileName = "FreeSpec.scala" /** * Returns anParallelTestExecution
into either of theseExampleSpec
classes, and the tests would run in parallel just fine. *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 *fixture.FreeSpec
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 * thisFreeSpec
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 registerTestToRun(specText: String, testTags: List[Tag], methodName: String, testFun: FixtureParam => Any) { registerTest(specText, testFun, "itCannotAppearInsideAnotherIt", sourceFileName, methodName, 4, -3, None, None, None, testTags: _*) } /** * Register a test to ignore, which has the given spec text, optional tags, and test function value that takes no arguments. * This method will register the test for later ignoring via an invocation of one of theexecute
* methods. This method exists to make it easy to ignore an existing test by changing the call toit
* toignore
without deleting or commenting out the actual test code. The test will not be executed, but a * report will be sent that indicates the test was ignored. The name of the test will be a concatenation of the text of all surrounding describers, * from outside in, and the passed spec text, with one space placed between each item. (See the documenation * fortestNames
for an example.) The resulting test name must not have been registered previously on * thisFreeSpec
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: FixtureParam => Any) { registerIgnoredTest(specText, testFun, "ignoreCannotAppearInsideAnIt", sourceFileName, methodName, 4, -3, None, testTags: _*) } /* private def registerBranch(description: String, childPrefix: Option[String], fun: () => Unit) { // TODO: Fix the resource name and method name registerNestedBranch(description, childPrefix, fun(), "describeCannotAppearInsideAnIt", sourceFileName, "describe") } */ /** * Class that supports the registration of tagged tests. * ** Instances of this class are returned by the
* * @author Bill Venners */ protected final class ResultOfTaggedAsInvocationOnString(specText: String, tags: List[Tag]) { /** * Supports tagged test registration. * *taggedAs
method of * classFreeSpecStringWrapper
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) in { fixture => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def in(testFun: FixtureParam => Any) { registerTestToRun(specText, tags, "in", testFun) } /** * Supports tagged test registration, for tests that don't take a fixture. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) in { () => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def in(testFun: () => Any) { registerTestToRun(specText, tags, "in", new NoArgTestWrapper(testFun)) } /** * Supports registration of tagged, pending tests. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) is (pending) * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(specText, tags, "is", unusedFixtureParam => testFun) } /** * Supports registration of tagged, ignored tests. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) ignore { fixture => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def ignore(testFun: FixtureParam => Any) { registerTestToIgnore(specText, tags, "ignore", testFun) } /** * Supports registration of tagged, ignored tests that take no fixture parameter. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) ignore { () => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def ignore(testFun: () => Any) { registerTestToIgnore(specText, tags, "ignore", new NoArgTestWrapper(testFun)) } } /** * A class that via an implicit conversion (namedFreeSpec
. *convertToFreeSpecStringWrapper
) enables * methodswhen
,that
,in
,is
,taggedAs
* andignore
to be invoked onString
s. * ** This class provides much of the syntax for
* * @author Bill Venners */ protected final class FreeSpecStringWrapper(string: String) { // TODO: Fill in Scaladoc def - (fun: => Unit) { registerNestedBranch(string, None, fun, "describeCannotAppearInsideAnIt", sourceFileName, "-", 3, -2, None) } /** * Supports test registration. * *fixture.FreeSpec
, however, it does not add * the verb methods (should
,must
, andcan
) toString
. * Instead, these are added via theShouldVerb
,MustVerb
, andCanVerb
* traits, whichfixture.FreeSpec
mixes in, to avoid a conflict with implicit conversions provided * inShouldMatchers
andMustMatchers
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" in { fixture => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def in(testFun: FixtureParam => Any) { registerTestToRun(string, List(), "in", testFun) } /** * Supports registration of tests that take no fixture. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" in { () => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def in(testFun: () => Any) { registerTestToRun(string, List(), "in", new NoArgTestWrapper(testFun)) } /** * Supports pending test registration. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" is (pending) * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def is(testFun: => PendingNothing) { registerTestToRun(string, List(), "is", unusedFixtureParam => testFun) } /** * Supports ignored test registration. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" ignore { fixture => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def ignore(testFun: FixtureParam => Any) { registerTestToIgnore(string, List(), "ignore", testFun) } /** * Supports registration of ignored tests that take no fixture. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" ignore { () => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def ignore(testFun: () => Any) { registerTestToIgnore(string, List(), "ignore", new NoArgTestWrapper(testFun)) } /** * Supports tagged test registration. * *FreeSpec
. ** For example, this method supports syntax such as the following: *
* ** "complain on peek" taggedAs(SlowTest) in { fixture => ... } * ^ ** ** For more information and examples of this method's use, see the main documentation for trait
*/ def taggedAs(firstTestTag: Tag, otherTestTags: Tag*) = { val tagList = firstTestTag :: otherTestTags.toList new ResultOfTaggedAsInvocationOnString(string, tagList) } } /** * Implicitly convertsFreeSpec
. *String
s toFreeSpecStringWrapper
, which enables * methodswhen
,that
,in
,is
,taggedAs
* andignore
to be invoked onString
s. */ protected implicit def convertToFreeSpecStringWrapper(s: String) = new FreeSpecStringWrapper(s) /** * AMap
whose keys areString
tag names to which tests in thisFreeSpec
belong, and values * theSet
of test names that belong to each tag. If thisFreeSpec
contains no tags, this method returns an emptyMap
. * ** This trait's implementation returns tags that were passed as strings contained in
* *Tag
objects passed to * methodstest
andignore
. ** In addition, this trait's implementation will also auto-tag tests with class level annotations. * For example, if you annotate @Ignore at the class level, all test methods in the class will be auto-annotated with @Ignore. *
*/ override def tags: Map[String, Set[String]] = autoTagClassAnnotations(atomic.get.tagsMap, this) /** * Run a test. This trait's implementation runs the test registered with the name specified by *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 args theArgs
for this run * * @throws NullPointerException if any oftestName
,reporter
,stopper
, orconfigMap
* isnull
. */ protected override def runTest(testName: String, args: Args): Status = { def invokeWithFixture(theTest: TestLeaf) { theTest.testFun match { case wrapper: NoArgTestWrapper[_] => withFixture(new FixturelessTestFunAndConfigMap(testName, wrapper.test, args.configMap)) case fun => withFixture(new TestFunAndConfigMap(testName, fun, args.configMap)) } } runTestImpl(thisSuite, testName, args, true, invokeWithFixture) } /** ** Run zero to many of this
* *FreeSpec
'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 aSet
* that should be excluded (tagsToExclude
), when deciding which of thisSuite
's tests to execute. * IftagsToInclude
is empty, all tests will be executed * except those those belonging to tags listed in thetagsToExclude
Set
. IftagsToInclude
is non-empty, only tests * belonging to tags mentioned intagsToInclude
, and not mentioned intagsToExclude
* will be executed. However, iftestName
isSome
,tagsToInclude
andtagsToExclude
are essentially ignored. * Only iftestName
isNone
willtagsToInclude
andtagsToExclude
be consulted to * determine which of the tests named in thetestNames
Set
should be run. For more information on trait tags, see the main documentation for this trait. ** If
* *testName
isNone
, this trait's implementation of this method * invokestestNames
on thisSuite
to get aSet
of names of tests to potentially execute. * (AtestNames
value ofNone
essentially acts as a wildcard that means all tests in * thisSuite
that are selected bytagsToInclude
andtagsToExclude
should be executed.) * For each test in thetestName
Set
, in the order * they appear in the iterator obtained by invoking theelements
method on theSet
, this trait's implementation * of this method checks whether the test should be run based on thetagsToInclude
andtagsToExclude
Set
s. * If so, this implementation invokesrunTest
, passing in: **
* * @param testName an optional name of one test to execute. If- *
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 itNone
, all relevant tests should be executed. * I.e.,None
acts like a wildcard that means execute all relevant tests in thisFreeSpec
. * @param args theArgs
for this run * * @throws NullPointerException if any oftestName
,reporter
,stopper
,tagsToInclude
, *tagsToExclude
, orconfigMap
isnull
. */ protected override def runTests(testName: Option[String], args: Args): Status = { runTestsImpl(thisSuite, testName, args, info, true, runTest) } /** * An immutableSet
of test names. If thisfixture.FreeSpec
contains no tests, this method returns an * emptySet
. * ** 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. *
*/ 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], args: Args): Status = { runImpl(thisSuite, testName, args, super.run) } /** * Supports shared test registration infixture.FreeSpec
s. * ** This field enables syntax such as the following: *
* ** behave like nonFullStack(stackWithOneItem) * ^ ** ** For more information and examples of the use of
behave FreeSpec
. * */ protected val behave = new BehaveWord /** * Suite style name. */ final override val styleName: String = "org.scalatest.fixture.FreeSpec" override def testDataFor(testName: String, theConfigMap: Map[String, Any] = Map.empty): TestData = createTestDataFor(testName, theConfigMap, this) }