org.scalatest.exceptions.ModifiablePayload.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.exceptions

/**
 * Trait implemented by PayloadField exception types that can modify their payload.
 *
 * 
 * This trait facilitates the withPayload construct provided by trait
 * Payloads. This construct enables a payload object (or modified
 * payload object) to be included as the payload of a thrown exception. The payload
 * can then be included in the ScalaTest event that results from that exception. For
 * example, the payload included in a TestFailedException will be included
 * as the payload of the resulting TestFailed event. Here's an example in
 * which a GUI snapshot is included as a payload when a test fails:
 * 
 *
 *  * withPayload(generateGUISnapshot()) {
 *   1 + 1 should === (3)
 * }
 * 
 *
 * 
 * Exception types that mix in this trait have a modifyPayload method, which
 * returns an exception identical to itself, except with the payload option replaced with
 * the result of invoking the passed function, supplying the current payload option
 * as the lone Option[Any] parameter.
 * 
 */
trait ModifiablePayload[T <: Throwable] { this: Throwable with PayloadField =>
  
  /**
   * Returns an instance of this exception's class, identical to this exception,
   * except with the payload option replaced with
   * the result of invoking the passed function, fun, supplying the current payload option
   * as the lone Option[Any] parameter.
   *
   * 
   * Implementations of this method may either mutate this exception or return
   * a new instance with the revised detail message.
   * 
   *
   * @param fun A function that returns the new payload option given the old one
   */
  def modifyPayload(fun: Option[Any] => Option[Any]): T
}