• Home
• org.scalatest
• scalatest_2.9.0
• 2.0.M6-SNAP3
• source code
• BeforeAndAfterEach.scala

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.scalatest.BeforeAndAfterEach.scala Maven / Gradle / Ivy

/*
 * Copyright 2001-2012 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

/**
 * Stackable trait that can be mixed into suites that need code executed before and after running each test.
 *
 * 

 * Recommended Usage:
 * Use trait BeforeAndAfterEach when you want to stack traits that perform side-effects before and/or after tests, rather
 * than at the beginning or end of tests, or when you need access to the config map or test name in the before and/or after code.
 * Note: For more insight into where BeforeAndAfterEach fits into the big picture, see the 
 * Shared fixtures section in the documentation for your chosen style trait.
 * 
 * 
 * 

 * A test fixture is composed of the objects and other artifacts (files, sockets, database
 * connections, etc.) tests use to do their work.
 * When multiple tests need to work with the same fixtures, it is important to try and avoid
 * duplicating the fixture code across those tests. The more code duplication you have in your
 * tests, the greater drag the tests will have on refactoring the actual production code.
 * Trait BeforeAndAfterEach offers one way to eliminate such code duplication:
 * a beforeEach method that will be run before each test (like JUnit's setUp),
 * and an afterEach method that will be run after (like JUnit's tearDown).
 * 
 *
 * 

 * Here's an example:
 * 
 *
 * 
 * package org.scalatest.examples.flatspec.composingbeforeandaftereach
 * 
 * import org.scalatest._
 * 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 your super.beforeEach call at the end of each
 * beforeEach method, and the super.afterEach call at the beginning of each afterEach
 * method, as shown in the previous example. It is a good idea to invoke super.afterEach in a try
 * block and perform cleanup in a finally clause, as shown in the previous example, because this ensures the
 * cleanup code is performed even if super.afterEach throws an exception.
 * 
 *
 * 

 * Besides enabling trait stacking, the other main advantage of BeforeAndAfterEach over BeforeAndAfter is
 * that BeforeAndAfterEach allows you to make use of test data (the test name and the config map) in your before
 * and/or after code, whereas BeforeAndAfter does not. To access the test data, simply override the form of
 * beforeEach and/or afterEach that takes a TestData parameter, like this.
 * 
 *
 * 
 *   override def beforeEach(td: TestData) {
 *     // Can now use the test data in your "before" code:
 *     //   td.name is the name of the test
 *     //   td.configMap is the config map passed to runTest
 *   }
 *
 *   override def afterEach(td: TestData) {
 *     // Can now use the test data in your "after" code:
 *     //   td.name is the name of the test
 *     //   td.configMap is the config map passed to runTest
 *   }
 * 
 *
 * 

 * The main disadvantage of BeforeAndAfterEach compared to BeforeAndAfter is that BeforeAndAfterEach
 * requires more boilerplate. If you don't need trait stacking or access to the test data, use BeforeAndAfter instead
 * of BeforeAndAfterEach.
 * 
 *
 * @author Bill Venners
 */
trait BeforeAndAfterEach extends SuiteMixin {

  this: Suite =>

  /**
   * Defines a method to be run before each of this suite's tests.
   *
   * 

   * This trait's implementation
   * of runTest invokes the overloaded form of this method that
   * takes a configMap before running
   * each test. This trait's implementation of that beforeEach(Map[String, Any]) method simply invokes this
   * beforeEach() method. Thus this method can be used to set up a test fixture
   * needed by each test, when you don't need anything from the configMap.
   * This trait's implementation of this method does nothing.
   * 
   */
  protected def beforeEach() = ()

  /**
   * This overloaded form of beforeEach has been deprecated and will
   * be removed in a future version of ScalaTest. Please use beforeEach(TestData) instead.
   *
   * 

   * During the deprecation cycle, this trait's implementation
   * of beforeEach(TestData) invokes will this method.
   * This trait's implementation of this method invokes the
   * overloaded form of beforeEach that takes no configMap.
   * 
   */
  @deprecated("Please use beforeEach(TestData) instead.")
  protected def beforeEach(configMap: Map[String, Any]) {
    beforeEach()
  }
  
