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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of scalatest_2.9.1 Show documentation
ScalaTest is a free, open-source testing toolkit for Scala and Java programmers.
The newest version!
/*
 * Copyright 2001-2013 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

/**
 * Superclass for the possible outcomes of running a test.
 *
 * 
 * Outcome is the result type of the withFixture methods of traits
 * Suite and fixture.Suite, as well as their
 * NoArgTest and OneArgTest function types.
 * The five possible outcomes are:
 * 
 *
 * 
 * Succeeded - indicates a test succeeded
 * Failed - indicates a test failed and contains an exception describing the failure
 * Canceled - indicates a test was canceled and contains an exception describing the cancelation
 * Pending - indicates a test was pending
 * Omitted - indicates a test was omitted
 * 
 *
 * 
 * Note that "ignored" does not appear as a type of Outcome, because tests are
 * marked as ignored on the outside and skipped over as the suite executes. So an ignored test never runs, and therefore
 * never has an outcome. By contrast, a test is determined to be pending by running the test
 * and observing the actual outcome. If the test body completes abruptly with a TestPendingException,
 * then the outcome was that the test was pending.
 * 
 *
 * 
 * Note: Omitted is currently not used in ScalaTest, but will eventually be used
 * to indicate everthing except specification-text provided by mechanisms such
 * as GivenWhenThen has been omitted or elided from the test body. This will enable
 * full specification output to be obtained without waiting for the actual test code
 * to execute.
 * 
 */
sealed abstract class Outcome {

  /**
   * Indicates whether this Outcome represents a test that succeeded.
   *
   * 
   * This class's implementation of this method always returns false.
   * 
   *
   * @return true if this Outcome is an instance of Succeeded.
   */
  val isSucceeded: Boolean = false

  /**
   * Indicates whether this Outcome represents a test that failed.
   *
   * 
   * This class's implementation of this method always returns false.
   * 
   *
   * @return true if this Outcome is an instance of Failed.
   */
  val isFailed: Boolean = false

  /**
   * Indicates whether this Outcome represents a test that was canceled.
   *
   * 
   * This class's implementation of this method always returns false.
   * 
   *
   * @return true if this Outcome is an instance of Canceled.
   */
  val isCanceled: Boolean = false

  /**
   * Indicates whether this Outcome represents a test that was pending.
   *
   * 
   * This class's implementation of this method always returns false.
   * 
   *
   * @return true if this Outcome is an instance of Pending.
   */
  val isPending: Boolean = false

  /**
   * Indicates whether this Outcome represents a test that was omitted.
   *
   * 
   * This class's implementation of this method always returns false.
   * 
   *
   * @return true if this Outcome is an instance of Omitted.
   */
  val isOmitted: Boolean = false

  /**
   * Indicates whether this Outcome represents a test that either failed or was canceled, in which case this Outcome will contain an exception.
   *
   * @return true if this Outcome is an instance of either Failed or Canceled.
   */
  val isExceptional: Boolean = false

  /**
   * Converts this Outcome to an Option[Throwable].
   *
   * 
   * This class's implementation of this method always returns None.
   * 
   *
   * @return a Some wrapping the contained exception if this Outcome is an instance of either Failed or Canceled.
   */
  def toOption: Option[Throwable] = None

  // Used internally to resuse the old code that was catching these exceptions when running tests. Eventually I would
  // like to rewrite that old code to use the result type, but it will still needs to catch and handle these exceptions
  // in the same way in case they come back from a user's withFixture implementation.
  private[scalatest] def toUnit {
    this match {
      case Succeeded =>
      case Exceptional(e) => throw e
      case Pending(_) => throw new exceptions.TestPendingException
      case Omitted => throw new exceptions.TestOmittedException
    }
  }
}

/**
 * Superclass for the two outcomes of running a test that contain an exception: Failed and Canceled.
 *
 * 
 * This class provides a toOption method that returns a Some wrapping the contained exception, and
 * an isExceptional field with the value true. It's companion object provides an extractor that
 * enables patterns that match a test that either failed or canceled, as in:
 * 
 *
 *  * outcome match {
 *   case Exceptional(ex) => // handle failed or canceled case
 *   case _ => // handle succeeded, pending, or omitted case
 * }
 * 
 *
 * @param ex the Throwable contained in this Exceptional.
 */
sealed abstract class Exceptional(ex: Throwable) extends Outcome {

  /**
   * Indicates that this Outcome represents a test that either failed or was canceled.
   *
   * @return true
   */
  override val isExceptional: Boolean = true

  /**
   * Converts this Exceptional to a Some that wraps the contained exception.
   *
   * @return A Some wrapping the exception contained in this Exceptional.
   */
  override def toOption: Option[Throwable] = Some(ex)
}

/**
 * Companion object to class Exceptional that provides a factory method and an extractor that enables
 * patterns that match both Failed and Canceled outcomes and 
 * extracts the contained exception and a factory method.
 */
object Exceptional {

  /**
   * Creates an Exceptional instance given the passed Throwable.
   *
   * 
   * If the passed Throwable is an instance of TestCanceledException, this
   * method will return Canceled containing that TestCanceledException. Otherwise,
   * it returns a Failed containing the Throwable.
   * 
   *
   * 
   * For example, trait SeveredStackTraces uses this
   * factory method to sever the stack trace of the exception contained in either a Failed and Canceled 
   * like this:
   * 
   * 
   *    * abstract override def withFixture(test: NoArgTest): Outcome = {
   *   super.withFixture(test) match {
   *     case Exceptional(e: StackDepth) => Exceptional(e.severedAtStackDepth)
   *     case o => o
   *   }
   * }
   * 
   *
   * @return a Failed or Canceled containing the passed exception.
   */
  def apply(e: Throwable): Exceptional = 
    e match {
      case tce: exceptions.TestCanceledException => Canceled(tce)
      case _ => Failed(e)
    }

