Skip to main content

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 -- TestConfig for static load, LoadProfile enum 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 via ClientBuilder::default_headers().
  • metrics -- Lock-free atomic counters (AtomicUsize) track total requests and errors without contention. An aggregator task collects raw latencies, then calculate_summary computes average, p95, and p99 percentiles in Rust at bare-metal speed.
  • chaos -- Protocol-agnostic fault injection engine with ChaosEngine evaluator and ChaosFault enum (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

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/my-feature)
  3. Make your changes
  4. Run formatting, linting, and tests:
    cargo fmt
    cargo clippy --all-targets -- -D warnings
    cargo test
    uv run pytest -v
    
  5. Commit your changes following Conventional Commits
  6. 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.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for strobengine 0.2.1
File Size Uploaded Provenance Actions
strobengine-0.2.1.tar.gz 64.7 kB With provenance Details for strobengine-0.2.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for strobengine 0.2.1
File Actions
strobengine-0.2.1-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for strobengine-0.2.1-cp311-abi3-win_amd64.whl
strobengine-0.2.1-cp311-abi3-manylinux_2_38_x86_64.whl CPython 3.11 abi3 Linux glibc 2.38+ x86-64 Details for strobengine-0.2.1-cp311-abi3-manylinux_2_38_x86_64.whl
strobengine-0.2.1-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for strobengine-0.2.1-cp311-abi3-macosx_11_0_arm64.whl
strobengine-0.2.1-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for strobengine-0.2.1-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 13.4 MB

Release files / strobengine-0.2.1.tar.gz

Download URL strobengine-0.2.1.tar.gz
Size 64.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f49215522f091dd40389a9fcc0a85641485c0420234cfd25cd874cee44696c7c
BLAKE2b-256 checksum
How to use checksums
f2f2688e40bf58b1346dbb2ddadba3704c04ddcaf66d25bc8537aab801fe6dee
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 3, 2026.

Transparency log

Release files / strobengine-0.2.1-cp311-abi3-win_amd64.whl

Download URL strobengine-0.2.1-cp311-abi3-win_amd64.whl
Size 2.9 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
f307bf65bf7508703a10a006d31adf6f695ff398319b0414db0e6024b3a15dbd
BLAKE2b-256 checksum
How to use checksums
d834f7e0dbbac05461e8ab04342990e6f2a56bd4cdf449f67fefa6f4927690cf
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 3, 2026.

Transparency log

Release files / strobengine-0.2.1-cp311-abi3-manylinux_2_38_x86_64.whl

Download URL strobengine-0.2.1-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
b5dfa7007bcdcf17ed38af2039f8888fe390589021a293975278449f97cf0a68
BLAKE2b-256 checksum
How to use checksums
0bbcdc02a919f02191ccafb054e8e7aa1e0285515719ba778a5e05bffd829d95
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 3, 2026.

Transparency log

Release files / strobengine-0.2.1-cp311-abi3-macosx_11_0_arm64.whl

Download URL strobengine-0.2.1-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
c19565025796bb65beba7a40d0d4b61fb035343c6a558e7a42c260e8a816a91a
BLAKE2b-256 checksum
How to use checksums
8737b9cc40cd36de827721b79485e02471c616f59535ef2b09856ba692cadc5b
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 3, 2026.

Transparency log

Release files / strobengine-0.2.1-cp311-abi3-macosx_10_12_x86_64.whl

Download URL strobengine-0.2.1-cp311-abi3-macosx_10_12_x86_64.whl
Size 3.5 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
13df8984016600be31a9dd0e2cad89419d0b06429b936eace39e6b8aa2636f12
BLAKE2b-256 checksum
How to use checksums
6f8972659f50e19657cb81dd258ed3170a0c25c3c58359f505eafaa02db75156
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 3, 2026.

Transparency log

Security for strobengine 0.2.1

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 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for strobengine-0.2.1.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 3, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page