  /**
   * Defines a method (that takes a TestData) to be run before
   * each of this suite's tests.
   *
   * 

   * This trait's implementation
   * of runTest invokes this method before running
   * each test (passing in the configMap passed to it), thus this
   * method can be used to set up a test fixture
   * needed by each test. This trait's implementation of this method invokes the
   * overloaded form of beforeEach that takes configMap.
   * After the deprecation cycle, this method will invoke the no-arg form of beforeEach.
   * 
   */
  protected def beforeEach(testData: TestData) {
    beforeEach(testData.configMap)
  }

  /**
   * Defines a method to be run after each of this suite's tests.
   *
   * 

   * This trait's implementation
   * of runTest invokes the overloaded form of this method that
   * takes a configMap map after running
   * each test. This trait's implementation of that afterEach(Map[String, Any]) method simply invokes this
   * afterEach() method. Thus this method can be used to tear down a test fixture
   * needed by each test, when you don't need anything from the configMap.
   * This trait's implementation of this method does nothing.
   * 
   */
  protected def afterEach() = ()

  /**
   * This overloaded form of afterEach has been deprecated and will
   * be removed in a future version of ScalaTest. Please use afterEach(TestData) instead.
   *
   * 

   * During the deprecation cycle, this trait's implementation
   * of afterEach(TestData) invokes will this method.
   * This trait's implementation of this method invokes the
   * overloaded form of afterEach that takes no configMap.
   * 
   */
  @deprecated("Please use afterEach(TestData) instead.")
  protected def afterEach(configMap: Map[String, Any]) {
    afterEach()
  }
  
  /**
   * Defines a method (that takes a TestData) to be run after
   * each of this suite's tests.
   *
   * 

   * This trait's implementation
   * of runTest invokes this method after running
   * each test (passing in a TestData containing the configMap passed
   * to it), thus this method can be used to tear down a test fixture
   * needed by each test. This trait's implementation of this method invokes the
   * overloaded form of afterEach that takes configMap.
   * After the deprecation cycle, this method will invoke the no-arg form of afterEach.
   * 
   */
  protected def afterEach(testData: TestData) {
    afterEach(testData.configMap)
  }

  /**
   * Run a test surrounded by calls to beforeEach and afterEach.
   *
   * 

   * This trait's implementation of this method ("this method") invokes
   * beforeEach(configMap)
   * before running each test and afterEach(configMap)
   * after running each test. It runs each test by invoking super.runTest, passing along
   * the two parameters passed to it.
   * 
   * 
   * 

   * If any invocation of beforeEach completes abruptly with an exception, this
   * method will complete abruptly with the same exception. If any call to
   * super.runTest completes abruptly with an exception, this method
   * will complete abruptly with the same exception, however, before doing so, it will
   * invoke afterEach. If afterEach also completes abruptly with an exception, this
   * method will nevertheless complete abruptly with the exception previously thrown by super.runTest.
   * If super.runTest returns normally, but afterEach completes abruptly with an
   * exception, this method will complete abruptly with the exception thrown by afterEach.
   * 
   *
   * @param testName the name of one test to run.
   * @param args the Args for this run
   * @return a Status object that indicates when the test started by this method has completed, and whether or not it failed .
  */
  abstract protected override def runTest(testName: String, args: Args): Status = {

    var thrownException: Option[Throwable] = None

    beforeEach(testDataFor(testName, args.configMap))
    try {
      super.runTest(testName, args)
    }
    catch {
      case e: Exception => 
        thrownException = Some(e)
        FailedStatus
    }
    finally {
      try {
        afterEach(testDataFor(testName, args.configMap)) // Make sure that afterEach is called even if runTest completes abruptly.
        thrownException match {
          case Some(e) => throw e
          case None =>
        }
      }
      catch {
        case laterException: Exception =>
          thrownException match { // If both run and afterAll throw an exception, report the test exception
            case Some(earlierException) => throw earlierException
            case None => throw laterException
          }
      }
    }
  }
}