Configuration: uiscout.config.json

uiscout init writes it (Install). uiscout finds the nearest uiscout.config.json from the current directory up to the repository root, and reads the paths in it from the file's own directory. Command-line flags always override the file. Use another file with --config path/to/file.json.

Any string may contain ${NAME}: it's replaced by that environment variable, and a variable that isn't set stops the run (nothing is typed as an empty password).

Full example#

{
  "url": "http://localhost:5173/",
  "webServer": { "command": "pnpm run dev", "timeout": 120 },
  "auth": {
    "steps": [
      { "goto": "/login" },
      { "fill": "Email", "text": "${SCOUT_EMAIL}" },
      { "fill": "Password", "text": "${SCOUT_PASSWORD}" },
      { "click": "Sign in" }
    ],
    "waitFor": "/"
  },
  "depth": 2,
  "maxSteps": 600,
  "concurrency": 4,
  "now": "2026-10-07T09:00:00+07:00",
  "timezone": "Asia/Ho_Chi_Minh",
  "seeds": ["auto", "/legacy", "/no-such-page"],
  "block": ["**/api/ai/**"],
  "allow4xx": ["GET /api/me"],
  "allowOverlap": "[data-event-id]",
  "ignoreConsole": ["Download the React DevTools"],
  "fillText": "uiscout",
  "fastForwardMs": 5000,
  "a11y": true,
  "network": "live",
  "baseline": "uiscout"
}

Keys#

Starting the app: webServer#

"webServer": { "command": "pnpm run dev", "url": "http://localhost:5173/", "timeout": 120, "reuseExisting": true }

The command's output goes to .uiscout/server.log. uiscout stops what it started (the whole process group, so the dev server's children too) however the run ends, Ctrl+C included. check, fuzz, adapters and check --watch all use it; --watch starts it once for every rerun.

Sign-in: auth#

"auth": {
  "steps": [
    { "goto": "/login" },
    { "fill": "Email", "text": "${SCOUT_EMAIL}" },
    { "fill": "Password", "text": "${SCOUT_PASSWORD}" },
    { "click": "Sign in" }
  ],
  "waitFor": "/"
}

The steps (same kinds as setup steps, below) run once, in a fresh browser, before the walk. The cookies and storage they leave are saved, and every screen starts from them. That works for session cookies and tokens in localStorage; it's how apps that reload after signing in get walked without signing in again on every screen.

• waitFor: after the steps, wait until the URL path is this one or below it ("/app" matches /app/home; "/" matches the root only). When it isn't reached, the run stops and says where the sign-in ended up.
• The saved state lives in a private temporary directory (owner only) and is deleted when uiscout exits: never in .uiscout/, which CI uploads.
• A failed step is reported by kind and label (fill "Password"), never with what it typed.
• Each context can have its own auth; the top-level one applies when there are no contexts.
• Use a dedicated test account: everything the walk clicks is done as that user.

Contexts (personas)#

A context has a name, an optional auth (above), and setup steps. The setup steps run after every page load, so they work for apps that keep the session in memory only; for a session cookie, use auth.

With two or more contexts:

• the report prefixes locations with [guest], [member];
• the graph records which contexts saw each screen and edge, and the graph page gets a context filter;
• a setup that fails is reported as a transition error with the failing step's number, and that context isn't walked in a wrong state.

Tip: use dedicated test accounts. The config is plain text.

Seed routes#

Routes no link reaches (the 404 page, an old URL that redirects, a hidden page) that should still be checked:

"seeds": ["auto", "/legacy", "/no-such-page"]

"auto" stands for every static route the app's router declares:

On the command line: --seeds auto,/legacy.

They're entered through the history API from the entry (falling back to a page load). A seed that redirects is kept as a route edge, e.g. /legacy → /pricing, or for a guest /account → /login.

What gets typed#

A field gets a value it accepts, so a validated form lets the walk through:

Values are fixed, not random: the same field gets the same text every run, so graphs and snapshots compare. maxlength is respected.

Edit this page on GitHub