Skip to content

About

An XUnit Test Framework implementation allowing long lived fixtures without giving up concurrency.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

nullean

Partitions for xUnit: share a few expensive, long-lived objects (a container, a server, a browser) across thousands of tests, set up just before the tests that need them and torn down right after, one partition at a time.

NuGet CI

using AwesomeAssertions;
using Nullean.Xunit.Partitions.v3.Sdk;
using Xunit;

// The shared state: initialised just before its partition's tests run, disposed right after.
public class Database : IPartitionLifetime
{
	private static int _starts;
	public int Starts => _starts;

	public ValueTask InitializeAsync()
	{
		Interlocked.Increment(ref _starts);   // start a container, a server, a browser...
		return default;
	}

	public ValueTask DisposeAsync() => default;

	public int? MaxConcurrency => null;        // test classes run at once; null for the default
	public string FailureTestOutput() => "";   // reported on every test of the partition if InitializeAsync throws
}

public class OrderTests(Database db) : IPartitionFixture<Database>
{
	[Fact]
	public void StartedOnce() => db.Starts.Should().Be(1);
}

public class CustomerTests(Database db) : IPartitionFixture<Database>
{
	[Fact]
	public void SharesTheInstance() => db.Starts.Should().Be(1);
}

Install

dotnet add package Nullean.Xunit.Partitions.v3   # xUnit v3
dotnet add package Nullean.Xunit.Partitions      # xUnit v2

Quick start

Register the partition test framework once, anywhere in the test project (xUnit v3):

using Nullean.Xunit.Partitions.v3;
using Xunit;

[assembly: TestFramework(typeof(PartitionTestFramework))]

Then give the shared state an IPartitionLifetime and let test classes ask for it with IPartitionFixture<T>, as above: OrderTests and CustomerTests receive one shared Database, after its InitializeAsync has run. xUnit's analyzer reports partition fixtures as xUnit1041; add <NoWarn>$(NoWarn);xUnit1041</NoWarn> to the test project.

  • One partition at a time. No partition runs concurrently with another, by design, so each partition's state can run expensive operations (start Docker containers or processes, bootstrap Playwright) in isolation.
  • Concurrent inside a partition. Unlike xUnit's ICollectionFixture<T>, a partition is not a concurrency barrier: the test classes that share a partition run concurrently.
  • Just in time. InitializeAsync runs right before a partition's tests and DisposeAsync right after, before the next partition initialises. Assembly fixtures bootstrap too early and dispose too late.
  • No partition is a partition too. Test classes without IPartitionFixture<T> run together, concurrently, as one more partition.
  • If InitializeAsync throws, every test of the partition fails with the exception and the text of FailureTestOutput(), such as a server's log.
  • MaxConcurrency is how many of the partition's test classes run at once. The runner uses the larger of it and its default, 4 x the processor count, so only a higher value changes anything; null keeps the default.

If you want to share a few (say 0 to 20) long-running objects over thousands of tests, this library will work for you. If you instead have many test collections each with only a few tests, xUnit's own collections suit better.

Filter which partitions and test classes run with an options class; filtered-out tests are reported as skipped. OnBeforeTestsRun() and OnTestsFinished(...) can be overridden for logging or reporting.

using Nullean.Xunit.Partitions.v3;

[assembly: PartitionOptions(typeof(MyPartitioningOptions))]

public class MyPartitioningOptions : PartitionOptions
{
	public MyPartitioningOptions()
	{
		PartitionFilterRegex = "Database";   // only run partitions whose lifetime type name matches
		TestFilterRegex = null;              // only run test classes whose name matches (null = all)
	}
}

For xUnit v2 the framework is registered with [assembly: TestFramework(Partition.TestFramework, Partition.Assembly)] and the lifetime methods return Task; see the v2 package README and the migration table.

Packages

Package What it is
Nullean.Xunit.Partitions.v3 Partitions for xUnit v3 NuGet
Nullean.Xunit.Partitions Partitions for xUnit v2 NuGet

Learn more

MIT licensed. Copyright Nullean and contributors.

About

An XUnit Test Framework implementation allowing long lived fixtures without giving up concurrency.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages