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

/*
 * 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

/**
 * Trait that contains the outcomeOf method, which executes a passed code block and
 * transforms the outcome into an Outcome, using the
 * same mechanism used by ScalaTest to produce an Outcome when executing
 * a test.
 *
 * 
 * For an example of outcomeOf in action, see the documentation for
 * class TableFor2.
 * 
 *
 * @author Bill Venners
 */
trait OutcomeOf {

  /**
   * Executes the supplied code (a by-name parameter) and returns an Outcome.
   *
   * 
   * Because Errors are used to denote serious errors, ScalaTest does not always treat a test that completes abruptly with
   * an Error as a test failure, but sometimes as
   * an indication that serious problems have arisen that should cause the run to abort, and the outcomeOf method exhibits
   * the same behavior. For example, if a test completes abruptly
   * with an OutOfMemoryError, it will not be reported as a test failure, but will instead cause the run to abort.
   * Because not everyone uses Errors only to represent serious problems, however, ScalaTest only behaves this way
   * for the following exception types (and their subclasses):
   * 
   *
   * 
   * java.lang.annotation.AnnotationFormatError
   * java.awt.AWTError
   * java.nio.charset.CoderMalfunctionError
   * javax.xml.parsers.FactoryConfigurationError
   * java.lang.LinkageError
   * java.lang.ThreadDeath
   * javax.xml.transform.TransformerFactoryConfigurationError
   * java.lang.VirtualMachineError
   * 
   *
   * 
   * The previous list includes all Errors that exist as part of Java 1.5 API, excluding java.lang.AssertionError.
   * If the code supplied to outcomeOf completes abruptly in one of the errors in the previous list, outcomeOf
   * will not return an Outcome, but rather will complete abruptly with the same exception.
   * will wrap any other exception thrown by the supplied code in a Some and return it.
   * 
   *
   * 
   * The outcomeOf method (and ScalaTest in general) does treat a thrown AssertionError as an indication of a test failure and therefore
   * returns a Failed wrapping the AssertionError. In addition, any other Error that is not an instance of a
   * type mentioned in the previous list will be caught by the outcomeOf and transformed as follows:
   *
   * 

   * TestPendingException
: Pending
   * TestCanceledException
: Canceled
   * otherwise: Failed
   * 
   * 
   *
   * 
   * If the code block completes normally (i.e., it doesn't throw any exception), outcomeOf results in Succeeded.
   * 
   *
   * @param f a block of code to execute
   * @return an Outcome representing the outcome of executing the block of code
   */
  def outcomeOf(f: => Any): Outcome = {
    try {                                         
      f                                           
      Succeeded
    }                                             
    catch {                                       
      case ex: exceptions.TestCanceledException => Canceled(ex)                           
      case _: exceptions.TestPendingException => Pending
      case tfe: exceptions.TestFailedException => Failed(tfe)
      case ex: Throwable if !Suite.anExceptionThatShouldCauseAnAbort(ex) => Failed(ex)                           
    }
  }
}

/**
 * Companion object that facilitates the importing of OutcomeOf's method as 
 * an alternative to mixing it in. One use case is to import OutcomeOf's method so you can use
 * it in the Scala interpreter.
 *
 * @author Bill Venners
 */
object OutcomeOf extends OutcomeOf