Skip to content
LiteTraffic

developer preview · 0.1.0.dev0

Users
as an API.

Give a running app a population of stateful synthetic users. Replay what they do on a seeded schedule, then check the business effects they leave behind.

Run a scenarioStar on GitHub
The documented first run of the checkout example

$ litetraffic verify examples/checkout \ --target http://127.0.0.1:8765 --seed 42

pass· 12/12 journeys · 36 requests

seed · drive

interactive preview · examples/checkout

Seed a world, then drive it.

A scenario names its users, the state they start from, the pace they arrive at, and what must hold afterwards. LiteTraffic sets up that state, runs the journeys on a seeded schedule with stock k6, and reads back the result.

run · checkoutseed 42
manifest.jsontrimmed
{
  "name": "checkout",
  "actors": [{"class": "buyer", "count": 8}],
  "fixtures": {"recipe": "owned-shop"},
  "schedule": {
    "unit": "journeys_per_second",
    "phases": [
      {"name": "warmup",   "seconds": 1, "rate": 1},
      {"name": "measure",  "seconds": 5, "rate": 2},
      {"name": "recovery", "seconds": 1, "rate": 1}
    ]
  },
  "assertions": ["one_effect_per_payment",
                 "accepted_orders_persist",
                 "order_totals_match"],
  "budgets": {"max_seconds": 20, "max_requests": 40}
}
  1. Seeding, done
  2. Traffic, done
  3. Observing, done
  4. Verdict, done

run log

  1. preparingFixture owned-shop created for this run
  2. runningk6 v2.2.0 drove 12/12 journeys, 36 requests
  3. observingObserver owned-order-ledger read the final state
  4. finalizing3 of 3 assertions hold. report.html written
verdictPass

This replays the documented first run of examples/checkout against its demo server, with the timing shortened. A real run writes every step to .litetraffic/runs/<run_id>/.

observe · verdict

interactive comparison · checkout --wrong-duplicate

A fast response can still be a failed checkout.

The demo server's faulty mode charges twice when a payment is retried. Every request still succeeds. Switch views to see what each tool reports.

verify · checkoutillustrative timing
one_effect_per_paymentFail
expected1
actual2

2 charges for 1 payment.

{"actual": 2, "expected": 1,
 "logical_key": "<run_id>-traffic-0",
 "sequence": 2}

Each failing sample keeps what the scenario expected and what the app did, so the report points at the retry, not at a log.

examples · deliberate faults

Each included scenario ships with a working demo server and a faulty mode. The same scenario must pass one and fail the other.

  • CheckoutDuplicate charge on retry
  • InventoryOverselling
  • ReportingPartial response or wrong final ledger
  • Cached searchPermanently stale cache
  • Tenant APIData leak or deny-all shortcut

in the 0.1.0.dev0 preview

Everything a run needs, on your machine.

Scenarios are handwritten or generated, and you review them before they run. Every piece below works in the current developer preview.

the cli · nine commands

Built for people, scripts and agents.

Each command prints a short summary, or one JSON object with --json.

litetraffic --help
doctor
Checks k6 is exactly v2.2.0, Python is 3.11 or newer, the output directory is writable, and, with --target, that the app answers.
init
Generates a tenant-isolation scenario from a small JSON config, then validates it.
inspect
Explains a scenario: actors, budgets, fixtures, observations and the resolved schedule. Runs nothing.
approve
Binds the scenario's digest to a target origin, so verify --require-approval refuses a changed scenario.
verify
Runs the scenario and prints the verdict, each assertion, any limitations and the report path.
diff
Compares a baseline and a candidate run, with an optional p95 regression gate.
dashboard
Serves your runs on 127.0.0.1 to filter, read failing samples and compare.
up
Repeats bounded runs as slices until Ctrl+C. Records each slice, gives no overall verdict.
prune
Deletes old run directories by count or age, with an optional --dry-run that deletes nothing.
verify · exit codes
  • 0pass
  • 1fail
  • 2inconclusive
  • 3error
  • 130cancelled

A target that never answers is an error, never a pass. Ctrl+C still saves the evidence collected so far. Exit codes for every command

first run · from the readme

Run the checkout example.

Install k6 v2.2.0 separately, then LiteTraffic from source. The expected result is a pass with 12 journeys and 36 requests. Restart the demo server with --wrong-duplicate to watch it fail.

Where it runs

  • Local development--target http://127.0.0.1:8765
  • CI and preview URLs--target https://…
  • An existing E2B sandbox--e2b-sandbox-id ID --e2b-port PORT

Cloud metadata and link-local addresses are refused before a request is sent, and k6 does not follow redirects.

Not shipped yet

  • AI or automatic scenario authoring
  • Persistent users across runs
  • Managed sandboxes
  • A PyPI release
terminal · first run
$ git clone https://github.com/rohansx/litetraffic.git
$ cd litetraffic
$ python3 -m venv .venv && . .venv/bin/activate
$ python -m pip install -e .
$ litetraffic doctor
$ python examples/checkout/server.py --port 8765 &
$ litetraffic verify examples/checkout \
    --target http://127.0.0.1:8765 --seed 42
$ litetraffic dashboard

verdict: pass · journeys 12/12

developer preview · 0.1.0.dev0

Give the app a world.
Then ask what survived.

Run the included examples today, then write a scenario for your own API. Open source, MIT licensed, no hosted account.

Read the quickstartStar on GitHub