org.scalatest.prop

# TableDrivenPropertyChecks

#### trait TableDrivenPropertyChecks extends Whenever with Tables

Trait containing methods that faciliate property checks against tables of data.

This trait contains one `forAll` method for each `TableForN` class, `TableFor1` through `TableFor22`, which allow properties to be checked against the rows of a table. It also contains a `wherever` method that can be used to indicate a property need only hold whenever some condition is true.

For an example of trait `TableDrivenPropertyChecks` in action, imagine you want to test this `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
    }

`TableDrivenPropertyChecks` allows you to create tables with between 1 and 22 columns and any number of rows. You create a table by passing tuples to one of the factory methods of object `Table`. Each tuple must have the same arity (number of members). The first tuple you pass must all be strings, because it define names for the columns. Subsequent tuples define the data. After the initial tuple that contains string column names, all tuples must have the same type. For example, if the first tuple after the column names contains two `Int`s, all subsequent tuples must contain two `Int` (i.e., have type `Tuple2[Int, Int]`).

To test the behavior of `Fraction`, you could create a table of numerators and denominators to pass to the constructor of the `Fraction` class using one of the `apply` factory methods declared in `Table`, like this:

    import org.scalatest.prop.TableDrivenPropertyChecks._

    val fractions =
      Table(
        ("n", "d"),  // First tuple defines column names
        (  1,   2),  // Subsequent tuples define the data
        ( -1,   2),
        (  1,  -2),
        ( -1,  -2),
        (  3,   1),
        ( -3,   1),
        ( -3,   0),
        (  3,  -1),
        (  3,  Integer.MIN_VALUE),
        (Integer.MIN_VALUE, 3),
        ( -3,  -1)
      )

You could then check a property against each row of the table using a `forAll` method, like this:

    import org.scalatest.matchers.ShouldMatchers._

    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 be === 0

        f.denom should be > 0
      }
    }

Trait `TableDrivenPropertyChecks` provides 22 overloaded `forAll` methods that allow you to check properties using the data provided by a table. Each `forAll` method takes two parameter lists. The first parameter list is a table. The second parameter list is a function whose argument types and number matches that of the tuples in the table. For example, if the tuples in the table supplied to `forAll` each contain an `Int`, a `String`, and a `List[Char]`, then the function supplied to `forAll` must take 3 parameters, an `Int`, a `String`, and a `List[Char]`. The `forAll` method will pass each row of data to the function, and generate a `TableDrivenPropertyCheckFailedException` if the function completes abruptly for any row of data with any exception that would normally cause a test to fail in ScalaTest other than `UnmetConditionException`. An `UnmetConditionException`, which is thrown by the `whenever` method (also defined in this trait) to indicate a condition required by the property function is not met by a row of passed data, will simply cause `forAll` to skip that row of data.

#### Testing stateful functions

One way to use a table with one column is to test subsequent return values of a stateful function. Imagine, for example, you had an object named `FiboGen` whose `next` method returned the next fibonacci number, where next means the next number in the series following the number previously returned by `next`. So the first time `next` was called, it would return 0. The next time it was called it would return 1. Then 1. Then 2. Then 3, and so on. `FiboGen` would need to maintain state, because it has to remember where it is in the series. In such a situation, you could create a `TableFor1` (a table with one column, which you could alternatively think of as one row), in which each row represents the next value you expect.

    val first14FiboNums =
      Table("n", 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233)

Then in your `forAll` simply call the function and compare it with the expected return value, like this:

    forAll (first14FiboNums) { n =>
      FiboGen.next should equal (n)
    }

#### Testing mutable objects

If you need to test a mutable object, one way you can use tables is to specify state transitions in a table. For example, imagine you wanted to test this mutable `Counter` class:

    class Counter {
      private var c = 0
      def reset() { c = 0 }
      def click() { c += 1 }
      def enter(n: Int) { c = n }
      def count = c
    }

A `Counter` keeps track of how many times its `click` method is called. The count starts out at zero and increments with each `click` invocation. You can also set the count to a specific value by calling `enter` and passing the value in. And the `reset` method returns the count back to zero. You could define the actions that initiate state transitions with case classes, like this:

    abstract class Action
    case object Start extends Action
    case object Click extends Action
    case class Enter(n: Int) extends Action

Given these actions, you could define a state-transition table like this:

    val stateTransitions =
      Table(
        ("action", "expectedCount"),
        (Start,    0),
        (Click,    1),
        (Click,    2),
        (Click,    3),
        (Enter(5), 5),
        (Click,    6),
        (Enter(1), 1),
        (Click,    2),
        (Click,    3)
      )

To use this in a test, simply do a pattern match inside the function you pass to `forAll`. Make a pattern for each action, and have the body perform that action when there's a match. Then check that the actual value equals the expected value:

    val counter = new Counter
    forAll (stateTransitions) { (action, expectedCount) =>
      action match {
        case Start => counter.reset()
        case Click => counter.click()
        case Enter(n) => counter.enter(n)
      }
      counter.count should equal (expectedCount)
    }

#### Testing invalid argument combinations

A table-driven property check can also be helpful to ensure that the proper exception is thrown when invalid data is passed to a method or constructor. For example, the `Fraction` constructor shown above should throw `IllegalArgumentException` if `Integer.MIN_VALUE` is passed for either the numerator or denominator, or zero is passed for the denominator. This yields the following five combinations of invalid data:

`n` | `d`
--- | ---
`Integer.MIN_VALUE` | `Integer.MIN_VALUE`
a valid value | `Integer.MIN_VALUE`
`Integer.MIN_VALUE` | a valid value
`Integer.MIN_VALUE` | zero
a valid value | zero

You can express these combinations in a table:

    val invalidCombos =
      Table(
        ("n",               "d"),
        (Integer.MIN_VALUE, Integer.MIN_VALUE),
        (1,                 Integer.MIN_VALUE),
        (Integer.MIN_VALUE, 1),
        (Integer.MIN_VALUE, 0),
        (1,                 0)
      )

Given this table, you could check that all invalid combinations produce `IllegalArgumentException`, like this:

    forAll (invalidCombos) { (n: Int, d: Int) =>
      evaluating {
        new Fraction(n, d)
      } should produce [IllegalArgumentException]
    }

Linear Supertypes
Tables, Whenever, AnyRef, Any
Known Subclasses
PropertyChecks, PropertyChecks, TableDrivenPropertyChecks
Ordering

1. Alphabetic
2. By inheritance

Inherited

1. Hide All
2. Show all

1. TableDrivenPropertyChecks
2. Tables
3. Whenever
4. AnyRef
5. Any

Visibility

1. Public
2. All

### Value Members

1. #### def != (arg0: AnyRef): Boolean

   Attributes
     final
   Definition Classes
     AnyRef

2. #### def != (arg0: Any): Boolean

   Attributes
     final
   Definition Classes
     Any

3. #### def ## (): Int

   Attributes
     final
   Definition Classes
     AnyRef → Any

4. #### def == (arg0: AnyRef): Boolean

   Attributes
     final
   Definition Classes
     AnyRef

5. #### def == (arg0: Any): Boolean

   Attributes
     final
   Definition Classes
     Any

6. #### object Table extends AnyRef

   Object containing one `apply` factory method for each `TableFor<n>` class.

7. #### def asInstanceOf [T0] : T0

   Attributes
     final
   Definition Classes
     Any

8. #### def clone (): AnyRef

   Attributes
     protected[lang]
   Definition Classes
     AnyRef
   Annotations
     @throws()

9. #### def eq (arg0: AnyRef): Boolean

   Attributes
     final
   Definition Classes
     AnyRef

10. #### def equals (arg0: Any): Boolean

    Definition Classes
      AnyRef → Any

11. #### def finalize (): Unit

    Attributes
      protected[lang]
    Definition Classes
      AnyRef
    Annotations
      @throws()

12. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V] (table: TableFor22[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor22`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor22`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

13. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U] (table: TableFor21[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor21`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor21`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

14. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T] (table: TableFor20[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor20`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor20`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

15. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S] (table: TableFor19[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor19`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor19`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

16. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R] (table: TableFor18[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor18`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor18`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

17. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q] (table: TableFor17[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor17`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor17`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

18. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P] (table: TableFor16[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor16`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor16`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

19. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N, O] (table: TableFor15[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor15`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor15`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

20. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M, N] (table: TableFor14[A, B, C, D, E, F, G, H, I, J, K, L, M, N])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M, N) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor14`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor14`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

21. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L, M] (table: TableFor13[A, B, C, D, E, F, G, H, I, J, K, L, M])(fun: (A, B, C, D, E, F, G, H, I, J, K, L, M) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor13`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor13`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

22. #### def forAll [A, B, C, D, E, F, G, H, I, J, K, L] (table: TableFor12[A, B, C, D, E, F, G, H, I, J, K, L])(fun: (A, B, C, D, E, F, G, H, I, J, K, L) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor12`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor12`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

23. #### def forAll [A, B, C, D, E, F, G, H, I, J, K] (table: TableFor11[A, B, C, D, E, F, G, H, I, J, K])(fun: (A, B, C, D, E, F, G, H, I, J, K) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor11`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor11`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

24. #### def forAll [A, B, C, D, E, F, G, H, I, J] (table: TableFor10[A, B, C, D, E, F, G, H, I, J])(fun: (A, B, C, D, E, F, G, H, I, J) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor10`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor10`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

25. #### def forAll [A, B, C, D, E, F, G, H, I] (table: TableFor9[A, B, C, D, E, F, G, H, I])(fun: (A, B, C, D, E, F, G, H, I) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor9`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor9`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

26. #### def forAll [A, B, C, D, E, F, G, H] (table: TableFor8[A, B, C, D, E, F, G, H])(fun: (A, B, C, D, E, F, G, H) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor8`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor8`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

27. #### def forAll [A, B, C, D, E, F, G] (table: TableFor7[A, B, C, D, E, F, G])(fun: (A, B, C, D, E, F, G) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor7`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor7`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

28. #### def forAll [A, B, C, D, E, F] (table: TableFor6[A, B, C, D, E, F])(fun: (A, B, C, D, E, F) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor6`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor6`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

29. #### def forAll [A, B, C, D, E] (table: TableFor5[A, B, C, D, E])(fun: (A, B, C, D, E) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor5`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor5`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

30. #### def forAll [A, B, C, D] (table: TableFor4[A, B, C, D])(fun: (A, B, C, D) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor4`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor4`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

31. #### def forAll [A, B, C] (table: TableFor3[A, B, C])(fun: (A, B, C) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor3`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor3`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

32. #### def forAll [A, B] (table: TableFor2[A, B])(fun: (A, B) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor2`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor2`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

33. #### def forAll [A] (table: TableFor1[A])(fun: (A) ⇒ Unit): Unit

    Performs a property check by applying the specified property check function to each row of the specified `TableFor1`.

    Performs a property check by applying the specified property check function to each row of the specified `TableFor1`.

    table

      the table of data with which to perform the property check

    fun

      the property check function to apply to each row of data in the table

34. #### def getClass (): java.lang.Class[_]

    Attributes
      final
    Definition Classes
      AnyRef

35. #### def hashCode (): Int

    Definition Classes
      AnyRef → Any

36. #### def isInstanceOf [T0] : Boolean

    Attributes
      final
    Definition Classes
      Any

37. #### def ne (arg0: AnyRef): Boolean

    Attributes
      final
    Definition Classes
      AnyRef

38. #### def notify (): Unit

    Attributes
      final
    Definition Classes
      AnyRef

39. #### def notifyAll (): Unit

    Attributes
      final
    Definition Classes
      AnyRef

40. #### def synchronized [T0] (arg0: ⇒ T0): T0

    Attributes
      final
    Definition Classes
      AnyRef

41. #### def toString (): String

    Definition Classes
      AnyRef → Any

42. #### def wait (): Unit

    Attributes
      final
    Definition Classes
      AnyRef
    Annotations
      @throws()

43. #### def wait (arg0: Long, arg1: Int): Unit

    Attributes
      final
    Definition Classes
      AnyRef
    Annotations
      @throws()

44. #### def wait (arg0: Long): Unit

    Attributes
      final
    Definition Classes
      AnyRef
    Annotations
      @throws()

45. #### def whenever (condition: Boolean)(fun: ⇒ Unit): Unit

    Evaluates the passed code block if the passed boolean condition is true, else throws `DiscardedEvaluationException`.

    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.ShouldMatchers._

        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 be === 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.

    condition

      the boolean condition that determines whether `whenever` will evaluate the `fun` function (`condition` is true) or throws `DiscardedEvaluationException` (`condition` is false)

    fun

      the function to evaluate if the specified `condition` is true

    Definition Classes
      Whenever

### Inherited from Tables

### Inherited from Whenever

### Inherited from AnyRef

### Inherited from Any