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

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.6
File Size Uploaded Provenance Actions
jac_loadtest-0.3.6.tar.gz 236.6 kB Without provenance Details for jac_loadtest-0.3.6.tar.gz

Built distribution (wheel)

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

Total release size: 1.2 MB

Release files / jac_loadtest-0.3.6.tar.gz

Download URL jac_loadtest-0.3.6.tar.gz
Size 236.6 kB
Tags Source
SHA-256 checksum
How to use checksums
54c1feb5a42e0a0db2f8c37205a4860da9c2946e8fc3eaac88d6a6c8228980a3
BLAKE2b-256 checksum
How to use checksums
9284f208779fe34f41c255fdb9b98602deddaed21076e62cd9a2b6ed45157cb8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

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

Download URL jac_loadtest-0.3.6-py3-none-any.whl
Size 936.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
531dcb6ef96483e7c39be5c724a02035f1cc3831bc4b8d6a0498f3490136e7d8
BLAKE2b-256 checksum
How to use checksums
c997ccac8626a414e4bb861a7f11770b148fb24031f9cd62141fbcbd75e559d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for jac-loadtest 0.3.6

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