LoadSurge 3.1.0

LoadSurge

High-performance, actor-based load testing framework for .NET.

Installation

dotnet add package LoadSurge

Quick Start

using LoadSurge.Models;
using LoadSurge.Runner;

var plan = new LoadExecutionPlan
{
    Name = "API_Load_Test",
    Settings = new LoadSettings
    {
        Concurrency = 50,
        Duration = TimeSpan.FromSeconds(30),
        Interval = TimeSpan.FromMilliseconds(100)
    },
    Action = async () =>
    {
        var response = await httpClient.GetAsync("https://api.example.com/health");
        return response.IsSuccessStatusCode;
    }
};

var result = await LoadRunner.Run(plan);

Console.WriteLine($"Total: {result.Total}, Success: {result.Success}, Failed: {result.Failure}");
Console.WriteLine($"RPS: {result.RequestsPerSecond:F1}, Avg: {result.AverageLatency:F1}ms, P95: {result.Percentile95Latency:F1}ms");

Examples

Fixed Iteration Count

var plan = new LoadExecutionPlan
{
    Name = "Fixed_100_Requests",
    Settings = new LoadSettings
    {
        Concurrency = 10,
        Duration = TimeSpan.FromMinutes(5),
        Interval = TimeSpan.FromMilliseconds(100),
        MaxIterations = 100  // Stop after exactly 100 requests
    },
    Action = async () => { /* your test */ return true; }
};

Database Testing

var plan = new LoadExecutionPlan
{
    Name = "DB_Pool_Test",
    Settings = new LoadSettings
    {
        Concurrency = 100,
        Duration = TimeSpan.FromMinutes(2),
        Interval = TimeSpan.FromMilliseconds(50)
    },
    Action = async () =>
    {
        using var conn = new SqlConnection(connectionString);
        await conn.OpenAsync();
        using var cmd = conn.CreateCommand();
        cmd.CommandText = "SELECT 1";
        return await cmd.ExecuteScalarAsync() != null;
    }
};

Configuration

Settings

Workload Model

LoadSurge uses an open workload model (constant arrival rate, like NBomber Inject / k6 constant-arrival-rate): iterations are injected on schedule regardless of response times. If the system under test slows down, in-flight requests accumulate — which is exactly what a load test must measure.

var config = new LoadWorkerConfiguration
{
    MaxInFlight = 10_000  // optional safety cap; excess iterations are dropped and counted
};
var result = await LoadRunner.Run(plan, config);

Per-request timeout and cancellation-aware actions:

var plan = new LoadExecutionPlan
{
    Name = "API_Test",
    Settings = new LoadSettings
    {
        // ...
        RequestTimeout = TimeSpan.FromSeconds(5) // hung requests counted as failures
    },
    // Preferred over Action: the token fires on RequestTimeout and run cancellation,
    // so timed-out work is truly aborted instead of leaking in the background.
    ActionWithCancellation = async token =>
    {
        var response = await httpClient.GetAsync(url, token);
        return response.IsSuccessStatusCode;
    }
};

// Cancelling returns partial results collected so far (no exception).
var result = await LoadRunner.Run(plan, config, cancellationToken);

Live progress (long runs are not a black box):

var config = new LoadWorkerConfiguration
{
    Progress = new Progress<LoadProgress>(p =>
        Console.WriteLine($"[{p.ElapsedSeconds:F0}s] started={p.RequestsStarted} ok={p.Success} " +
                          $"fail={p.Failure} inflight={p.InFlight} dropped={p.Dropped} rps={p.RequestsPerSecond:F0}")),
    ProgressInterval = TimeSpan.FromSeconds(1) // default
};

Results

result.Total              // Total completed requests
result.Success            // Successful requests
result.Failure            // Failed requests (incl. timeouts)
result.Dropped            // Iterations dropped by MaxInFlight cap
result.RequestsInFlight   // Still executing when the test ended
result.RequestsPerSecond  // Throughput
result.AverageLatency     // Mean latency (ms)
result.Percentile95Latency // P95 latency (ms)
result.Percentile99Latency // P99 latency (ms)

Samples

Runnable offline examples: dotnet run --project samples/LoadSurge.Samples

Requirements

• .NET Standard 2.0+ (.NET Framework 4.7.2+, .NET 6/8/9+)
• The net8.0 build is Native-AOT-compatible and trimmable
• Zero external dependencies

Related

• xUnitV3LoadFramework - xUnit v3 integration with [Load] attribute

License

MIT