api-stressor
A command-line tool for stress testing HTTP API endpoints. It sends repeated requests at a configurable rate using a JSON payload file, then reports success, failure, and response-time statistics.
Prerequisites
- .NET 10 SDK or later
Running the app
From the repository root:
dotnet run --project src/Stressor.App -- `
--url <endpoint-url> `
--payload <path-to-payload.json> `
--requests <count> `
--interval <duration> `
[--method <http-verb>] `
[--auth <authorization-header-value>] `
[--load <gentle-pacing|fixed-rate|batch>] `
[--batch <count>] `
[--timeout <duration>] `
[--cycles <count>] `
[--cycle-interval <duration>] `
You can also build and run the executable directly:
dotnet build src/Stressor.App ./src/Stressor.App/bin/Debug/net10.0/Stressor.App.exe --url ... --payload ... --requests ... --interval ...
## Getting help
Pass `--help` (or `-h`) to print usage information. This includes all command-line options, examples, supported HTTP methods, interval formats, authentication notes, and exit codes. No other arguments are required.
Pass `--version` to print the application version.
dotnet run --project src/Stressor.App -- --help dotnet run --project src/Stressor.App -- --version
When running the built executable:
./src/Stressor.App/bin/Debug/net10.0/Stressor.App.exe --help
## Command-line options
| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--url` | `-u` | Yes | Full URL of the API endpoint (must start with `http://` or `https://`) |
| `--payload` | `-p` | Yes | Path to a JSON payload file (single body or multi-payload envelope) |
| `--requests` | `-r` | Yes | Number of requests to send per cycle |
| `--interval` | `-i` | Yes | Delay between consecutive request starts (see formats and load modes below) |
| `--method` | `-m` | No | HTTP method to use (default: `POST`) |
| `--auth` | `-a` | No | Authorization header value sent with each request (e.g. `Bearer <token>`) |
| `--load` | `-l` | No | Load handling mode: `gentle-pacing` (default), `fixed-rate`, or `batch` || --timeout | -t | No | Per-request timeout (default: 100s; same formats as --interval) | | --cycles | -c | No | Number of cycles to run (default: 1) | | --cycle-interval | | No | Minimum wait after a cycle completes before the next cycle starts (default: 0s; same formats as --interval) | | --verbose | -v | No | Per-request output mode: failures (detail only on errors) or full (detail on every request) | | --help | -h | No | Show usage information and exit | | --version | | No | Print application version and exit |
Supported HTTP methods
GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
For POST, PUT, and PATCH, the JSON payload file is sent as the request body. For other methods, the payload file is still required and validated, but no body is attached to the request.