Autonomous Exploration

The fastest way to learn what an app actually does is to click all of it. This skill drives the bundled runner (runner/), which performs a breadth-first exploration of every reachable UI state and produces an evidence report.

Run it

cd runner && npm install                 # first time only
node bin/qa-supreme.mjs here                              # detects the project, starts it, tests it, stops it
node bin/qa-supreme.mjs run --url https://app.example.com # full pipeline against a running app
node bin/qa-supreme.mjs watch --url http://localhost:3000 # real window, slowed down, video recorded

here reads the project in the current directory — Next, Vite, CRA, Nuxt, Astro, Remix, Angular, Django, Rails, Laravel, or a plain static folder — starts it on its own port, waits for it to answer, runs the pipeline and shuts it down. That is what makes this usable on any project without configuring anything first.

The on-screen HUD counts every click as it happens, flashes the element being hit, and shows queue depth and error count — so a human watching, a screenshot, or a recorded video all carry the same proof.

Apps behind a login (most of them)

An unauthenticated run against a protected app explores the login page and reports an empty product. The runner names that instead of pretending: smoke fails with authentication — target is behind a login, and the run stops there rather than producing noise.

# log in once, keep the session
node bin/qa-supreme.mjs login --url https://app.example.com --login-url https://app.example.com/login \
  --user qa@example.com --pass "$QA_PASSWORD"

# every later run reuses it
node bin/qa-supreme.mjs run --url https://app.example.com --storage .qa-supreme/auth.json

The login form is found automatically (username/email + password + submit). When the markup defeats the heuristics, name the fields: --user-selector, --pass-selector, --submit-selector, --success-selector. Success is judged by the login form being gone, not by a URL change — SPAs authenticate without navigating.

While a session is active the crawler also refuses to click anything that ends it (log out, sign out), on top of the destructive-action guard. One stray click on "Sign out" would turn every remaining state into the login page.

What it produces

The button report

Every control gets one verdict, decided from what the click actually caused:

Effects are attributed to a control only when it owns them: errors thrown while a new page loads belong to that page, not to the link that led there. Blaming the link is exactly the false positive this repository exists to hunt, so navigations are judged by what they reached, not by what the destination logged.

What it can see (and what it still cannot)

Before listing controls, the runner puts the page into the state a user would actually find: the consent banner is dismissed (recorded, never counted as a test click), the page is scrolled to the bottom so lazy and virtualised content exists, it waits for the page to stop changing, and hover menus are opened. Then it discovers through the places a naive crawler stops:

Still out of reach, and honest about it: canvas and WebGL surfaces with no DOM behind them, drag-and-drop, cross-origin iframes, native OS dialogs, and anything gated behind a captcha.

Reading only one part of the app

node bin/qa-supreme.mjs crawl --url http://localhost:3000 --only "#settings-panel"

--only <css> limits discovery to one region — a tab panel, a drawer, the screen you just built. Everything else on the page is ignored, so the report is about your change and nothing else. Frames are skipped while a scope is set, because a scope belongs to the host document.

Triaging dead buttons

A dead verdict is not automatically a bug — it may be a no-change tab, an already-active state, or a control whose effect is server-side only. For each one, answer: what should a user expect to happen? If the answer is "something", you found a defect before any user did. Record the confirmed ones as bugs, and add the rest to denySelectors so the next run stays signal.

Safety

By default the crawler refuses to click anything whose label matches a destructive verb (delete, pay, logout, publish, transfer...). That guard is the difference between exploration and an incident.

• Point it at local, preview, or staging environments. Not production.
• Use a seeded, disposable account. Never a real customer's.
• --full-send removes the guard. Only ever on a throwaway environment you can rebuild.
• Add data-qa-skip to any element the crawler must never touch.

Turning exploration into a suite

Exploration is reconnaissance, not regression protection. Feed what it found back into real tests: the discovered journeys become e2e-authoring specs, the dead buttons become bug reports through bug-repro, and the state graph becomes the input to risk-map.