Excalibur.Dispatch.Testing 10.0.0-alpha.4

This is a prerelease version of Excalibur.Dispatch.Testing.

There is a newer prerelease version of this package available.
See the version list below for details.

dotnet add package Excalibur.Dispatch.Testing --version 10.0.0-alpha.4

NuGet\Install-Package Excalibur.Dispatch.Testing -Version 10.0.0-alpha.4

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Excalibur.Dispatch.Testing" Version="10.0.0-alpha.4" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Excalibur.Dispatch.Testing" Version="10.0.0-alpha.4" />
                    

                            Directory.Packages.props

<PackageReference Include="Excalibur.Dispatch.Testing" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Excalibur.Dispatch.Testing --version 10.0.0-alpha.4

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Excalibur.Dispatch.Testing, 10.0.0-alpha.4"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Excalibur.Dispatch.Testing@10.0.0-alpha.4

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Excalibur.Dispatch.Testing&version=10.0.0-alpha.4&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=Excalibur.Dispatch.Testing&version=10.0.0-alpha.4&prerelease
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Excalibur.Dispatch.Testing

Test infrastructure for the Dispatch messaging pipeline. Provides a lightweight, framework-agnostic test harness with message tracking, fluent builders, and spy middleware.

Installation

dotnet add package Excalibur.Dispatch.Testing

Features

DispatchTestHarness - Lazy-build DI container for testing Dispatch pipelines
MessageContextBuilder - Fluent API for creating test message contexts
IDispatchedMessageLog/DispatchedMessageLog - In-memory message tracking
TestTrackingMiddleware - Spy middleware for observing pipeline execution
Framework-agnostic - Works with xUnit, NUnit, MSTest, or any test framework

Quick Start

// Create harness and configure pipeline
var harness = new DispatchTestHarness();
harness.ConfigureDispatch(d => d.AddHandlersFromAssembly(typeof(MyHandler).Assembly));

// Dispatch messages
await harness.Dispatcher.DispatchAsync(new MyCommand(), CancellationToken.None);

// Verify dispatched messages
harness.Dispatched.Count.ShouldBe(1);
harness.Dispatched.All[0].Message.ShouldBeOfType<MyCommand>();

// Clean up
await harness.DisposeAsync();

DispatchTestHarness

Lazy-build service provider that accumulates DI registrations and builds the container on first access.

var harness = new DispatchTestHarness();

// Configure services (accumulates until first access)
harness.ConfigureServices(services =>
{
    services.AddSingleton<IMyService, MyService>();
});

// Configure Dispatch pipeline
harness.ConfigureDispatch(d =>
{
    d.AddHandlersFromAssembly(typeof(MyHandler).Assembly);
    d.AddMiddleware<ValidationMiddleware>();
});

// ServiceProvider built on first property access
var dispatcher = harness.Dispatcher;
var log = harness.Dispatched;

MessageContextBuilder

Fluent API for creating test message contexts with custom properties, cancellation tokens, and metadata.

var context = new MessageContextBuilder()
    .WithMessage(new MyCommand { Id = 123 })
    .WithUserId("user-123")
    .WithTenantId("tenant-42")
    .WithCorrelationId("corr-abc")
    .Build();

await dispatcher.DispatchAsync(context);

IDispatchedMessageLog

In-memory log that captures all messages dispatched during tests.

// Access via harness
var log = harness.Dispatched;

// Query dispatched messages
log.Count.ShouldBe(3);
log.Select<OrderCreated>().Count.ShouldBe(1);
log.All.Count(m => m.Message is OrderUpdated).ShouldBe(2);

// Clear log between test phases
log.Clear();

TestTrackingMiddleware

Spy middleware automatically registered by DispatchTestHarness. Captures all messages passing through the pipeline.

// Automatically registered - no manual setup needed
var harness = new DispatchTestHarness();
harness.ConfigureDispatch(d => d.AddHandlersFromAssembly(typeof(MyHandler).Assembly));

// Middleware captures messages as they flow through pipeline
await harness.Dispatcher.DispatchAsync(new MyCommand());

// Verify via Dispatched log
harness.Dispatched.All.ShouldContain(m => m.Message is MyCommand);

Integration with Testing.Shouldly

For fluent assertions, add the companion package:

dotnet add package Excalibur.Dispatch.Testing.Shouldly

// Fluent Shouldly extensions
harness.Dispatched.ShouldHaveDispatched<OrderCreated>();
harness.Dispatched.ShouldNotHaveDispatched<OrderCancelled>();
sender.ShouldHaveSent(3);
receiver.ShouldHaveAcknowledged(2);

