org.scalatest.prop.Whenever.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.prop
import org.scalatest.enablers.WheneverAsserting
/**
* Trait that contains the whenever clause that can be used in table- or generator-driven property checks.
*
* @author Bill Venners
*/
trait Whenever {
/**
* Evaluates the passed code block if the passed boolean condition is true, else throws DiscardedEvaluationException.
*
*
* The whenever method can be used inside property check functions to discard invocations of the function with
* data for which it is known the property would fail. For example, given the following Fraction class:
*
*
*
* class Fraction(n: Int, d: Int) {
*
* require(d != 0)
* require(d != Integer.MIN_VALUE)
* require(n != Integer.MIN_VALUE)
*
* val numer = if (d < 0) -1 * n else n
* val denom = d.abs
*
* override def toString = numer + " / " + denom
* }
*
*
*
* import org.scalatest.prop.TableDrivenPropertyChecks._
*
* val fractions =
* Table(
* ("n", "d"),
* ( 1, 2),
* ( -1, 2),
* ( 1, -2),
* ( -1, -2),
* ( 3, 1),
* ( -3, 1),
* ( -3, 0),
* ( 3, -1),
* ( 3, Integer.MIN_VALUE),
* (Integer.MIN_VALUE, 3),
* ( -3, -1)
* )
*
*
*
* Imagine you wanted to check a property against this class with data that includes some
* value that are rejected by the constructor, such as a denominator of zero, which should
* result in an IllegalArgumentException. You could use whenever
* to discard any rows in the fraction that represent illegal arguments, like this:
*
*
*
* import org.scalatest.matchers.Matchers._
*
* forAll (fractions) { (n: Int, d: Int) =>
*
* whenever (d != 0 && d != Integer.MIN_VALUE
* && n != Integer.MIN_VALUE) {
*
* val f = new Fraction(n, d)
*
* if (n < 0 && d < 0 || n > 0 && d > 0)
* f.numer should be > 0
* else if (n != 0)
* f.numer should be < 0
* else
* f.numer should === (0)
*
* f.denom should be > 0
* }
* }
*
*
*
* In this example, rows 6, 8, and 9 have values that would cause a false to be passed
* to whenever. (For example, in row 6, d is 0, which means d != 0
* will be false.) For those rows, whenever will throw DiscardedEvaluationException,
* which will cause the forAll method to discard that row.
*
*
* @param condition the boolean condition that determines whether whenever will evaluate the
* fun function (condition is true) or throws DiscardedEvaluationException (condition is false)
* @param fun the function to evaluate if the specified condition is true
*/
def whenever[T](condition: Boolean)(fun: => T)(implicit wa: WheneverAsserting[T]): wa.Result =
wa.whenever(condition)(fun)
}