jac-loadtest-cli
HAR-based load testing CLI built on Jac. Capture real browser traffic via Chrome DevTools, export it as a .har file, and replay it under load — no scripting required.
The tool installs as a console script into your project's jac venv, so after installation you run it with jac x loadtest alongside any other tool in jac x --list.
Compatibility: Works with any HTTP server — jac-scale, Django, FastAPI, Node.js, etc. The only jac-scale-specific feature is auth: if your app uses jac-scale's
/user/loginJWT flow, credentials are automatically handled. For other auth schemes the raw request from the HAR is replayed as-is.
Varied test data: inline
{{uuid}},{{vu_id}},{{account.<col>}}tokens anywhere in a recorded payload, or--param "AddTodo.body.title=titles.csv"to feed a field from a list of real values — so VUs stop colliding on unique fields and stop sharing one warm cache entry. See docs/COMMANDS.md § Varying the data.
Per-VU accounts:
--accounts '{"alice":"pw1","bob":"pw2"}'gives every VU its own identity and its own token, so N VUs exercise N root graphs instead of contending on one. Accounts that do not exist yet are registered automatically. See docs/COMMANDS.md § Accounts.
Correlation: a HAR carries the recording user's server-generated IDs, so replaying it raw makes every create → update → delete workflow fail its ownership check. The recorded file is scanned at startup for values a response hands to a later request, and each VU threads the IDs it was given — no flags, no scripting. See docs/COMMANDS.md § Correlation.
Protocols: HTTP/HTTPS, plus WebSocket and GraphQL (query/mutation over HTTP, subscriptions over
graphql-ws) — all auto-detected from the HAR with no extra flags. See docs/COMMANDS.md § Protocol Support.
Testing Modes
Monolith mode (default) — all requests go through a single --url. Use this for production-realistic load testing: it measures what users actually experience end-to-end through the gateway.
Microservice mode — route requests directly to individual service processes by URL path prefix. Use this locally or inside your cluster to isolate per-service latency and identify which service is the bottleneck — without gateway overhead masking the signal.
# Monolith: all traffic through the gateway
jac x loadtest recording.har --url http://localhost:8000 --vus 10 --iterations 20
# Microservice: bypass gateway, route by path prefix to individual services
jac x loadtest recording.har --mode microservice \
--url http://localhost:8000 \
--services-map '{"order_service":"http://localhost:18001","inventory_service":"http://localhost:18002"}' \
--vus 10 --iterations 20
Note: Microservice mode requires direct network access to service ports. This means it's only usable locally (
jac serve) or from inside a Kubernetes cluster — not from outside production. For remote or production load testing, use monolith mode.
Quick Start
# Minimal: 1 VU, 1 HAR replay
jac x loadtest recording.har --url http://localhost:8000
# 50 VUs, each replaying the HAR 100 times, with 10s ramp-up
jac x loadtest recording.har --url http://localhost:8000 \
--vus 50 --iterations 100 --ramp-up 10s
# Realistic pacing: replay at recorded think times, halved
jac x loadtest recording.har --url http://localhost:8000 \
--vus 10 --iterations 30 --think-time scaled --think-time-scale 0.5
# Rate-limited stress test: cap global throughput to 50 req/s
jac x loadtest recording.har --url http://localhost:8000 \
--vus 10 --iterations 50 --rps 50
# CI gate: fail if p95 > 500ms or error rate > 1%, stop early on first breach
jac x loadtest recording.har --url http://staging:8000 \
--vus 20 --iterations 100 \
--fail-on-p95 500 --fail-on-error-rate 1 \
--threshold-start-delay 10s --abort-on-fail
# Per-request debug output
jac x loadtest recording.har --url http://localhost:8000 --vus 2 --iterations 5 --debug
Exit Codes
| Code | Meaning |
|---|---|
0 |
Test completed; all thresholds passed (or none configured) |
1 |
At least one threshold failed (--fail-on-error-rate, --fail-on-p95, --fail-on-p99) |
2 |
Config or tool error (missing flag, bad HAR file, auth failure) |
Failed thresholds are printed to stderr before exit:
THRESHOLD FAILED: error_rate 3.2% > limit 1.0%
THRESHOLD FAILED: p95 612.4ms > limit 500.0ms
Key Flags
| Flag | Default | Description |
|---|---|---|
--vus |
1 |
Concurrent virtual users (asyncio coroutines per worker) |
--iterations |
1 |
Stop each VU after N full HAR replays |
--ramp-up |
0s |
Stagger VU startup — prevents thundering herd at test start |
--workers |
CPU count | Worker processes; each runs its own event loop (capped at --vus and CPU count) |
--rps |
0 (unlimited) |
Global requests-per-second cap across all VUs |
--timeout |
30s |
Per-request timeout; exceeded requests are recorded as TIMEOUT errors |
--think-time |
none |
none / real / scaled — inter-request delay from HAR timings |
--think-time-scale |
1.0 |
Multiplier on think times (0.5 = half speed, 2.0 = double) |
--fail-on-error-rate |
— | Fail (exit 1) if global error rate exceeds N% |
--fail-on-p95 |
— | Fail (exit 1) if global p95 latency exceeds N ms |
--fail-on-p99 |
— | Fail (exit 1) if global p99 latency exceeds N ms |
--threshold-start-delay |
0s |
Ignore threshold checks for this long after the test starts |
--abort-on-fail |
false |
Stop the test immediately when a threshold is first breached |
--debug |
false |
Print one line per request to stderr: VU ID, endpoint, status, latency |
--report-format |
console |
console / json / html |
--report-out |
— | Write report to file (required for --report-format html) |
See docs/COMMANDS.md for the full flag reference including microservice mode, auth, and jac.toml configuration.
Authentication
The tool auto-detects the login request in the HAR by matching --login-path (default /user/login). At test start each VU logs in once and injects the returned JWT into all subsequent requests.
# All VUs log in with the same account used during HAR recording
jac x loadtest recording.har --url http://localhost:8000 \
--username admin@example.com --password secret
Developer Setup
# 1. Navigate to the CLI directory
cd jac_loadtest_cli
# 2. Install the package in editable mode (also installs runtime deps)
jac install -e .
# 3. Verify the command is registered
jac x loadtest --help
Running tests
cd jac_loadtest_cli
jac test tests/ # all 387 tests
jac test tests/unit/ # unit tests only
jac test tests/integration/ # integration tests (needs aiohttp servers)
Mock service for local testing
The scripts/mock_service.jac script spins up lightweight HTTP servers to test against without a real backend:
# Start two fake services on ports 8001 and 8002
jac run scripts/mock_service.jac -- order_service:8001 inventory_service:8002
Project Layout
jac_loadtest_cli/ ← sub-project root
├── scripts/
│ └── mock_service.jac ← lightweight fake HTTP servers for local testing
└── jac_loadtest_cli/ ← Python package (importable as jac_loadtest_cli)
├── plugin.jac ← argparse CLI entry point, exposed as the `loadtest` console script
├── cli.jac ← argument wiring, run orchestration, exit codes
├── config.jac ← LoadTestConfig + three-layer config resolution
├── headless.jac ← run_test_headless() — CLI-free entry point for web/embedder use
├── core/
│ ├── har_parser.jac ← parse HAR 1.2, filter, URL rewrite, protocol tagging
│ ├── engine.jac ← asyncio VU coroutines, RPS cap, threshold watcher (HTTP)
│ ├── correlation.jac ← per-VU response correlation; detects rules from the HAR
│ ├── parameterize.jac ← {{...}} tokens and --param data substitution
│ ├── ws_engine.jac ← WebSocket VU coroutine, HAR auto-detection bridge
│ ├── graphql_engine.jac ← GraphQL subscription (graphql-ws) VU coroutine
│ ├── protocols.jac ← run_all_protocols() — HTTP entries and ws/graphql
│ │ scenarios concurrently, one MetricsCollector
│ ├── metrics.jac ← RequestResult, MetricsCollector, p50/p95/p99, latency histogram
│ └── process_runner.jac ← multi-process worker orchestration, controller-side
│ --abort-on-fail decision and metric merging
├── bridge/
│ ├── auth.jac ← login detection, JWT injection, credential rotation
│ └── topology.jac ← TopologyRouter, longest-prefix matching
└── output/
└── reporter.jac ← Rich console, JSON, HTML reporters
HAR Compatibility
Tested with HAR 1.1 and 1.2 (the format exported by Chrome DevTools, Firefox, Postman, and Insomnia). Files from other versions are parsed with a warning — open an issue if something breaks.
Documentation
- Architecture — module map, data flow, design decisions
- Commands — full CLI flag reference
- Roadmap — delivery phases for CLI and web UI
- Testing — test strategy and coverage guide
- Upgrading — what changes between releases, and why your numbers may move
Metadata
Release files for jac-loadtest 0.9.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 |
|---|---|---|---|---|
| jac_loadtest-0.9.0.tar.gz | 288.7 kB | Without provenance | Details for jac_loadtest-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jac_loadtest-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for jac_loadtest-0.9.0-py3-none-any.whl |
Total release size: 1.4 MB
Release files / jac_loadtest-0.9.0.tar.gz
| Download URL | jac_loadtest-0.9.0.tar.gz |
|---|---|
| Size | 288.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dd1f654531b3c193fe2095481da8ca05f56df433b7d0d00a15e6f1217fab336c
|
|
BLAKE2b-256 checksum How to use checksums |
589e208d599da504c99fafc2eb09b58edc6c1631e932fc85dbc805ecedad91e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / jac_loadtest-0.9.0-py3-none-any.whl
| Download URL | jac_loadtest-0.9.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac04cf3c96d114f32e230c544e418020ac8d2f8af51cfc8ab730dd7fa07d2892
|
|
BLAKE2b-256 checksum How to use checksums |
4f13bf5cbf6ae17235ca87f713a061a8baa2218a7e860c859ff798f56e2b68a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for jac-loadtest 0.9.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.