NCrunch.Framework.ExclusivelyUsesAttribute

Purpose

The ExclusivelyUsesAttribute 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 exclusive 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 or inclusive (via InclusivelyUsesAttribute) use 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 ExclusivelyUsesAttribute is effectively no more than an arbitrary mutex that prevents two similarly attributed 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 ExclusivelyUsesAttribute: ResourceUsageAttribute
    {
        public ExclusivelyUsesAttribute(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.ExclusivelyUses("Database", @"c:\logfile")]
[Test]
public void MyTest()
{
	...

Recommendations

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 'Exclusively Used Resources' column.

Where a physical resource doesn't exist, you can simply substitute its name for the name of an arbitrary mutex. The main function of this attribute is to declare some kind of name that can never be shared by two tests executing at the same time. So you could just use 'ExclusivelyUsesAttribute("LocksFiles")' on all the tests that can experience file locking issues. This would be better than marking each test with SerialAttribute, as the tests with ExclusivelyUsesAttribute would be unable to run concurrently with each other, where the SerialAttribute tests cannot run concurrently with anything (i.e. you may have other tests that can run perfectly normally without ever caring about the file locks).