V4 Documentation
Search

NCrunch.Framework.DistributeByCapabilitiesAttribute

NCrunch.Framework Attribute Introduced NCrunch v4.4

Purpose

The DuplicateByDimensionsAttribute can be applied to tests, fixtures, or assemblies to enable multiple copies of these tests to be created and parameterised within the NCrunch runner. NCrunch will create a new copy of each test according to each parameter supplied to the attribute. When a copy of the test is executed, it is able to determine the value of its parameter using the NCrunchEnvironment.GetDuplicatedDimension method.

The test clones are effectively treated as separate tests by the entirety of the NCrunch engine. Throughout the UI, they are distinctively marked with a suffix describing their parameter value ('dimension').

This facility could be compared with similar test framework features such as NUnit's TestCase or XUnit Theories. However, there are some notable differences:

  • DuplicateByDimensionsAttribute can be applied at all levels of a test suite, including at assembly level. This makes it possible to duplicate entire test suites according to parameters.
  • DuplicateByDimensionsAttribute is applied at the runner level and requires no interaction with the test framework. This means it works seamlessly with all test frameworks supported by NCrunch, including those that do not have their own parameterisation features.
  • DuplicateByDimensionsAttribute requires NCrunch to run. This means that tests relying on this attribute and values returned from NCrunchEnvironment.GetDuplicatedDimension will not function outside NCrunch. This is an important consideration for development projects where not all developers are using NCrunch to run their tests.

Declaration In NCrunch.Framework.dll

namespace NCrunch.Framework
{
    public class DuplicateByDimensionsAttribute: Attribute
    {
        private string[] _dimensions;

        public DistributeByCapabilitiesAttribute(params string[] dimensions)
        {
            _dimensions = dimensions;
        }

        public string[] Dimensions
        {
            get { return _dimensions; }
        }
    }
}

You can declare this in your own code if you want NCrunch to use it - or otherwise reference the attribute from NCrunch.Framework.dll.

Usage Example

The following example will create 3 tests with the same name, each with a different dimension shown in the Tests Window. Inside the code of these tests, each will call a different method as determined by the call to the NCrunchEnvironment.GetDuplicatedDimension method.

public class MyTestFixture
{
  [Test]
  [NCrunch.Framework.DuplicateByDimensions("ABC", "XYZ", "123")]
  public void MyTest()
  {
    var dimension = NCrunch.Framework.NCrunchEnvironment.GetDuplicatedDimension();

    if (dimension == "ABC")
      firstTestCase();
    else if (dimension == "XYZ")
      secondTestCase();
    else if (dimension == "123")
      thirdTestCase();
  }

  private void firstTestCase()
  {
  }

  private void secondTestCase()
  {
  }

  private void thirdTestCase()
  {
  }
}

Recommendations

This attribute can be used for executing a test suite across multiple platforms, where the platform is chosen at runtime during the test.

It can also provide a simple way to perform parameteried testing outside the constaints of the test framework(s) in use.