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

Show more of this group Show more artifacts with this name
Show all versions of scalatest_2.11.0-M3 Show documentation
ScalaTest is a free, open-source testing toolkit for Scala and Java programmers.
There is a newer version: 2.0.M6-SNAP27
/*
 * Copyright 2001-2008 Artima, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.scalatest

/**
 * Trait that defines abstract methods that are implemented in Suite that can
 * be overriden in stackable modification traits.
 *
 * 
 * The main purpose of AbstractSuite is to differentiate core Suite
 * traits, such as Suite, FunSuite, and FunSpec from stackable
 * modification traits for Suites such as BeforeAndAfterEach, OneInstancePerTest,
 * and ParallelNestedSuiteExecution. Because these stackable traits extend AbstractSuite 
 * instead of Suite, you can't define a suite by simply extending one of the stackable traits:
 * 
 *
 *  * class MySuite extends BeforeAndAfterEach // Won't compile
 * 
 *
 * 
 * Instead, you need to extend a core Suite trait and mix the stackable BeforeAndAfterEach trait
 * into that, like this:
 * 
 *
 *  * class MySuite extends FunSuite with BeforeAndAfterEach // Compiles fine
 * 
 *
 * @author Bill Venners
 */
trait AbstractSuite { this: Suite =>

  /**
   * Runs the passed test function with a fixture established by this method.
   *
   * 
   * This method should set up the fixture needed by the tests of the
   * current suite, invoke the test function, and if needed, perform any clean
   * up needed after the test completes. Because the NoArgTest function
   * passed to this method takes no parameters, preparing the fixture will require
   * side effects, such as reassigning instance vars in this Suite or initializing
   * a globally accessible external database. If you want to avoid reassigning instance vars
   * you can use fixture.Suite.
   * 
   *
   * @param test the no-arg test function to run with a fixture
   */
  protected def withFixture(test: NoArgTest)

  /**
   * Runs this suite of tests.
   *
   * @param testName an optional name of one test to execute. If None, all relevant tests should be executed.
   *                 I.e., None acts like a wildcard that means execute 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 Suites to be executed
   *              by another entity, such as concurrently by a pool of threads. If None, nested Suites will be executed sequentially.
   * @param tracker a Tracker tracking Ordinals being fired by the current thread.
   *
   * @throws NullPointerException if any passed parameter is null.
   */
  def run(
    testName: Option[String],
    reporter: Reporter,
    stopper: Stopper,
    filter: Filter,
    configMap: Map[String, Any],
    distributor: Option[Distributor],
    tracker: Tracker
  )

  /**
   *
   * Runs zero to many of this suite's nested suites.
   *
   * @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 Suites to be run
   *              by another entity, such as concurrently by a pool of threads. If None, nested Suites will be run sequentially.
   * @param tracker a Tracker tracking Ordinals being fired by the current thread.
   *         
   * @throws NullPointerException if any passed parameter is null.
   */
  protected def runNestedSuites(reporter: Reporter, stopper: Stopper, filter: Filter,
                                configMap: Map[String, Any], distributor: Option[Distributor], tracker: Tracker)

  /**
   * Runs zero to many of this suite'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 instances of this Suite class
   *              that are responsible for executing individual tests contained in this Suite, or groups of this Suite's
   *              tests, may be placed so as to be run
   *              by another entity, such as concurrently by a pool of threads.
   * @param tracker a Tracker tracking Ordinals being fired by the current thread.
   * @throws NullPointerException if any of testName, reporter, stopper, groupsToInclude,
   *     groupsToExclude, or configMap is null.
   */
  protected def runTests(testName: Option[String], reporter: Reporter, stopper: Stopper, filter: Filter,
                             configMap: Map[String, Any], distributor: Option[Distributor], tracker: Tracker)

  /**
   * Runs a test.
   *
   * @param testName the name of one test to execute.
   * @param reporter the Reporter to which results will be reported
   * @param stopper the Stopper that will be consulted to determine whether to stop execution early.
   * @param configMap a Map of key-value pairs that can be used by the executing Suite of tests.
   * @param tracker a Tracker tracking Ordinals being fired by the current thread.
   *
   * @throws NullPointerException if any of testName, reporter, stopper, configMap,
   *     or tracker is null.
   */
  protected def runTest(
    testName: String,
    reporter: Reporter,
    stopper: Stopper,
    configMap: Map[String, Any],
    tracker: Tracker
  )

  /**
  * An Set of test names. If this Suite contains no tests, this method returns an empty Set.
  *
  * 
  * Although subclass and subtrait implementations of this method may return a Set whose iterator produces String
  * test names in a well-defined order, the contract of this method does not required a defined order. Subclasses are free to
  * implement this method and return test names in either a defined or undefined order.
  * 
  */
  def testNames: Set[String]

  /**
  * A List of this Suite object's nested Suites. If this Suite contains no nested Suites,
  * this method returns an empty List.
  */
  def nestedSuites: List[Suite]

  /**
   * A Map whose keys are String tag names with which tests in this Suite are marked, and
   * whose values are the Set of test names marked with each tag.  If this Suite contains no tags, this
   * method returns an empty Map.
   *
   * 
   * Subclasses may implement this method to define and/or discover tags in a custom manner, but overriding method implementations
   * should never return an empty Set as a value. If a tag has no tests, its name should not appear as a key in the
   * returned Map.
   * 
   */
  def tags: Map[String, Set[String]]

  /**
   * The total number of tests that are expected to run when this Suite's run method is invoked.
   *
   * @param filter a Filter with which to filter tests to count based on their tags
   */
  def expectedTestCount(filter: Filter): Int
  
  /**
   * Suite style name.
   */
  val styleName: String
}