Getting started

1. 01

   Verify your hostname

   loadtest.dev only sends load to hostnames it has verified. An app on narduk-core serves its verification token at /.well-known/loadtest-dev/<token> once NARDUK_LOAD_SIGNING_KEY is set, and the service checks it before the first run. Private and reserved addresses are always refused.

2. 02

   Add a plan

   Commit Config/load-plan.json to the app repository. New apps from create-narduk-app start with a smoke plan; existing apps get one from narduk-app upgrade.

3. 03

   Run it

   Run narduk-app load run --profile smoke --wait under nvault run, so LOADTEST_API_KEY stays in the process. The CLI resolves the preview hostname from Config/cloudflare-app.json.

4. 04

   Read the verdict

   The command exits 0 when every threshold held, 1 when one broke, 2 when the run was aborted, and 3 for a usage or configuration error, so CI can gate on it directly.

Your first plan

A plan is declarative JSON: scenarios weighted by share of traffic, profiles made of arrival-rate stages, and the thresholds that decide pass or fail. No code runs from it.

{
  "targets": { "preview": "auto" },
  "scenarios": [
    { "id": "home", "weight": 3, "method": "GET", "path": "/" },
    { "id": "health", "weight": 1, "method": "GET", "path": "/api/health", "cache": "bypass" }
  ],
  "profiles": {
    "smoke": { "stages": [{ "duration": "1m", "rate": 5 }] },
    "baseline": { "stages": [{ "duration": "1m", "rate": 50 }, { "duration": "5m", "rate": 50 }] }
  },
  "thresholds": { "p95Ms": 400, "errorRate": 0.01 }
}

What to expect

While a run is live, every second of it is recorded:

• Response time: p50, p95 and p99 latency in milliseconds, from merged histograms.
• Throughput: requests per second actually sent, against the rate the plan asked for.
• Errors by class: 5xx, 4xx, 429, timeout and transport failures, counted separately.
• The build that answered: the x-build-version the target reported, so a result names the release it measured.

Production targets

Previews are the default target. A production run needs --target production and the hostname typed back as confirmation, and the service holds it to a lower peak rate than a preview.