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:

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 Ints, 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:

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.

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:

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:

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:

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:

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:

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)