Skip to main content

strobengine

A high-performance HTTP, WebSocket, and gRPC 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
tonic 0.14 gRPC framework with TLS support
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.

Docker

Alternatively, pull and run strobengine directly from Docker Hub:

docker pull strobeops/strobengine:latest
docker run --rm -it strobeops/strobengine load http://host.docker.internal:8080/api/health -c 50 -d 30

See docs/docker.md for full Docker documentation including version tags, host networking, and building locally.

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)

# 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,
    headers=[("Authorization", "Bearer token123")],
)
summary = engine.run()

print_summary(summary)

# 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,
    headers=[("X-Custom", "value")],
)
summary = engine.run()

print_summary(summary)

# 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()

# gRPC unary call
engine = StrobEngine(
    url="grpc://localhost:50051",
    concurrency=10,
    duration=30,
    options=RequestOptions(
        grpc_service="helloworld.Greeter",
        grpc_method="SayHello",
        grpc_payload="CgR0ZXN0",
    ),
)
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"

# Multiple headers (repeatable -H flag)
strobengine load http://localhost:8080/api/data \
  --method POST --body '{"key": "val"}' \
  --header "Authorization: Bearer token" \
  --header "X-Request-ID: abc-123"

# POST with URL-encoded form data
strobengine load http://localhost:8080/api/data \
  --method POST --form "key1=value1&key2=value2"

# 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

# gRPC unary call
strobengine load grpc://localhost:50051 \
  --grpc-service helloworld.Greeter \
  --grpc-method SayHello \
  --grpc-payload CgR0ZXN0 \
  -c 10 -d 30

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 (min, avg, p50, p90, p95, p99, max).

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)
--form none Form data body (e.g. key1=val1&key2=val2)
--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
--ws-mode handshake WebSocket mode: handshake, ping_pong, stream
--ws-payload none WebSocket text payload for stream mode
--ws-role none WebSocket Pub/Sub role: publisher, subscriber
--ws-publish-interval none Publisher send interval in milliseconds
--ws-subscribers none Number of subscriber workers
--grpc-service none gRPC service name (e.g. helloworld.Greeter)
--grpc-method none gRPC method name (e.g. SayHello)
--grpc-payload none Base64-encoded protobuf payload
--grpc-deadline-ms none gRPC deadline in milliseconds
--http3/--no-http3 off Enable HTTP/3 over QUIC
--quic-zero-rtt off Enable QUIC 0-RTT connection testing
--quic-max-idle-timeout none QUIC max idle timeout in ms

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)
--form none Form data body (e.g. key1=val1&key2=val2)
--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
--ws-mode handshake WebSocket mode: handshake, ping_pong, stream
--ws-payload none WebSocket text payload for stream mode
--ws-role none WebSocket Pub/Sub role: publisher, subscriber
--ws-publish-interval none Publisher send interval in milliseconds
--ws-subscribers none Number of subscriber workers
--grpc-service none gRPC service name (e.g. helloworld.Greeter)
--grpc-method none gRPC method name (e.g. SayHello)
--grpc-payload none Base64-encoded protobuf payload
--grpc-deadline-ms none gRPC deadline in milliseconds
--http3/--no-http3 off Enable HTTP/3 over QUIC
--quic-zero-rtt off Enable QUIC 0-RTT connection testing
--quic-max-idle-timeout none QUIC max idle timeout in ms

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)
--form none Form data body (e.g. key1=val1&key2=val2)
--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
--ws-mode handshake WebSocket mode: handshake, ping_pong, stream
--ws-payload none WebSocket text payload for stream mode
--ws-role none WebSocket Pub/Sub role: publisher, subscriber
--ws-publish-interval none Publisher send interval in milliseconds
--ws-subscribers none Number of subscriber workers
--grpc-service none gRPC service name (e.g. helloworld.Greeter)
--grpc-method none gRPC method name (e.g. SayHello)
--grpc-payload none Base64-encoded protobuf payload
--grpc-deadline-ms none gRPC deadline in milliseconds
--http3/--no-http3 off Enable HTTP/3 over QUIC
--quic-zero-rtt off Enable QUIC 0-RTT connection testing
--quic-max-idle-timeout none QUIC max idle timeout in ms

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 min, average, p50, p90, p95, p99, and max 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

See docs/testing.md for the full testing guide, including e2e tests, CI/CD checks, and running individual test suites.

Documentation

See docs/table_of_contents.md for the full documentation index including HTTP methods, WebSocket support, Docker, testing, and architecture guides.

How to Contribute

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/my-feature)
  3. Install dependencies and set up pre-push Git hooks:
    uv sync
    uv run pre-commit install --hook-type pre-push
    
  4. Run formatting, linting, and tests manually (or let git push run them automatically):
    make check
    
  5. Commit your changes following Conventional Commits
  6. Push to your branch and open a Pull Request

Development

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Metadata

Release files for strobengine 0.4.0

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.4.0
File Size Uploaded Provenance Actions
strobengine-0.4.0.tar.gz 159.8 kB With provenance Details for strobengine-0.4.0.tar.gz

Built distributions (wheels)

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

Total release size: 23.0 MB

Release files / strobengine-0.4.0.tar.gz

Download URL strobengine-0.4.0.tar.gz
Size 159.8 kB
Tags Source
SHA-256 checksum
How to use checksums
82b8b793d26e110ae1e7e3e7fc0ee239c0bab7b13f2be8e8eab3d9ecd51a3356
BLAKE2b-256 checksum
How to use checksums
dc109edc8cef7c6a93831ce77a6a805bead026558a6b73676409b1ba0c4ed519
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 23, 2026.

Transparency log

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

Download URL strobengine-0.4.0-cp311-abi3-win_amd64.whl
Size 5.2 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
bacceb2f8d7d73dc982372751eacb2e5b2d1d976771d64f6d5dcb87a0eff4459
BLAKE2b-256 checksum
How to use checksums
f7b305ccb47407aeda735eabb62b55a0e843ed7619fa120eb882e58972eec180
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 23, 2026.

Transparency log

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

Download URL strobengine-0.4.0-cp311-abi3-manylinux_2_38_x86_64.whl
Size 6.2 MB
Tags CPython 3.11 Linux glibc 2.38+ x86-64 abi3
SHA-256 checksum
How to use checksums
ed7001924d7fc709bd2fedf815733b054e75aea64f800560c0901ed44d19b9d5
BLAKE2b-256 checksum
How to use checksums
69c1ecb021ba39693cee7ec0c2dfc2db68ae0788df07fb9c8a905e1bd860abd9
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 23, 2026.

Transparency log

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

Download URL strobengine-0.4.0-cp311-abi3-macosx_11_0_arm64.whl
Size 5.6 MB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ae3324daefd6cf1e1823bd8c15bf8854b3682d77e22c86c869fb83c930a31953
BLAKE2b-256 checksum
How to use checksums
bd8b998429ebdbe1d6d9f5cee3943ee42a66c17f569218e3af39ac3025f55177
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 23, 2026.

Transparency log

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

Download URL strobengine-0.4.0-cp311-abi3-macosx_10_12_x86_64.whl
Size 5.8 MB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
01e8b016f4b38054b6d1bb5d6100f9b5a5a01ce81818bc8e3096aa408f2eb292
BLAKE2b-256 checksum
How to use checksums
b12d5a665f1a999e2020b04ab727adb3c9516e489fbdb4b713826c60b9ba4021
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 23, 2026.

Transparency log

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

Select from 5 files

Attestation for strobengine-0.4.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 23, 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