Skip to content
LiteTraffic
newLiteTraffic Cloud · early access

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

Read more about how it works

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

Read more about verdicts

demo · rohansx/litetraffic-demo

See it catch a bug.

A pull request adds record sharing and quietly leaks records across tenants. Every request returns 200. LiteTraffic in CI fails the check, the dashboard shows the evidence, and the fix turns it green.

98 seconds, no sound. The full story is in litetraffic-demo pull request #1: the failing run, the fix, and the green run.

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.

Read more about features

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

Read more about commands

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

  • LiteTraffic Cloud (early access)
  • 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

pricing · developer preview

Free to run. Cloud when your team needs it.

The CLI is open source and MIT licensed. LiteTraffic Cloud, for run history across CI builds and links the whole team can open, is in early access.

Join the waitlistSee pricing

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 and MIT licensed. The CLI needs no hosted account.

Read the quickstartStar on GitHub