Rystem.Test.XUnit 10.0.7

What is Rystem?

Rystem.Test.XUnit

Rystem.Test.XUnit is a test-project helper for xUnit v3 that combines constructor injection with an optional in-process ASP.NET Core test host.

The package builds on Xunit.DependencyInjection and adds a StartupHelper model so your test project can choose between:

• DI-only tests
• full HTTP integration tests with Microsoft.AspNetCore.TestHost

It is most useful when:

• you want test classes to receive services directly in their constructors
• you want one reusable test startup pipeline for a whole test assembly
• you want an in-process API host without managing your own WebApplicationFactory
• you want to reuse the same Rystem DI and runtime service patterns inside tests

The strongest source-backed examples are the package implementation itself and the real startup used by src/Core/Test/Rystem.Test.UnitTest/Startup.cs plus the HTTP tests in src/Core/Test/Rystem.Test.UnitTest/RuntimeServiceProvider/RuntimeServiceProviderTest.cs.

Resources

• Complete Documentation: https://rystem.net
• MCP Server for AI: https://rystem.cloud/mcp
• Discord Community: https://discord.gg/tkWvy4WPjt
• Support the Project: https://www.buymeacoffee.com/keyserdsoze

Installation

dotnet add package Rystem.Test.XUnit

The current 10.x package targets net10.0 and references:

• Microsoft.NET.Test.Sdk
• Microsoft.AspNetCore.TestHost
• xunit.v3
• Xunit.DependencyInjection
• Rystem.DependencyInjection.Web
• Rystem.Concurrency

The package is designed for xUnit v3 projects, not the older xunit package line.

Package Architecture

The package is centered around three main pieces.

At a high level, the flow is:

• xUnit bootstraps the test assembly through Xunit.DependencyInjection
• your test project provides a Startup : StartupHelper
• ConfigureHost(...) builds configuration for the test run
• ConfigureServices(...) either configures DI only or starts the shared test host
• constructor injection works for all test classes in the assembly

Table of Contents

• Package Architecture
• How it Works
• Implement a Startup Class
• StartupHelper Reference
  • Required members
  • Optional members
• DI-only Tests
• HTTP Integration Tests with Test Host
• Shared Test Server Behavior
• IHttpClientFactory in Tests
• Repository Examples

How it Works

StartupHelper exposes two framework-facing methods that Xunit.DependencyInjection can call:

• ConfigureHost(IHostBuilder)
• ConfigureServices(IServiceCollection, HostBuilderContext)

From the current implementation:

• ConfigureHost(...) loads AppSettingsFileName, then optional user secrets, then environment variables
• ConfigureServices(...) checks HasTestHost
• if HasTestHost = true, it calls HostTester.CreateHostServerAsync(...)
• the shared TestHttpClientFactory is then registered into the test DI container
• ConfigureClientServices(...) always runs and is where you add the services that test classes consume

So the package gives you one central startup object for both configuration and test DI wiring.

Implement a Startup Class

Create a Startup class in the test project that inherits from StartupHelper.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Rystem.Test.XUnit;

public sealed class Startup : StartupHelper
{
    protected override string? AppSettingsFileName => "appsettings.test.json";
    protected override bool HasTestHost => false;
    protected override Type? TypeToChooseTheRightAssemblyToRetrieveSecretsForConfiguration => typeof(Startup);
    protected override Type? TypeToChooseTheRightAssemblyWithControllersToMap => null;

    protected override IServiceCollection ConfigureClientServices(
        IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddMyBusinessLogic();
        return services;
    }
}

The real project already contains a concrete example in src/Core/Test/Rystem.Test.UnitTest/Startup.cs, where:

• HasTestHost is true
• controllers are mapped from the API assembly containing ServiceController
• client DI gets an HttpClient named client
• server DI gets application services from AddTestServices()

StartupHelper Reference

Required members

StartupHelper requires these members:

Even when the host is enabled, ConfigureClientServices(...) is still the place for the services injected into the tests themselves.

Optional members

These virtual members can be overridden when needed:

If HasTestHost is false, the server-specific members are effectively ignored.

DI-only Tests

Use this mode when you only need constructor injection and no HTTP pipeline.

public sealed class Startup : StartupHelper
{
    protected override string? AppSettingsFileName => "appsettings.test.json";
    protected override bool HasTestHost => false;
    protected override Type? TypeToChooseTheRightAssemblyToRetrieveSecretsForConfiguration => typeof(Startup);
    protected override Type? TypeToChooseTheRightAssemblyWithControllersToMap => null;

    protected override IServiceCollection ConfigureClientServices(
        IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddMyRepositories();
        services.AddMyBusinessLogic();
        return services;
    }
}

public sealed class OrderServiceTest
{
    private readonly IOrderService _orderService;

    public OrderServiceTest(IOrderService orderService)
    {
        _orderService = orderService;
    }

