Update: August 22, 2007

SuiteAttribute (NUnit 2.0/2.4.4)

The Suite Attribute is used to define subsets of test to be run from the command-line, using the /fixture option. It was introduced in NUnit 2.0 to replace the older approach of inheriting from the TestSuite class.

Originally, the NUnit developers believed that the need for the Suite mechanism would diminish because of the dynamic creation of suites based on namespaces. It was provided for backwards compatibility.

That has not proven to be true. Suites are still used today by many people, so we are making an effort to revive them in terms of usability.

The Suite mechanism depends on a static property marked with the SuiteAttribute. In the clasic implementation, supported by all releases since 2.0, that property returns a TestSuite, populated with the tests that are to be executed.

Old Approach

namespace NUnit.Tests
{
  using System;
  using NUnit.Framework;
  using NUnit.Core;

  public class AllTests
  {
    [Suite]
    public static TestSuite Suite
    {
      get
      {
        TestSuite suite = new TestSuite("All Tests");
        suite.Add(new OneTestCase());
        suite.Add(new Assemblies.AssemblyTests());
        suite.Add(new AssertionTest());
        return suite;
      }
    }
  }
}

This approach has a serious problem: it requires a reference to the nunit.core assembly, which is not normally referenced by user tests. This means that the tests cannot be ported across versions of NUnit without recompilation. In some cases, introducing more than one version of the core assembly can prevent NUnit from running correctly.

Beginning with NUnit 2.4.4, a new approach is available. The property marked with the SuiteAttribute may simply return a collection containing test fixture objects or Types. If a Type is provided, NUnit creates an object of that type for use as a fixture. Any other object is assumed to be a pre-created fixture object. This allows objects with parameterized constructors or settable properties to be used as fixtures.

Test suites created through use of the SuiteAttribute may contain TestFixtureSetUp and TestFixtureTearDown methods, to perform one-time setup and teardown for the tests included in the suite.

New Approach - Fixture Objects

namespace NUnit.Tests
{
  using System;
  using NUnit.Framework;

  private class AllTests
  {
    [Suite]
    public static IEnumerable Suite
    {
      get
      {
        ArrayList suite = new ArrayList();
        suite.Add(new OneTestCase());
        suite.Add(new AssemblyTests());
        suite.Add(new NoNamespaceTestFixture());
        return suite;
      }
    }
  }
}

New Approach - Fixture Types

namespace NUnit.Tests
{
  using System;
  using NUnit.Framework;

  private class AllTests
  {
    [Suite]
    public static IEnumerable Suite
    {
      get
      {
        ArrayList suite = new ArrayList();
        suite.Add(typeof(OneTestCase));
        suite.Add(typeof(AssemblyTests));
        suite.Add(typeof(NoNamespaceTestFixture));
        return suite;
      }
    }
  }
}

Limitations

NUnit support for user-defined Suites currently has two limitations:
  1. It is not possible to include individual test cases directly in a Suite using the new approach. Anyone wanting to do so will need to use the old approach and create an object derive from NUnit.Core.TestCase. This is not recommended, since it requires a reference to the core assembly.
  2. Suites are currently not displayed in the Gui or run automatically by either runner when they are encountered. The historical purpose of the Suite mechanism was to provide a way of aggregating tests at the top level of each run. Hence, they are only supported when used with the /fixture option on the console or gui command line.
Approaches to removing these limitations are being investigated as part of the planning for future NUnit releases.