jac-loadtest

Monorepo containing two projects:

Project	Description
jac_loadtest_cli/	HAR-based load testing CLI — published to PyPI as jac-loadtest-cli
jac_loadtest_web/	Web application built on the CLI engine using jac-client

---

Prerequisites: Install Jac

Both projects run on the Jac toolchain — install the jac binary before doing anything else:

curl -fsSL https://raw.githubusercontent.com/jaseci-labs/jaseci/main/scripts/install.sh | bash

This installs a self-contained native jac binary to ~/.local/bin (no system Python/pip required) and adds it to your PATH. Verify with:

jac -V

Requires Python 3.12+ on your system for the projects' own virtual environments (the jac binary bundles its own runtime and doesn't need this, but jac install still creates a project-local venv).

Version pinning: CI (.github/workflows/test.yml) pins a specific jac release (currently 0.31.1) rather than always installing latest, since jac's own internals (e.g. the jaclang.scale module this project imports) can change between releases. To match CI exactly:

curl -fsSL https://raw.githubusercontent.com/jaseci-labs/jaseci/main/scripts/install.sh | bash -s -- --version 0.31.1

---

jac-loadtest-cli

HAR-based load testing CLI for jac-scale applications. 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.

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 (default, production-realistic)
jac x loadtest recording.har --url http://localhost:8000 --vus 10

# 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

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 iteration
jac x loadtest recording.har --url http://localhost:8000

# 50 VUs with 10s ramp-up, 100 iterations each
jac x loadtest recording.har --url http://localhost:8000 --vus 50 --ramp-up 10s --iterations 100

# CI-friendly with thresholds
jac x loadtest recording.har --url http://localhost:8000 \
  --vus 10 --iterations 50 --fail-on-p95 500 --fail-on-error-rate 1

Developer Setup

# 1. Create and activate a conda env (Python 3.12 required)
conda create -n load python=3.12
conda activate load

# 2. Move into the CLI sub-project
cd jac_loadtest_cli

# 3. Install the package in editable mode (runtime deps only)
jac install -e .

# 4. Verify the command is registered
jac x loadtest --help

# 5. Run the test suite
jac test tests/

Project Layout

jac_loadtest_cli/              ← sub-project root
├── jac.toml                   ← package config and dependencies
├── docs/                      ← CLI documentation
├── scripts/                   ← developer utilities
├── tests/                     ← unit, integration, e2e tests
└── 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 and run orchestration
    ├── config.jac             ← LoadTestConfig dataclass (three-layer resolution)
    ├── core/                  ← HAR parser, load engine, metrics (no jac-scale knowledge)
    ├── bridge/                ← jac-scale-aware adapters (auth, topology)
    └── output/                ← 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 and exit criteria
• Testing — test strategy and coverage guide

---

jac-loadtest-web

Browser-based GUI that wraps the CLI engine using jac-client. See Web Roadmap for the full product plan.