NCrunch.Framework.InclusivelyUsesAttribute

Purpose

The InclusivelyUsesAttribute can be used to mark tests (or test fixtures) as making constrained use of a specific set of resources. The primary reason for this is to prevent concurrent execution of tests that do not support it.

This attribute can be found in the NCrunch.Framework assembly, which you can reference from your test project to make use of NCrunch's run-time features.

The attribute can be applied to both fixtures and tests, and also supports inheritance.

The attribute can also be applied at assembly level, in which case all tests within the assembly will be considered as making inclusive use of the specified resources.

When declaring the attribute, you specify a sequence of string values that are used to identify the resources your test is relying on during its execution. Any tests that make exclusive use (via ExclusivelyUsesAttribute) of one of the specified resources will be considered mutually exclusive with the decorated test and will not be run at the same time by NCrunch.

Note that the resource name declared with InclusivelyUsesAttribute is effectively no more than an arbitrary mutex that prevents certain tests from running concurrently - it does not need to correspond to a physical resource on the system. Resource naming is done purely for the sake of convention.

Declaration In NCrunch.Framework.dll

namespace NCrunch.Framework
{
    public abstract class ResourceUsageAttribute: Attribute
    {
        private readonly string[] _resourceNames;

        public ResourceUsageAttribute(params string[] resourceName)
        {
            _resourceNames = resourceName;
        }

        public string[] ResourceNames
        {
            get { return _resourceNames; }
        }
    }

    public class InclusivelyUsesAttribute: ResourceUsageAttribute
    {
        public InclusivelyUsesAttribute(params string[] resourceName) 
			: base(resourceName) {}
    }
}

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

[NCrunch.Framework.InclusivelyUses("Database", @"c:\logfile")]
[Test]
public void MyTest()
{
	...

Recommendations

Because this attribute marks resource usages as inclusive, the test will not be mutually exclusive with other tests that also make inclusive use of any the same resources. Therefore this attribute is only effective when used in combination with the ExclusivelyUsesAttribute.

Tests most commonly need to make use of the InclusivelyUsesAttribute and ExclusivelyUsesAttribute when they are interacting with key files on the file system, with a database, or using a specific socket connection.

It is considered good practice to engineer your tests so that they do not need exclusive use of resources. Make use of random file names, random socket numbers and isolated database transactions where ever possible. Doing so will reduce the constraints on NCrunch's execution engine and reduce your test cycle times.

In the Tests Window, it is possible to view which tests are making inclusive/exclusive use of resources. Simply right click the column header and select the 'Inclusively Used Resources' column.