TheoryAttribute (NUnit 2.5)
A Theory is a special type of test, used to verify a general statement about the system under development. Normal tests are example-based. That is, the developer supplies one or more examples of inputs and expected outputs either within the code of the test or - in the case of Parameterized Tests - as arguments to the test method. A theory, on the other hand, makes a general statement that all of its assertions will pass for all arguments satisfying certain assumptions.
Theories are implemented in NUnit as methods within a TestFixture, which are annotated with the TheoryAttribute. Theory methods must always have arguments and therefore appears quite similar to Parameterized Tests at first glance. However, a Theory incorporates additional data sources for its arguments and allows special processing for assumptions about that data. The key difference, though, is that theories make general statements and are more than just a set of examples.
Data for Theories
The primary source of data for a Theory is the Datapoint or Datapoints attribute. NUnit will use any fields of the required types, which are annotated with one of these attributes, to provide data for each parameter of the Theory. NUnit assembles the values for individual arguments combinatorially to provide test cases for the theory.
In addition to the Datapoint and Datapoints attributes, it is possible to use any of the approaches for supplying data that are recognized on normal parameterized tests. We suggest that this capability not be overused, since it runs counter to the distinction between a test based on examples and a theory. However, it may be useful in order to guarantee that a specific test case is included.
For boolean and enum arguments, NUnit can supply the data without any action by the user. All possible values are supplied to the argument. This feature is disabled if the user supplies any values for the argument.
Assumptions
The theory itself is responsible for ensuring that all data supplied meets its assumptions. It does this by use of the Assume.That(...) construct, which works just like Assert.That(...) but does not cause a failure. If the assumption is not satisfied for a particular test case, that case returns an Inconclusive result, rather than a Success or Failure.
The overall result of executing a Theory over a set of test cases is determined as follows:
- If the assumptions are violated for all test cases, then the Theory itself is marked as a failure.
- If any Assertion fails, the Theory itself fails.
- If at least some cases pass the stated assumptions, and there are no assertion failures or exceptions, then the Theory passes.
Since the user does not generally care about inconclusive cases under a theory, they are not normally displayed in the Gui. For situations where they are needed - such as debugging - the context menu for the theory provides an option to display them.
Example:
In the following example, the theory SquareRootDefinition verifies that the implementation of square root satisies the following definition:
"Given a non-negative number, the square root of that number is always non-negative and, when multiplied by itself, gives the original number."
public class SqrtTests
{
[Datapoints]
public double[] values = new double[] { 0.0, 1.0, -1.0, 42.0 };
[Theory]
public void SquareRootDefinition(double num)
{
Assume.That(num >= 0.0);
double sqrt = Math.Sqrt(num);
Assert.That(sqrt >= 0.0);
Assert.That(sqrt * sqrt, Is.EqualTo(num).Within(0.000001));
}
}