# Event Subscribing

Objects associated with your tests have the ability to subscribe to lifecycle events generated by TUnit.

Objects associated with your tests can mean:

* The test class itself
* A custom class constructor
* Injected class parameter arguments
* Injected method parameter arguments
* Injected properties
* Associated attributes

The interfaces they can implement are:

* ITestRegisteredEventReceiver
* ITestStartEventReceiver
* ITestEndEventReceiver
* ILastTestInClassEventReceiver
* ILastTestInAssemblyEventReceiver
* ILastTestInTestSessionEventReceiver

This can be useful especially when generating data that you need to track and maybe dispose later. By hooking into these events, we can do things like track and dispose our objects when we need.

## Registration callbacks for injected properties[​](#registration-callbacks-for-injected-properties "Direct link to Registration callbacks for injected properties")

TUnit creates injected property values after the first `OnTestRegistered` pass, so that a receiver such as a `SkipAttribute` can skip the test before expensive data sources are created. An injected property value that implements `ITestRegisteredEventReceiver` receives its callback in a second pass, after the property values are resolved and before the test runs. The second pass uses the same `Order` sorting, but it always runs after every receiver from the first pass.

A property value can still call `SetParallelLimiter`, `SetSkipped` and the other `TestRegisteredContext` methods. If it skips the test, its shared data source objects have already been created.

## Registration callbacks for executors[​](#registration-callbacks-for-executors "Direct link to Registration callbacks for executors")

An executor that implements `ITestRegisteredEventReceiver` receives `OnTestRegistered` when a registration receiver installs it through `SetTestExecutor` or `SetHookExecutor`, unless it has already received the callback for that test. Its callback runs after the installing receiver returns. Dynamically installed executors are not globally sorted by their own `Order`.

Each receiver instance receives this callback at most once per test, using reference identity. This also applies when the same instance is already an eligible event object, installs itself, or is installed as both the test and hook executor. Distinct instances that compare equal still receive separate callbacks.

An explicit `[ParallelLimiter<T>]` takes precedence over a limiter set through `TestRegisteredContext.SetParallelLimiter`, including one set by an executor, regardless of callback order.

## Execution Stage Control[​](#execution-stage-control "Direct link to Execution Stage Control")

> **Note**: This feature is available on .NET 10.0+ only due to default interface member requirements.

For `ITestStartEventReceiver` and `ITestEndEventReceiver`, you can control when your event receivers execute relative to instance-level hooks (`[Before(Test)]` and `[After(Test)]`) by setting the `Stage` property.

### EventReceiverStage Options[​](#eventreceiverstage-options "Direct link to EventReceiverStage Options")

* **`EventReceiverStage.Early`**: Executes before instance-level hooks

  * Test start receivers run before `[Before(Test)]` hooks
  * Test end receivers run before `[After(Test)]` hooks

* **`EventReceiverStage.Late`** (default): Executes after instance-level hooks

  * Test start receivers run after `[Before(Test)]` hooks
  * Test end receivers run after `[After(Test)]` hooks

### When to Use Early Stage[​](#when-to-use-early-stage "Direct link to When to Use Early Stage")

Use `EventReceiverStage.Early` when your event receiver needs to:

* Initialize resources that instance-level hooks depend on
* Set up test context or environment before any test-specific setup runs
* Capture test state before any modifications from hooks

### When to Use Late Stage[​](#when-to-use-late-stage "Direct link to When to Use Late Stage")

Use `EventReceiverStage.Late` (the default) when your event receiver needs to:

* Access resources initialized by instance-level hooks
* Clean up after all test-specific teardown completes
* Log or report on final test state after all hooks have run

### Example: Early Stage Event Receiver[​](#example-early-stage-event-receiver "Direct link to Example: Early Stage Event Receiver")

```
public class DatabaseConnectionAttribute : Attribute, ITestStartEventReceiver

{

    private DbConnection? _connection;



    // Execute before [Before(Test)] hooks so the connection is available to them

    public EventReceiverStage Stage => EventReceiverStage.Early;



    public async ValueTask OnTestStart(TestContext context)

    {

        _connection = new NpgsqlConnection(connectionString);

        await _connection.OpenAsync();



        // Store connection in test context for use by hooks and test

        context.StateBag.GetOrAdd("DbConnection", _ => _connection);

    }

}



public class MyTests

{

    [Test]

    [DatabaseConnection] // Runs BEFORE BeforeTest hook

    public async Task TestWithDatabase()

    {

        // Database connection is already open and available

        TestContext.Current!.StateBag.TryGetValue<IDbConnection>("DbConnection", out var connection);

        // ... test logic

    }



    [Before(Test)]

    public void BeforeTest()

    {

        // Database connection is already available here

        TestContext.Current!.StateBag.TryGetValue<IDbConnection>("DbConnection", out var connection);

        // ... setup that needs the database

    }

}
```

### Example: Late Stage Event Receiver (Default)[​](#example-late-stage-event-receiver-default "Direct link to Example: Late Stage Event Receiver (Default)")

```
public class TestMetricsAttribute : Attribute, ITestEndEventReceiver

{

    // Late stage is the default, so this property is optional

    public EventReceiverStage Stage => EventReceiverStage.Late;



    public async ValueTask OnTestEnd(TestContext context)

    {

        // This runs AFTER all [After(Test)] hooks have completed

        // So we can capture the final test metrics including cleanup time

        await LogMetrics(context);

    }

}
```

### .NET Framework / .NET Standard 2.0 Behavior[​](#net-framework--net-standard-20-behavior "Direct link to .NET Framework / .NET Standard 2.0 Behavior")

On older frameworks that don't support default interface members (.NET Framework, .NET Standard 2.0), the `Stage` property is not available. All event receivers will execute at the `Late` stage (after instance-level hooks), which matches the historical behavior.

Each attribute will be new'd up for each test, so you are able to store state within the fields of your attribute class.

The `[ClassDataSource<T>]` uses these events to do the following:

* On Test Register > Increment Counts for Various Types (Global, Keyed, etc.)
* On Test Start > Initialise any objects if they have the `IAsyncInitializer` interface
* On Test End > If the object isn't shared, dispose it. Otherwise, decrement the count for the type.
* On Last Test for Class > Dispose the object being used to inject into that specific class
* On Last Test for Assembly > Dispose the object being used to inject into that specific assembly

Here's a simple Dependency Injection Class Constructor class subscribing to the TestEnd event in order to dispose the service scope when the test is finished:

```
public class DependencyInjectionClassConstructor : IClassConstructor, ITestEndEventReceiver

{

    private readonly IServiceProvider _serviceProvider = CreateServiceProvider();

    private AsyncServiceScope _scope;



    public Task<object> Create([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] Type type, ClassConstructorMetadata classConstructorMetadata)

    {

        _scope = _serviceProvider.CreateAsyncScope();



        var instance = ActivatorUtilities.GetServiceOrCreateInstance(_scope.ServiceProvider, type);

        return Task.FromResult(instance);

    }



    public ValueTask OnTestEnd(TestContext testContext)

    {

        return _scope.DisposeAsync();

    }



    private static IServiceProvider CreateServiceProvider()

    {

        return new ServiceCollection()

            .AddTransient<Class1>()

            .AddTransient<Class2>()

            .AddTransient<Class3>()

            ...

            .BuildServiceProvider();

    }

}
```