    [Fact]
    public async Task CreateOrder_ShouldReturnValidOrder()
    {
        var order = await _orderService.CreateAsync(new CreateOrderRequest { ProductId = 1 });
        Assert.NotNull(order);
    }
}

In this mode, the package behaves mainly as an xUnit DI bootstrapper.

HTTP Integration Tests with Test Host

Use this mode when the tests should hit a real ASP.NET Core pipeline in-process.

A trimmed version looks like this:

using Microsoft.AspNetCore.Builder;

public sealed class Startup : StartupHelper
{
    protected override string? AppSettingsFileName => "appsettings.test.json";
    protected override bool HasTestHost => true;
    protected override Type? TypeToChooseTheRightAssemblyToRetrieveSecretsForConfiguration => typeof(Startup);
    protected override Type? TypeToChooseTheRightAssemblyWithControllersToMap => typeof(Program);

    protected override IServiceCollection ConfigureClientServices(
        IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddHttpClient("client", x =>
        {
            x.BaseAddress = new Uri("https://localhost:443");
        });
        return services;
    }

    protected override ValueTask ConfigureServerServicesAsync(
        IServiceCollection services,
        IConfiguration configuration)
    {
        services.AddControllers();
        services.AddMyApiServices();
        return ValueTask.CompletedTask;
    }

    protected override ValueTask ConfigureServerMiddlewareAsync(
        IApplicationBuilder app,
        IServiceProvider serviceProvider)
    {
        app.UseRouting();
        app.UseEndpoints(endpoints => endpoints.MapControllers());
        return ValueTask.CompletedTask;
    }
}

The real repository example is src/Core/Test/Rystem.Test.UnitTest/Startup.cs.

And a real HTTP test using constructor injection is src/Core/Test/Rystem.Test.UnitTest/RuntimeServiceProvider/RuntimeServiceProviderTest.cs:

public class RuntimeServiceProviderTest
{
    private readonly HttpClient _httpClient;

    public RuntimeServiceProviderTest(IHttpClientFactory httpClientFactory)
    {
        _httpClient = httpClientFactory.CreateClient("client");
    }

    [Fact]
    public async Task AddOneServiceAtRuntimeAsync()
    {
        var response = await _httpClient.GetAsync("Service/Get");
        Assert.True(response.IsSuccessStatusCode);
    }
}

That pattern is the core value of the package: tests can just request IHttpClientFactory, typed clients, repositories, or any other service directly in their constructors.

Shared Test Server Behavior

When HasTestHost = true, HostTester creates the in-process server lazily and only once.

Important implementation details:

• server creation is guarded with Rystem.Concurrency via ILock
• the built host is stored on the singleton TestHttpClientFactory.Instance
• later test classes reuse the same host instead of rebuilding it
• controllers are discovered with AddApplicationPart(...)
• if AddHealthCheck = true, the framework maps /healthz and performs a startup probe after the host starts

No real TCP port is opened. The package uses Microsoft.AspNetCore.TestHost, so requests stay in-process.

IHttpClientFactory in Tests

When the test host is enabled, ConfigureServices(...) registers:

services.AddSingleton<IHttpClientFactory>(TestHttpClientFactory.Instance);

TestHttpClientFactory creates clients from the shared TestServer and pre-populates these request headers:

That means tests can either:

• inject IHttpClientFactory directly
• register named or typed clients in ConfigureClientServices(...)

Example:

public sealed class HealthCheckTest
{
    private readonly HttpClient _httpClient;

    public HealthCheckTest(IHttpClientFactory factory)
    {
        _httpClient = factory.CreateClient();
    }

    [Fact]
    public async Task HealthCheck_ShouldBeHealthy()
    {
        var response = await _httpClient.GetAsync("/healthz");
        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
    }
}

Repository Examples

The most useful references for this package are:

• StartupHelper: src/Extensions/Tests/Rystem.Test.XUnit/TestHostWithDi/StartupHelper.cs
• Shared test host builder: src/Extensions/Tests/Rystem.Test.XUnit/TestHostWithDi/HostTester.cs
• Test HTTP client factory: src/Extensions/Tests/Rystem.Test.XUnit/TestHostWithDi/TestHttpClientFactory.cs
• Real startup example: src/Core/Test/Rystem.Test.UnitTest/Startup.cs
• Real HTTP integration tests: src/Core/Test/Rystem.Test.UnitTest/RuntimeServiceProvider/RuntimeServiceProviderTest.cs
• Test API used by that startup: src/Extensions/Tests/Test/Rystem.Test.TestApi/Program.cs

This README is intentionally architecture-first because Rystem.Test.XUnit is mostly infrastructure. The main value is not a long API surface, but the way it composes xUnit DI, configuration loading, and an optional shared in-process ASP.NET Core host.