See Excalibur.Dispatch.Testing.Shouldly for details.

Complete Example

public class OrderHandlerTests : IAsyncDisposable
{
    private readonly DispatchTestHarness _harness = new();

    public OrderHandlerTests()
    {
        _harness.ConfigureServices(services =>
        {
            services.AddSingleton<IOrderRepository, InMemoryOrderRepository>();
        });

        _harness.ConfigureDispatch(d =>
        {
            d.AddHandlersFromAssembly(typeof(OrderHandler).Assembly);
        });
    }

    [Fact]
    public async Task CreateOrder_ShouldDispatchOrderCreatedEvent()
    {
        // Arrange
        var command = new CreateOrderCommand { ProductId = 123, Quantity = 2 };

        // Act
        await _harness.Dispatcher.DispatchAsync(command, CancellationToken.None);

        // Assert
        _harness.Dispatched.Count.ShouldBe(1);
        var evt = _harness.Dispatched.All[0].Message.ShouldBeOfType<OrderCreated>();
        evt.ProductId.ShouldBe(123);
        evt.Quantity.ShouldBe(2);
    }

    public async ValueTask DisposeAsync()
    {
        await _harness.DisposeAsync();
    }
}

License

MIT

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- CloudNative.CloudEvents (>= 2.8.0)
- CloudNative.CloudEvents.SystemTextJson (>= 2.8.0)
- Cronos (>= 0.12.0)
- Excalibur.Dispatch (>= 10.0.0-alpha.4)
- Excalibur.Dispatch.Abstractions (>= 10.0.0-alpha.4)
- Excalibur.Dispatch.Transport.Abstractions (>= 10.0.0-alpha.4)
- Medo.Uuid7 (>= 3.2.0)
- Microsoft.AspNetCore.Authorization (>= 10.0.7)
- Microsoft.Extensions.Configuration (>= 10.0.10)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.10)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.10)
- Microsoft.Extensions.DependencyInjection (>= 10.0.10)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.10)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.10)
- Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions (>= 10.0.10)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.10)
- Microsoft.Extensions.Http (>= 10.0.10)
- Microsoft.Extensions.Logging (>= 10.0.10)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.10)
- Microsoft.Extensions.ObjectPool (>= 10.0.10)
- Microsoft.Extensions.Options (>= 10.0.10)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.10)
- Microsoft.Extensions.Options.DataAnnotations (>= 10.0.10)
- System.Threading.RateLimiting (>= 10.0.7)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Excalibur.Dispatch.Testing:

Package	Downloads
Excalibur.Dispatch.Testing.Shouldly Shouldly assertion extensions for the Excalibur testing utilities. Provides fluent assertions for DispatchTestHarness message logs, InMemoryTransportSender, InMemoryTransportReceiver, and InMemoryTransportSubscriber. PRE-RELEASE: the public API is not frozen and may change between pre-release builds. Not recommended for production use. Known issues: https://docs.excalibur-dispatch.dev/docs/known-issues	4.8K

Package

Downloads

Excalibur.Dispatch.Testing.Shouldly

Shouldly assertion extensions for the Excalibur testing utilities. Provides fluent assertions for DispatchTestHarness message logs, InMemoryTransportSender, InMemoryTransportReceiver, and InMemoryTransportSubscriber. PRE-RELEASE: the public API is not frozen and may change between pre-release builds. Not recommended for production use. Known issues: https://docs.excalibur-dispatch.dev/docs/known-issues

4.8K

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
10.0.0-alpha.9	41	8/31/2026
10.0.0-alpha.8	64	8/14/2026
10.0.0-alpha.7	58	8/13/2026
10.0.0-alpha.6	63	8/11/2026
10.0.0-alpha.5	52	8/10/2026
10.0.0-alpha.4	56	8/10/2026
3.0.0-alpha.216	79	6/30/2026
3.0.0-alpha.215	74	6/23/2026
3.0.0-alpha.214	73	6/23/2026
3.0.0-alpha.208	75	6/11/2026
3.0.0-alpha.207	72	6/11/2026
3.0.0-alpha.205	73	6/10/2026
3.0.0-alpha.204	72	6/8/2026
3.0.0-alpha.203	72	6/8/2026
3.0.0-alpha.202	67	6/8/2026
3.0.0-alpha.201	73	6/8/2026
3.0.0-alpha.199	72	6/8/2026
3.0.0-alpha.198	67	5/28/2026
3.0.0-alpha.197	79	5/28/2026
3.0.0-alpha.194	69	5/20/2026

See CHANGELOG.md for release notes