  /**
   * Extractor enabling patterns that match both Failed and Canceled outcomes, 
   * extracting the contained exception.
   *
   * 
   * For example, trait SeveredStackTraces uses this
   * extractor to sever the stack trace of the exception contained in either a Failed and Canceled 
   * like this:
   * 
   * 
   *    * abstract override def withFixture(test: NoArgTest): Outcome = {
   *   super.withFixture(test) match {
   *     case Exceptional(e: StackDepth) => Exceptional(e.severedAtStackDepth)
   *     case o => o
   *   }
   * }
   * 
   *
   * @return a Some wrapping the contained throwable if res is an instance of
   *     either Failed or Canceled, else None.
   */
  def unapply(res: Outcome): Option[Throwable] = 
    res match {
      case Failed(ex) => Some(ex)
      case Canceled(ex) => Some(ex)
      case _ => None
    }
}

/**
 * Outcome for a test that succeeded.
 *
 * 
 * Note: the difference between this Succeeded object and the similarly named SucceededStatus
 * object is that this object indicates one test succeeded, whereas the SucceededStatus object indicates the absence of any failed tests or
 * aborted suites during a run. Both are used as the result type of Suite lifecycle methods, but Succeeded
 * is a possible result of withFixture, whereas SucceededStatus is a possible result of run, runNestedSuites,
 * runTests, or runTest. In short, Succeeded is always just about one test, whereas SucceededStatus could be
 * about something larger: multiple tests or an entire suite.
 * 
 */
case object Succeeded extends Outcome {

  /**
   * Indicates that this Outcome represents a test that succeeded.
   *
   * 
   * This class's implementation of this method always returns true.
   * 
   *
   * @return true
   */
  override val isSucceeded: Boolean = true
}

/**
 * Outcome for a test that failed, containing an exception describing the cause of the failure.
 *
 * 
 * Note: the difference between this Failed class and the similarly named FailedStatus
 * object is that an instance of this class indicates one test failed, whereas the FailedStatus object indicates either one or more tests failed
 * and/or one or more suites aborted during a run. Both are used as the result type of Suite lifecycle methods, but Failed
 * is a possible result of withFixture, whereas FailedStatus is a possible result of run, runNestedSuites,
 * runTests, or runTest. In short, Failed is always just about one test, whereas FailedStatus could be
 * about something larger: multiple tests or an entire suite.
 * 
 *
 * @param ex the Throwable contained in this Failed.
 */
case class Failed(ex: Throwable) extends Exceptional(ex) {

  /**
   * Indicates that this Outcome represents a test that failed.
   *
   * 
   * This class's implementation of this method always returns true.
   * 
   *
   * @return true
   */
  override val isFailed: Boolean = true
}

/**
 * Outcome for a test that was canceled, containing an exception describing the cause of the cancelation.
 *
 * @param ex the TestCanceledException contained in this Exceptional.
 */
case class Canceled(ex: exceptions.TestCanceledException) extends Exceptional(ex) {

  /**
   * Indicates that this Outcome represents a test that was canceled.
   *
   * 
   * This class's implementation of this method always returns true.
   * 
   *
   * @return true
   */
  override val isCanceled: Boolean = true
}

/**
 * Companion object to class Canceled that provides, in addition to the extractor and factory method
 * provided by the compiler given its companion is a case class, a second factory method 
 * that produces a Canceled outcome given a string message.
 */
object Canceled {

  /**
   * Creates a Canceled outcome given a string message.
   *
   * 
   * For example, trait CancelAfterFailure uses this factory method to create
   * a Canceled status if a cancelRemaining flag is set, which will
   * be the case if a test failed previously while running the suite:
   * 
   *
   *    * abstract override def withFixture(test: NoArgTest): Outcome = {
   *   if (cancelRemaining) 
   *     Canceled("Canceled by CancelOnFailure because a test failed previously")
   *   else
   *     super.withFixture(test) match {
   *       case failed: Failed =>
   *         cancelRemaining = true
   *         failed
   *       case outcome => outcome
   *     }
   *  }
   * 
   */
  def apply(message: String): Canceled = {
    if (message == null)
      throw new NullPointerException("message was null")
    val e = new exceptions.TestCanceledException(message, 0) // TODO: Verify this is hte correct stack depth.
    e.fillInStackTrace()
    Canceled(e)
  }
}

/**
 * Outcome for a test that was pending, which contains an optional string giving more information on what exactly is needed
 * for the test to become non-pending.
 *
 * @param message an optional message describing the reason the test is pending
 */
case class Pending(message: Option[String] = None) extends Outcome {

  /**
   * Indicates that this Outcome represents a test that was pending.
   *
   * 
   * This class's implementation of this method always returns true.
   * 
   *
   * @return true
   */
  override val isPending: Boolean = true
}

/**
 * Outcome for a test that was omitted.
 *
 * 
 * Note: This outcome is currently not used in ScalaTest, but will eventually be used
 * to indicate everthing except specification-text provided by mechanisms such
 * as GivenWhenThen has been omitted from the test body. This will enable
 * a the specification output to be obtained without waiting for the actual test code
 * to execute.
 * 
 */
case object Omitted extends Outcome {

  /**
   * Indicates that this Outcome represents a test that was omitted.
   *
   * 
   * This class's implementation of this method always returns false.
   * 
   *
   * @return true
   */
  override val isOmitted: Boolean = true
}