org.scalatest.Payloads.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.0-1 Show documentation

ScalaTest is a free, open-source testing toolkit for Scala and Java programmers.

There is a newer version: 2.0.M6-SNAP3

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

/**
 * Trait facilitating the inclusion of a payload in a thrown ScalaTest exception.
 *
 * 
 * This trait includes a withPayload construct 
 * that enables a payload object (or modified
 * payload object) to be included as the payload of a thrown exception.
 *
 * 

 * Many ScalaTest events include an optional "payload" field that can be used
 * to pass information to a custom reporter. This trait facilitates such customization, 
 * by making it easy to insert a payload into a thrown exception, such as a TestFailedException.
 * The thrown exception must mix in Payload.
 * ScalaTest looks for trait Payload and fires any payloads it finds in the relevant ScalaTest event
 * stimulated by the exception, such as a TestFailed event stimulated by a TestFailedException.
 * Here's an example in which a GUI snapshot is included as a payload when a test fails:
 * 
 *
 *  * withPayload(generateGUISnapshot()) {
 *   1 + 1 should be === 3
 * }
 * 
 *
 * @author Bill Venners
 */
trait Payloads {

  /**
   * Executes the block of code passed as the second parameter, and, if it
   * completes abruptly with a ModifiablePayload exception,
   * replaces the current payload contained in the exception, if any, with the one passed
   * as the first parameter.
   *
   * 
   * This method allows you to insert a payload into a thrown Payload exception (such as
   * a TestFailedException), so that payload can be included in events fired to a custom reporter
   * that can make use of the payload.  
   * Here's an example in which a GUI snapshot is included as a payload when a test fails:
   * 
   *
   *    * withPayload(generateGUISnapshot()) {
   *   1 + 1 should be === 3
   * }
   * 
   *
  */
  def withPayload(payload: Any)(fun: => Unit) {
    try {
      fun
    }
    catch {
      case e: org.scalatest.exceptions.ModifiablePayload[_] =>
        if (payload != null)
          throw e.modifyPayload((currentPayload: Option[Any]) => Some(payload))
        else
          throw e
    }
  }
}