Skip to main content

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/login JWT flow, credentials are automatically handled. For other auth schemes the raw request from the HAR is replayed as-is.

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 148 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
    │   ├── engine.jac         ← asyncio VU coroutines, RPS cap, threshold watcher
    │   ├── metrics.jac        ← RequestResult, MetricsCollector, p50/p95/p99
    │   └── process_runner.jac ← multi-process worker orchestration
    ├── 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

Metadata

Release files for jac-loadtest 0.3.5

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

Source distribution (sdist)

Source distribution for jac-loadtest 0.3.5
File Size Uploaded Provenance Actions
jac_loadtest-0.3.5.tar.gz 236.6 kB Without provenance Details for jac_loadtest-0.3.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jac-loadtest 0.3.5
File Interpreter ABI Platform Actions
jac_loadtest-0.3.5-py3-none-any.whl Python 3 none any Details for jac_loadtest-0.3.5-py3-none-any.whl

Total release size: 1.2 MB

Release files / jac_loadtest-0.3.5.tar.gz

Download URL jac_loadtest-0.3.5.tar.gz
Size 236.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c3c59577d866716fa78cf3ce501f056e424a8c2a7fdeb01980734d968199b94e
BLAKE2b-256 checksum
How to use checksums
2f3d095fd3ba731d9ebb65aafe3b3c62ae689c46959d6e531df58164d9fc9c63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / jac_loadtest-0.3.5-py3-none-any.whl

Download URL jac_loadtest-0.3.5-py3-none-any.whl
Size 935.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1eb00a3c384ee3f1848ca6bcc6990ff685100a307c449fb4462b03ee9aedac27
BLAKE2b-256 checksum
How to use checksums
bec635fd9dcc7c0c01872fd57e79fa57ba92d13868f3e3c96e41be9bf37eef01
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for jac-loadtest 0.3.5

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.

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