xUnitV3LoadFramework 2.0.0.57

xUnitV3LoadFramework

xUnit v3-native load-style test runner for executing actions concurrently over a duration and reporting throughput/success/failure.

What It Is / What It Isn't

Best for:

• CI performance smoke tests
• Concurrency and regression checks
• Integration-style load tests inside dotnet test
• Quick validation that your API handles N concurrent requests

Not for:

• Distributed load generation across machines
• Protocol-specific clients (HTTP/2, gRPC, WebSocket)
• Full observability platform with dashboards
• Replacing dedicated load testing tools (k6, Locust, NBomber)

Install

dotnet add package xUnitV3LoadFramework

Quickstart

Attribute-Based

using xUnitV3LoadFramework.Attributes;
using xUnitV3LoadFramework.Extensions;

public class ApiLoadTests
{
    private static readonly HttpClient _httpClient = new();

    [Load(concurrency: 5, duration: 3000, interval: 500)]
    public async Task Api_Should_Handle_Concurrent_Requests()
    {
        var result = await LoadTestRunner.ExecuteAsync(async () =>
        {
            var response = await _httpClient.GetAsync("https://api.example.com/health");
            return response.IsSuccessStatusCode;
        });

        Assert.True(result.Success > 0);
        Assert.True(result.RequestsPerSecond > 1);
    }
}

Fluent API

using xUnitV3LoadFramework.Extensions;

public class ApiLoadTests
{
    private static readonly HttpClient _httpClient = new();

    [Fact]
    public async Task Api_Load_Test_Fluent()
    {
        var result = await LoadTestRunner.Create()
            .WithName("HealthCheck_Load")
            .WithConcurrency(10)
            .WithDuration(TimeSpan.FromSeconds(5))
            .WithInterval(TimeSpan.FromMilliseconds(200))
            .RunAsync(async () =>
            {
                var response = await _httpClient.GetAsync("https://api.example.com/health");
                response.EnsureSuccessStatusCode();
            });

        Assert.True(result.Success >= result.Total * 0.95);
    }
}

Sample Output

Load test 'HealthCheck_Load' completed:
  Total executions: 50
  Successful executions: 48
  Failed executions: 2
  Execution time: 5.12 seconds
  Requests per second: 9.77
  Average latency: 102.34ms
  Success rate: 96.00%

Core Concepts

How Interval Works

Every Interval, the framework launches Concurrency concurrent operations. For example:

• Concurrency: 5, Duration: 3s, Interval: 500ms = 6 batches × 5 operations = ~30 total operations

Advanced Configuration

Using LoadExecutionPlan Directly

For full control, use LoadExecutionPlan with LoadRunner.Run():

using LoadSurge.Models;
using LoadSurge.Runner;

[Fact]
public async Task Advanced_Load_Test()
{
    var plan = new LoadExecutionPlan
    {
        Name = "Database_Connection_Pool",
        Settings = new LoadSettings
        {
            Concurrency = 20,
            Duration = TimeSpan.FromSeconds(30),
            Interval = TimeSpan.FromMilliseconds(100),
            TerminationMode = TerminationMode.CompleteCurrentInterval,
            GracefulStopTimeout = TimeSpan.FromSeconds(10)
        },
        Action = async () =>
        {
            using var conn = new SqlConnection(connectionString);
            await conn.OpenAsync();
            return true;
        }
    };

    var result = await LoadRunner.Run(plan);

    Assert.True(result.Success >= result.Total * 0.99);
}

Termination Modes

MaxIterations (Fluent API)

Stop after a fixed number of operations regardless of duration:

var result = await LoadTestRunner.Create()
    .WithConcurrency(10)
    .WithDuration(TimeSpan.FromMinutes(5))
    .WithMaxIterations(1000) // Stop after 1000 operations
    .RunAsync(async () => { /* ... */ });

Assertions / CI Gating

Use LoadResult fields to fail tests based on performance criteria:

var result = await LoadTestRunner.Create()
    .WithConcurrency(10)
    .WithDuration(TimeSpan.FromSeconds(10))
    .RunAsync(async () => { /* ... */ });

// Success rate gate
var successRate = (double)result.Success / result.Total;
Assert.True(successRate >= 0.99, $"Success rate {successRate:P} below 99%");

// Throughput gate
Assert.True(result.RequestsPerSecond >= 50, $"RPS {result.RequestsPerSecond} below 50");

// Latency gate
Assert.True(result.Percentile95Latency < 500, $"P95 latency {result.Percentile95Latency}ms exceeds 500ms");
Assert.True(result.AverageLatency < 200, $"Avg latency {result.AverageLatency}ms exceeds 200ms");

Available Result Fields

• Total, Success, Failure — counts
• Time — execution time in seconds
• RequestsPerSecond — throughput
• AverageLatency, MinLatency, MaxLatency — in milliseconds
• MedianLatency, Percentile95Latency, Percentile99Latency — percentiles in ms
• PeakMemoryUsage — bytes

Safety & Gotchas

• Thread-safety: Your action runs concurrently. Avoid shared mutable state unless protected.
• Reuse HttpClient: Create a single static readonly HttpClient — don't instantiate per request.
• Start low: Begin with low concurrency and short duration. Increase gradually.
• Timeouts: Add your own timeout in the action. The framework won't kill hung operations:

  using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
  await httpClient.GetAsync(url, cts.Token);
  

• Cancellation: The framework uses GracefulStopTimeout to wait for in-flight requests. Long-running actions without cancellation support may delay test completion.
• CI filtering: Use dotnet test --filter "FullyQualifiedName~LoadTests" to run only load tests or exclude them from fast CI runs.

When to Choose This

Use this framework when:

• You want load tests as part of dotnet test without extra tooling
• You need quick concurrency smoke tests in CI
• Your tests are integration-style (HTTP calls, database queries)
• You want xUnit v3 native attributes and test discovery

Use a dedicated tool (k6, Locust, NBomber) when:

• You need distributed load from multiple machines
• You need protocol-specific features (HTTP/2 multiplexing, WebSocket)
• You need real-time dashboards and detailed analytics
• You're testing at scale (thousands of concurrent users)

Fun Explanation (optional)

Think of this like a playground stress test. You set:

• How many kids play at once (Concurrency)
• How long the playground is open (Duration)
• How often new groups arrive (Interval)

The framework tells you how many kids had fun (success), how many fell off the swings (failure), and how fast the line moved (RPS).

Requirements

• .NET 8.0+
• xUnit v3

Contributing

PRs welcome. Open an issue for bugs or feature requests.

Made by Vasyl