The check command and its report

uiscout check is the main command: walk the app, judge every step, write the results.

How it walks#

1. Opens the URL in Chromium (1280×800 viewport, en-US locale, Asia/Ho_Chi_Minh time zone, animations off).
2. On each screen, lists every interactive element a user can see or scroll to (below the fold, in a scrolling panel; not one cut off by a non-scrolling box). While a dialog or menu is open, only the elements inside it. Layout checks judge only what is in view.
3. Acts on each element:
   • buttons, links, tabs, menu items, checkboxes and switches are clicked;
   • text fields get a value that fits them (an email, a number in range, a date: see what gets typed), then Enter;
   • comboboxes and sliders are recorded but not operated yet.
4. After each step: waits until no request is in flight and the DOM has been still for 250 ms, fast-forwards the page clock by 5 s, waits again, then runs the oracles.
5. A step that leads to a new screen queues that screen, up to --depth.

Every screen is explored in a fresh browser context (clean IndexedDB, localStorage and cookies), four screens at a time.

Common flags#

Every flag: CLI reference.

Reading the report#

uiscout: 2 errors, 2 warnings · 11 nodes, 223 edges, 227 steps
Screens with errors: /checkout (2)

Graph diff (vs uiscout/app.graph.json)          ← only with a baseline
  (no change)

Errors (2) · uiscout export <n> writes a Playwright test for one
    1  network      POST /api/orders returned 500
                    at /checkout → click checkout.CheckoutForm.placeOrder
                    in src/features/checkout/CheckoutForm.tsx:48
                    repro open / → click "Cart" → click "Checkout" → type "uiscout@example.com" into "Email" → click "Place order"
    2  script       console.error: Error: MenuGroupContext is missing.
                    at /checkout → click checkout.Header.account · /cart → click … · +5 more
                    repro open / → click "Cart" → click "Checkout" → click "Account"

Warnings (2)
  a11y         button-name: Buttons must have discernible text — #nameless
               at load /broken.html

Changes (3)                                      ← info: new controls since the baseline

Intent coverage 2 of 6 lines                     ← only with *.intent.md files

Healed lookups (8): found by similarity, not exact match
Flaky (1): failed, then passed from a fresh context
Never settled (7): DOM kept changing, judged after the timeout
Not walked: 2 destructive, 1 input, 39 repeat

First lines#

Errors and warnings are counted by message: the same error on seven screens counts once. Then the number of screens, edges and steps walked, and the screens with errors, most first.

While it runs, each screen logs screens done of those found, actions used of the budget, and a rough time left.

Errors and warnings#

Each entry has up to four lines:

• its number (errors only, for uiscout export), the oracle that raised it and its message;
• at: where it happened. load /x means on arriving at /x; /x → click Y means after clicking Y on /x. With several places, the first three and a count;
• in: the source file and line of the control, when the app is built with the identity plugin;
• repro: the shortest path that shows it, in words, to follow by hand. For rule violations, via: the states that broke the rule.

The sections below#

From a finding to a test: uiscout export#

uiscout export                       # the errors of the last run, numbered
uiscout export 1 --to e2e/checkout.spec.ts

The file is a Playwright test that walks the same path (the sign-in and setup steps from the config included, ${VAR} kept as process.env.VAR) and fails on the same kind of problem: an uncaught exception, console.error, or the failing response. For a layout, a11y or rule finding it walks the path and marks where the assertion goes. Run it with npx playwright test; once the bug is fixed it stays as a regression test.

While coding: --watch#

uiscout check --quick --watch

Runs once, then again every time a file under the project changes (node_modules, .git and build output ignored). With a baseline and the plugin, each rerun walks only the screens the changed files build; without one, it reruns everything. The app is started once (webServer) and kept for every rerun.

Exit codes#

Cutting noise#

How long it takes#

Roughly 0.4–2 s per step. Screens run in parallel, but the steps on one screen run one after another, so the total is close to the time of the busiest screen. For reference, on a single-page app with 12 routes and sign-in:

Edit this page on GitHub