Excalibur.Dispatch.Testing 3.0.0-alpha.189

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 3.0.0-alpha.189

NuGet\Install-Package Excalibur.Dispatch.Testing -Version 3.0.0-alpha.189

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="3.0.0-alpha.189" />

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

<PackageVersion Include="Excalibur.Dispatch.Testing" Version="3.0.0-alpha.189" />
                    

                            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 3.0.0-alpha.189

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

#r "nuget: Excalibur.Dispatch.Testing, 3.0.0-alpha.189"

#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@3.0.0-alpha.189

#: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=3.0.0-alpha.189&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=Excalibur.Dispatch.Testing&version=3.0.0-alpha.189&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 (>= 3.0.0-alpha.189)
- Excalibur.Dispatch.Abstractions (>= 3.0.0-alpha.189)
- Excalibur.Dispatch.Transport.Abstractions (>= 3.0.0-alpha.189)
- Medo.Uuid7 (>= 3.2.0)
- Microsoft.AspNetCore.Authorization (>= 10.0.7)
- Microsoft.Extensions.Configuration (>= 10.0.7)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.7)
- Microsoft.Extensions.DependencyInjection (>= 10.0.7)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.7)
- Microsoft.Extensions.Diagnostics.HealthChecks.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.7)
- Microsoft.Extensions.Http (>= 10.0.7)
- Microsoft.Extensions.Logging (>= 10.0.7)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.7)
- Microsoft.Extensions.ObjectPool (>= 10.0.7)
- Microsoft.Extensions.Options (>= 10.0.7)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.7)
- Microsoft.Extensions.Options.DataAnnotations (>= 10.0.7)
- 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.	3.1K

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
3.0.0-alpha.193	40	5/13/2026
3.0.0-alpha.192	31	5/13/2026
3.0.0-alpha.191	33	5/13/2026
3.0.0-alpha.189	35	5/12/2026
3.0.0-alpha.187	56	5/8/2026
3.0.0-alpha.185	51	5/7/2026
3.0.0-alpha.183	48	5/7/2026
3.0.0-alpha.182	47	5/6/2026
3.0.0-alpha.181	41	5/6/2026
3.0.0-alpha.179	43	5/6/2026
3.0.0-alpha.178	50	4/25/2026
3.0.0-alpha.177	50	4/25/2026
3.0.0-alpha.176	49	4/25/2026
3.0.0-alpha.175	55	4/24/2026
3.0.0-alpha.174	50	4/24/2026
3.0.0-alpha.173	46	4/24/2026
3.0.0-alpha.170	52	4/23/2026
3.0.0-alpha.168	56	4/23/2026
3.0.0-alpha.165	55	4/22/2026
3.0.0-alpha.164	45	4/22/2026