xunit.v3.extensions.ordering 0.3.0

xunit.v3.extensions.ordering

Deterministic ordering for xUnit.net v3.

Inspired by Xunit.Extensions.Ordering, but built specifically for xUnit v3.

Why?

xUnit does not guarantee execution order between tests, classes, or collections.

This package provides a simple and consistent way to control test execution order of test methods, test classes, and test collections using a single [Order] attribute.

Installation

dotnet add package xunit.v3.extensions.ordering

Setup

Register once in your test project (for example in TestSetup.cs):

using Xunit;
using Xunit.v3.Extensions.Ordering;

[assembly: TestFramework(typeof(OrderedTestFramework))]
[assembly: CollectionBehavior(DisableTestParallelization = true)]
[assembly: TestCaseOrderer(typeof(OrderedTestCaseOrderer))]
[assembly: TestCollectionOrderer(typeof(OrderedTestCollectionOrderer))]

Note: The [Order] attribute lives in the Xunit namespace — no extra using needed in test files. The using Xunit.v3.Extensions.Ordering import is only required in the setup file for the infrastructure classes (OrderedTestFramework, OrderedTestCaseOrderer, OrderedTestCollectionOrderer).

OrderedTestFramework replaces xUnit's default execution pipeline to enable class ordering. If you only need method and collection ordering, you can omit the TestFramework line.

If collection or class order matters, parallelization should be disabled. Otherwise xUnit may run collections in parallel and ignore ordering.

Usage

Order test methods

using Xunit;

public class CheckoutTests
{
    [Fact, Order(1)]
    public void AddItemToCart() { }

    [Fact, Order(2)]
    public void ApplyDiscount() { }

    [Fact, Order(3)]
    public void CompletePayment() { }
}

Runs in order:

AddItemToCart -> ApplyDiscount -> CompletePayment

Order test classes within a collection

Class ordering applies only within the same test collection.

Apply [Order] to test classes that share a collection:

[CollectionDefinition("Integration")]
public class IntegrationDefinition;

[Collection("Integration")]
[Order(1)]
public class SetupTests
{
    [Fact, Order(1)]
    public void CreateSchema() { }
}

[Collection("Integration")]
[Order(2)]
public class BusinessLogicTests
{
    [Fact, Order(1)]
    public void ValidateOrder() { }
}

[Collection("Integration")]
[Order(3)]
public class CleanupTests
{
    [Fact, Order(1)]
    public void DropTempData() { }
}

Execution order:

SetupTests -> BusinessLogicTests -> CleanupTests

Requires [assembly: TestFramework(typeof(OrderedTestFramework))] to be registered.

Order test collections

Apply [Order] to collection definitions:

[CollectionDefinition("Setup")]
[Order(1)]
public class SetupCollection;

[CollectionDefinition("Tests")]
[Order(2)]
public class TestsCollection;

[CollectionDefinition("Cleanup")]
[Order(3)]
public class CleanupCollection;

Behavior

• ordering is ascending (Order(1) runs before Order(2))
• negative values are allowed
• tests without [Order] default to 0
• same order values are resolved by name (deterministic)
• [Order] works on methods, classes, and collection definitions

How it works

The package provides:

The OrderedTestFramework replaces xUnit's default execution pipeline with a custom chain:

OrderedTestFramework -> OrderedTestFrameworkExecutor -> OrderedTestAssemblyRunner -> OrderedTestCollectionRunner

The OrderedTestCollectionRunner overrides RunTestClasses() to sort test classes by their [Order] attribute before execution.

Migration notes

If you used Xunit.Extensions.Ordering (v2):

• [Order] works the same way
• registration now uses typeof(...) instead of strings
• class ordering requires [assembly: TestFramework(typeof(OrderedTestFramework))]
• assembly fixtures are handled natively by xUnit v3

License

MIT

Links

• GitHub Repository
• NuGet Package