strobengine
A high-performance HTTP load testing engine with a Python API and a bare-metal Rust core.
Dependencies
- Python >= 3.11
- Rust (stable, with
cargo) - uv (Python package manager)
Rust crates
| Crate | Version | Purpose |
|---|---|---|
| pyo3 | 0.29 | Python FFI bindings (stable ABI, abi3-py311) |
| reqwest | 0.13 | HTTP client with connection pooling |
| tokio | 1.53 | Multi-threaded async runtime |
| tokio-util | 0.7 | CancellationToken for graceful worker shutdown |
| tracing | 0.1 | Structured logging instrumentation |
| tracing-subscriber | 0.3 | Log formatting and output (stderr/file) |
| indicatif | 0.17 | Terminal progress bar rendering |
| fastrand | 2 | Fast random number generation for chaos injection |
| http | 1 | HTTP method types and header primitives |
| bytes | 1 | Zero-copy byte buffer for request payloads |
Installation & Compilation
# Clone the repository
git clone https://github.com/riccione/strobengine.git
cd strobengine
# Build the native extension and install the package
uv sync
uv sync invokes maturin under the hood, which compiles the Rust code into a native Python extension module and installs it into your virtual environment.
Quick Start Usage
from strobengine import StrobEngine
from strobengine.reporter import print_summary
# Constant load test
engine = StrobEngine(url="http://localhost:8080/api/health", concurrency=50, duration=30)
summary = engine.run()
print_summary(summary, url=engine._url, duration_secs=30)
# Ramp/stress test (10 -> 200 workers over 60s, hold 30s)
engine = StrobEngine.stress_test(
"http://localhost:8080/api/health",
start_concurrency=10, max_concurrency=200,
ramp_duration=60, hold_duration=30,
)
summary = engine.run()
print_summary(summary, url=engine._url, duration_secs=30)
# Spike test (baseline 5 -> peak 500 -> back to 5)
engine = StrobEngine.spike_test(
"http://localhost:8080/api/health",
baseline=5, peak_concurrency=500,
pre_spike_duration=5, spike_duration=10, post_spike_duration=5,
)
summary = engine.run()
print_summary(summary, url=engine._url, duration_secs=30)
# POST request with JSON body and custom headers
engine = StrobEngine(
url="http://localhost:8080/api/data",
method="POST",
body='{"name": "test", "value": 42}',
headers=[("Authorization", "Bearer token123")],
)
summary = engine.run()
For async contexts (FastAPI, Typer, etc.):
summary = await engine.run_async()
CLI Usage
# Constant load test (default subcommand)
strobengine http://localhost:8080/api/health -c 50 -d 30
# Ramp/stress test
strobengine stress http://localhost:8080/api/health --from 10 --to 500 --ramp 60 --hold 30
# Spike test
strobengine spike http://localhost:8080/api/health --baseline 5 --peak 1000 --pre-spike 5 --spike-duration 10 --post-spike 5
# JSON output for CI/CD
strobengine load http://localhost:8080/api/health --json
# Chaos/fault injection test (~10% of requests get faults)
strobengine load http://localhost:8080/api/health --chaos
# POST with JSON body
strobengine load http://localhost:8080/api/data --method POST --body '{"key": "val"}'
# PUT with custom headers
strobengine load http://localhost:8080/api/resource/1 \
--method PUT --body '{"name": "updated"}' --header "Authorization: Bearer token"
# DELETE
strobengine load http://localhost:8080/api/resource/1 --method DELETE
# Verbose debug output
strobengine load http://localhost:8080/api/health -vv
# Quiet mode (suppress logs, keep progress bar)
strobengine load http://localhost:8080/api/health -q
By default, this spawns 10 concurrent workers for 10 seconds with a 10-second request timeout. Results are displayed as a formatted table with total requests, errors, requests/sec, and latency percentiles (avg, p95, p99).
Subcommands
| Subcommand | Description |
|---|---|
load |
Constant load test (default if no subcommand given) |
stress |
Ramp from starting to target concurrency, then hold |
spike |
Baseline -> peak -> baseline |
Load Subcommand Options
| Flag | Default | Description |
|---|---|---|
-c, --concurrency |
10 |
Number of concurrent workers |
-d, --duration |
10 |
Duration in seconds |
-t, --timeout |
10 |
Per-request timeout in seconds |
--method |
GET |
HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) |
--body |
none | Request body (raw string) |
--header |
none | Custom header key:value (repeatable) |
--chaos |
off | Enable fault injection (~10% of requests) |
--no-progress |
off | Suppress live progress bar |
-v, -vv, -vvv |
warn | Increase verbosity (INFO, DEBUG, TRACE) |
-q, --quiet |
off | Suppress all output |
--log-file <path> |
none | Write logs to file |
--json |
off | Output raw JSON instead of formatted table |
Stress Subcommand Options
| Flag | Default | Description |
|---|---|---|
--from |
10 |
Starting concurrency |
--to |
200 |
Target concurrency |
--ramp |
60 |
Ramp duration in seconds |
--hold |
30 |
Hold duration at target concurrency |
-t, --timeout |
10 |
Per-request timeout in seconds |
--method |
GET |
HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) |
--body |
none | Request body (raw string) |
--header |
none | Custom header key:value (repeatable) |
--chaos |
off | Enable fault injection (~10% of requests) |
--no-progress |
off | Suppress live progress bar |
-v, -vv, -vvv |
warn | Increase verbosity (INFO, DEBUG, TRACE) |
-q, --quiet |
off | Suppress all output |
--log-file <path> |
none | Write logs to file |
--json |
off | Output raw JSON |
Spike Subcommand Options
| Flag | Default | Description |
|---|---|---|
--baseline |
5 |
Baseline concurrency |
--peak |
500 |
Peak concurrency |
--pre-spike |
5 |
Pre-spike duration in seconds |
--spike-duration |
10 |
Spike duration in seconds |
--post-spike |
5 |
Post-spike duration in seconds |
-t, --timeout |
10 |
Per-request timeout in seconds |
--method |
GET |
HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) |
--body |
none | Request body (raw string) |
--header |
none | Custom header key:value (repeatable) |
--chaos |
off | Enable fault injection (~10% of requests) |
--no-progress |
off | Suppress live progress bar |
-v, -vv, -vvv |
warn | Increase verbosity (INFO, DEBUG, TRACE) |
-q, --quiet |
off | Suppress all output |
--log-file <path> |
none | Write logs to file |
--json |
off | Output raw JSON |
Global Options
| Flag | Description |
|---|---|
-V, --version |
Show version and exit |
HTTP Methods, Bodies & Headers: See docs/http_methods.md for detailed documentation on supported HTTP methods, request body handling, custom headers, and performance characteristics.
Live Progress Bar
During test execution, a live progress bar displays on stderr with real-time telemetry:
⠋ [00:00:05] [==============>-------------] 40% | 1250 req/s | 20 VUs | 12 err | avg 4.2ms
- RPS: Instantaneous requests per second (sampled every 200ms)
- VUs: Active virtual users / concurrent workers
- Errors: Total error count
- Avg latency: Running average across all completed requests
The progress bar auto-detects non-TTY environments (CI/CD, piped output) and suppresses itself. Use --no-progress to explicitly disable it on interactive terminals.
Verbosity Levels
| Flag | Level | Shows |
|---|---|---|
| (default) | warn |
Errors and warnings only |
-v |
info |
Engine start/stop, test configuration |
-vv |
debug |
Worker spawn, HTTP errors, connection events |
-vvv |
trace |
Per-request latency, status codes, chaos injection |
-q |
off | Suppress all log output (progress bar remains) |
Logs stream to stderr by default, keeping stdout clean for JSON output piping:
strobengine load http://localhost:8080/api/health -vv --json > results.json
Architecture
strobengine separates configuration, execution, and metrics into clean Rust modules, exposed to Python via PyO3:
config--TestConfigfor static load,LoadProfileenum for dynamic profiles (Constant, Ramp, Spike) with target concurrency interpolation.worker-- Async worker loops with method-aware request building, static payload reuse (Bytes), and zero-allocation header management viaClientBuilder::default_headers().metrics-- Lock-free atomic counters (AtomicUsize) track total requests and errors without contention. An aggregator task collects raw latencies, thencalculate_summarycomputes average, p95, and p99 percentiles in Rust at bare-metal speed.chaos-- Protocol-agnostic fault injection engine withChaosEngineevaluator andChaosFaultenum (LatencySpike, CorruptedPayload, MetadataCorruption, ConnectionDrop).progress-- Background Tokio render task sampling atomic metrics every 200ms, displaying live RPS, active VUs, and latency via indicatif.- Orchestrator -- Supervisor task ticks every 200ms, calculates target concurrency from the active profile curve, spawns/aborts workers dynamically.
The Python GIL is released entirely via py.detach() during test execution, allowing the full Tokio thread pool to run concurrently without throttling Python.
Testing
Run the full test suite with:
# Rust unit tests
cargo test
# Python unit tests
uv run pytest -v
How to Contribute
- Fork the repository
- Create a feature branch (
git checkout -b feat/my-feature) - Make your changes
- Run formatting, linting, and tests:
cargo fmt cargo clippy --all-targets -- -D warnings cargo test uv run pytest -v
- Commit your changes following Conventional Commits
- Push to your branch and open a Pull Request
License
This project is licensed under the Apache License, Version 2.0. See LICENSE for the full text.
Metadata
Release files for strobengine 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| strobengine-0.2.0.tar.gz | 62.7 kB | With provenance | Details for strobengine-0.2.0.tar.gz |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| strobengine-0.2.0-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for strobengine-0.2.0-cp311-abi3-win_amd64.whl |
| strobengine-0.2.0-cp311-abi3-manylinux_2_38_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.38+ x86-64 | Details for strobengine-0.2.0-cp311-abi3-manylinux_2_38_x86_64.whl |
| strobengine-0.2.0-cp311-abi3-macosx_11_0_arm64.whl | CPython 3.11 | abi3 | macOS 11.0+ ARM64 | Details for strobengine-0.2.0-cp311-abi3-macosx_11_0_arm64.whl |
Total release size: 10.0 MB
Release files / strobengine-0.2.0.tar.gz
| Download URL | strobengine-0.2.0.tar.gz |
|---|---|
| Size | 62.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93f1bea8870f88862604c50fa75f1eb473796062737beeaf3cc3d1466f6d3ccf
|
|
BLAKE2b-256 checksum How to use checksums |
1f8af3ba055d1acaf66fa5b0b003fee2286f10cffe24dce8c88d70626ae5e87f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency logRelease files / strobengine-0.2.0-cp311-abi3-win_amd64.whl
| Download URL | strobengine-0.2.0-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
56dedef26d6d17f7533b22562bfa60c2b20ac130f0b771fa8628833698cb081b
|
|
BLAKE2b-256 checksum How to use checksums |
336f3df7cc8ab8e2d3abb0f90089815a37c9aa6a7f2da33ef603a9c6a68c3fe9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency logRelease files / strobengine-0.2.0-cp311-abi3-manylinux_2_38_x86_64.whl
| Download URL | strobengine-0.2.0-cp311-abi3-manylinux_2_38_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.11 Linux glibc 2.38+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
1fccf6708a51296a575593da875a7e1a67adb1c068e8448864e488a6e81231bf
|
|
BLAKE2b-256 checksum How to use checksums |
b3591111ce4114a921b9c6d292bb0bf2c2142abff694c67b68c9cfe842c84dd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency logRelease files / strobengine-0.2.0-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | strobengine-0.2.0-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
dc5d12afd3ffd695def5c9532829bbe19320535f8e50c83d83391ba225fa1b7c
|
|
BLAKE2b-256 checksum How to use checksums |
93d03ac8bcc2b48c9f71b5d7ce0e94b0ca9e16e9cb9b862f6b7e64490e757a7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency logSecurity for strobengine 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 4 files in this release have been uploaded with provenance metadata.
Attestation for strobengine-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.