TestCaseSourceAttribute (NUnit 2.5)

TestCaseSourceAttribute is used on a parameterized test method to identify the property, method or field that will provide the required arguments. The attribute has three public constructors, only one of which is recommended for use in new code: 

TestCaseSourceAttribute(Type sourceType);

The sourceType argument represents the class that provides test cases. It must implement IEnumerable and return test case data appropriate for the test method on which the attribute appears.

This is a new form of the attribute in NUnit 2.6.2 and is recommended for use in preference to other forms because it doesn't use a string to specify the data source and is therefore more easily refactored. 

TestCaseSourceAttribute(Type sourceType, string sourceName);
TestCaseSourceAttribute(string sourceName);

These older constructors are no longer recommended. If a sourceType is specified, it represents the class that provides the test cases. It must have a default constructor.

If sourceType is not specified, the class containing the test method is used. NUnit will construct it using either the default constructor or - if arguments are provided - the appropriate constructor for those arguments.

The sourceName argument represents the name of the source used to provide test cases. It has the following characteristics:

TestCaseSourceAttribute supports one named parameter:

Category
Used to assign one or more categories to every test case returned from this source.

Constructing Test Cases

In constructing tests, NUnit uses each item returned by the enumerator as follows:

  1. If it is an object implementing NUnit.Framework.ITestCaseData, its properties are used to provide the test case. In NUnit 2.5 and later, this is done using reflection to allow compatibility with earlier versions that did not implement ITestCaseData.

    The following public fields or properties are used:

    Arguments
    An object[] representing the arguments to the method
    Categories
    An IList of categories to be applied to the test case.
    Description
    Sets the description property of the test
    ExpectedException
    Specifies a the Type of an exception that should be thrown by this invocation
    ExpectedExceptionName
    Specifies a the FullName of an exception that should be thrown by this invocation
    Ignored
    If true, the test case is ignored.
    IgnoreReason
    Specifies the reason for ignoring this test case. If set to a non-empty string, then the test is ignored.
    Properties
    An IDictionary of properties to be applied to the test case. Note that the values provided must be compatible with PropertiesAttribute. In particular, use of custom types or enums will cause problems.
    Result
    The expected result to be returned from the method, which must have a compatible return type.
    TestName
    Provides a name for the test. If not specified, a name is generated based on the method name and the arguments provided

  2. If the test has a single argument and the returned value matches the type of that argument it is used directly.

  3. If it is an object[], its members are used to provide the arguments for the method, as in this example, which returns arguments from a named static field. 

    [Test, TestCaseSource("DivideCases")]
public void DivideTest(int n, int d, int q)
{
    Assert.AreEqual( q, n / d );
}

static object[] DivideCases =
{
    new object[] { 12, 3, 4 },
    new object[] { 12, 2, 6 },
    new object[] { 12, 4, 3 } 
};

  4. If it is an array of some other type, NUnit can use it provided that the arguments to the method are all of that type. For example, the above code could be modified to make the three nested arrays of type int[].

  5. If anything else is returned, it is used directly as the sole argument to the method. This allows NUnit to give an error message in cases where the method requires a different number arguments or an argument of a different type. This can also eliminate a bit of extra typing by the programmer, as in this example: 

    static int[] EvenNumbers = new int[] { 2, 4, 6, 8 };

[Test, TestCaseSource("EvenNumbers")]
public void TestMethod(int num)
{
    Assert.IsTrue( num % 2 == 0 );
}

TestCaseData Class

Although any object implementing ITestCaseData may be used to provide extended test case information, NUnit provides the TestCaseData class for this purpose. The following example returns TestCaseData instances from a data source in a separately defined class. 

[TestFixture]
public class MyTests
{
  [Test,TestCaseSource(typeof(MyFactoryClass),"TestCases")]
  public int DivideTest(int n, int d)
  {
    return n/d;
  }
	
  ...
}

public class MyFactoryClass
{
  public static IEnumerable TestCases
  {
    get
    {
      yield return new TestCaseData( 12, 3 ).Returns( 4 );
      yield return new TestCaseData( 12, 2 ).Returns( 6 );
      yield return new TestCaseData( 12, 4 ).Returns( 3 );
      yield return new TestCaseData( 0, 0 )
        .Throws(typeof(DivideByZeroException))
        .SetName("DivideByZero")
        .SetDescription("An exception is expected");
    }
  }  
}

This example uses the fluent interface supported by TestCaseData to make the program more readable. The last yield statement above is equivalent to 

      TestCaseData data = new TestCaseData(0,0);
      data.ExpectedException = typeof(DivideByZeroException;
      data.TestName = "DivideByZero";
      data.Description = "An exception is expected";
      yield return data;

TestCaseData supports the following properties and methods, which may be appended to an instance in any order.

.Ignore()
Causes the test case to be ignored.
.Ignore(string)
Causes the test case to be ignored with a reason specified.
.MakeExplicit()
Causes the test case to be marked explicit.
.MakeExplicit(string)
Causes the test case to be marked explicit and specifies the reason for doing so.
.Returns
The expected result to be returned from the method, which must have a compatible return type.
.SetCategory(string)
Applies a category to the test
.SetDescription(string)
Sets the description property of the test
.SetName(string)
Provides a name for the test. If not specified, a name is generated based on the method name and the arguments provided
.SetProperty(string, string)
.SetProperty(string, int)
.SetProperty(string, double)
Applies a named property and value to the test
.Throws(Type)
.Throws(string)
Specifies a the Type or FullName of an exception that should be thrown by this invocation

Order of Execution

In NUnit 2.5, individual test cases are sorted alphabetically and executed in that order. With NUnit 2.5.1, the individual cases are not sorted, but are executed in the order in which NUnit discovers them. This order does not follow the lexical order of the attributes and will often vary between different compilers or different versions of the CLR.

As a result, when TestCaseSourceAttribute appears multiple times on a method or when other data-providing attributes are used in combination with TestCaseSourceAttribute, the order of the test cases is undefined.

However, when a single TestCaseSourceAttribute is used by itself, the order of the tests follows exactly the order in which the test cases are returned from the source.

Note on Object Construction

NUnit locates the test cases at the time the tests are loaded, creates instances of each class with non-static sources and builds a list of tests to be executed. Each source object is only created once at this time and is destroyed after all tests are loaded.

If the data source is in the test fixture itself, the object is created using the appropriate constructor for the fixture parameters provided on the TestFixtureAttribute or the default constructor if no parameters were specified. Since this object is destroyed before the tests are run, no communication is possible between these two phases - or between different runs - except through the parameters themselves.