backend-testing

Backend testing with xUnit, Foundatio.Xunit, integration tests with AppWebHostFactory,FluentClient, ProxyTimeProvider for time manipulation, and test data builders.Keywords: xUnit, Fact, Theory, integration tests, AppWebHostFactory, FluentClient,ProxyTimeProvider, TimeProvider, Foundatio.Xunit, TestWithLoggingBase, test data builders

⭐2.4kstars🔀513forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for .NET backend testing, specializing in integration and unit testing using xUnit and Foundatio.Xunit. It offers a robust set of tools including custom WebApplicationFactory patterns, a fluent HTTP client for API testing, and advanced time manipulation utilities to ensure high-quality, reliable software delivery through a TDD-oriented workflow.

Use Cases

  • Automating integration tests for .NET Web APIs using AppWebHostFactory to simulate real-world hosting environments.
  • Simplifying complex API interactions in tests using a FluentClient with built-in authentication helpers for various user roles.
  • Testing time-sensitive business logic by manipulating system time with ProxyTimeProvider without affecting the host machine.
  • Generating isolated and reproducible test data using fluent Data Builders to maintain database consistency across test suites.
  • Implementing a Test-Driven Development (TDD) cycle by leveraging standardized base classes for logging and dependency injection.
nameBackend Testing
description|
KeywordsxUnit, Fact, Theory, integration tests, AppWebHostFactory, FluentClient,

Backend Testing

Running Tests

# All tests
dotnet test

# By test name
dotnet test --filter "FullyQualifiedName~CanPostUserDescriptionAsync"

# By class name
dotnet test --filter "ClassName~EventControllerTests"

Test Folder Structure

Tests mirror the source structure:

tests/Exceptionless.Tests/
├── AppWebHostFactory.cs         # WebApplicationFactory for integration tests
├── IntegrationTestsBase.cs      # Base class for integration tests
├── TestWithServices.cs          # Base class for unit tests with DI
├── Controllers/                 # API controller tests
├── Jobs/                        # Job tests
├── Repositories/                # Repository tests
├── Services/                    # Service tests
├── Utility/                     # Test data builders
│   ├── AppSendBuilder.cs        # Fluent HTTP request builder
│   ├── DataBuilder.cs           # Test data creation
│   ├── EventData.cs
│   ├── OrganizationData.cs
│   ├── ProjectData.cs
│   ├── ProxyTimeProvider.cs     # Time manipulation
│   └── ...
└── Validation/                  # Validator tests

Integration Test Base Pattern

Inherit from IntegrationTestsBase which uses Foundatio.Xunit's TestWithLoggingBase:

// From tests/Exceptionless.Tests/IntegrationTestsBase.cs
public abstract class IntegrationTestsBase : TestWithLoggingBase, IAsyncLifetime, IClassFixture<AppWebHostFactory>
{
    protected readonly TestServer _server;
    private readonly ProxyTimeProvider _timeProvider;

    public IntegrationTestsBase(ITestOutputHelper output, AppWebHostFactory factory) : base(output)
    {
        _server = factory.Server;
        _timeProvider = GetService<ProxyTimeProvider>();
    }

    protected TService GetService<TService>() where TService : notnull
        => ServiceProvider.GetRequiredService<TService>();

    protected FluentClient CreateFluentClient()
    {
        var settings = GetService<JsonSerializerSettings>();
        return new FluentClient(CreateHttpClient(), new NewtonsoftJsonSerializer(settings));
    }
}

Real Test Example

From EventControllerTests.cs:

public class EventControllerTests : IntegrationTestsBase
{
    private readonly IEventRepository _eventRepository;
    private readonly IQueue<EventPost> _eventQueue;

    public EventControllerTests(ITestOutputHelper output, AppWebHostFactory factory) : base(output, factory)
    {
        _eventRepository = GetService<IEventRepository>();
        _eventQueue = GetService<IQueue<EventPost>>();
    }

    [Fact]
    public async Task CanPostUserDescriptionAsync()
    {
        const string json = "{\"message\":\"test\",\"reference_id\":\"TestReferenceId\"}";

        await SendRequestAsync(r => r
            .Post()
            .AsTestOrganizationClientUser()
            .AppendPath("events")
            .Content(json, "application/json")
            .StatusCodeShouldBeAccepted()
        );

        var stats = await _eventQueue.GetQueueStatsAsync();
        Assert.Equal(1, stats.Enqueued);

        var processEventsJob = GetService<EventPostsJob>();
        await processEventsJob.RunAsync();
        await RefreshDataAsync();

        var events = await _eventRepository.GetAllAsync();
        var ev = events.Documents.Single(e => e.Type == Event.KnownTypes.Log);
        Assert.Equal("test", ev.Message);
    }
}

FluentClient Pattern

Use SendRequestAsync with AppSendBuilder for HTTP testing:

await SendRequestAsync(r => r
    .Post()
    .AsTestOrganizationUser()          // Basic auth with test user
    .AppendPath("organizations")
    .Content(new NewOrganization { Name = "Test" })
    .StatusCodeShouldBeCreated()
);

// Available auth helpers
r.AsGlobalAdminUser()          // TEST_USER_EMAIL
r.AsTestOrganizationUser()     // TEST_ORG_USER_EMAIL
r.AsFreeOrganizationUser()     // FREE_USER_EMAIL
r.AsTestOrganizationClientUser() // API key bearer token

Test Data Builders

Create test data with CreateDataAsync:

var (stacks, events) = await CreateDataAsync(b => b
    .Event()
    .TestProject()
    .Type(Event.KnownTypes.Error)
    .Message("Test error"));

Assert.Single(stacks);
Assert.Single(events);

Time Manipulation with ProxyTimeProvider

NOT ISystemClock — use .NET 8+ TimeProvider with ProxyTimeProvider:

// Access via protected property
protected ProxyTimeProvider TimeProvider => _timeProvider;

// Advance time
TimeProvider.Advance(TimeSpan.FromHours(1));

// Set specific time
TimeProvider.SetUtcNow(new DateTimeOffset(2024, 1, 15, 12, 0, 0, TimeSpan.Zero));

// Restore to system time
TimeProvider.Restore();

Registered in test services:

services.ReplaceSingleton<TimeProvider>(_ => new ProxyTimeProvider());

Test Principles

  • TDD workflow — When fixing bugs or adding features, write a failing test first
  • Use real serializer — Tests use the same JSON serializer as production
  • Use real time provider — Manipulate via ProxyTimeProvider when needed
  • Refresh after writes — Call RefreshDataAsync() after database changes
  • Clean state — ResetDataAsync() clears data between tests

Foundatio.Xunit

Base class provides logging integration:

using Foundatio.Xunit;

public class MyTests : TestWithLoggingBase
{
    public MyTests(ITestOutputHelper output) : base(output)
    {
        Log.DefaultLogLevel = LogLevel.Information;
    }
}