All pages
Reference
For agents
This page is also Markdown. llms.txt lists every page, and llms-full.txt holds them all in one file. The skill teaches a coding agent to run ra by itself.
Commands
| Command | What it does |
|---|---|
ra look <state | /path | address> | Looks at one state through its first view, or the views given with --at. Prints the outline, the layout, the findings, and where the pictures are. --in "<selector>" narrows it to part of the page. --then "<code>" runs Playwright code first, with page in scope, and prints what it returns; @file.js reads that code from a file. --full prints the whole outline. |
ra check [state…] | Looks at every state through every view. Each finding is listed once, with the views it shows at. Exits 1 when anything is wrong. |
ra snap [state…] | Keeps how the states look now. |
ra diff [state…] | Says what changed since the snapshot, in words, and writes a copy of each changed picture with the changes framed. |
ra states | Lists the states this project names. |
ra doctor | Shows which browser ra runs, starts it, and tries the closed world in it. |
These options work with every command: --url <origin> uses an app that is already running, or a deployment. --allow <host> lets the page reach that host during this run. --json prints data instead of text. --config <file> and --jobs <n> do what they say.
Exit codes: 0 fine; 1 ra check found something; 2 the command or the config is wrong; 3 the app or the browser could not run. On Ctrl-C, ra closes the browser and stops the app, then exits with 130 (143 for SIGTERM).
Config
app says how to reach the app. It takes one of three forms:
{ command, ready?, env?, timeout? }runs a shell command.{port}in the command is replaced with a free port, which is also set asPORT.{ static: "dist" }serves built files. It understands clean URLs and serves a 404 page if there is one.{ url }points at an app that is already running.
With command, the app runs in its own process group under a small keeper process. The keeper ends the whole group, background jobs included, when ra finishes, when ra is interrupted, and even when ra is killed outright.
views lists what to look through:
- The built-in views are
desktop(1440×900),tablet(820×1180, touch),phone(390×844, touch), andnarrow(320×640, touch). - A size such as
1024x768also works. - Any of these can be followed by
.dark,.light,.touch, or.motion(which leaves animations running). - Custom views are
{ name, width, height, touch?, scale? }. - The default is
["desktop", "phone"].
world says what everything outside the app answers. Set it for the whole project and lay more over it for each state:
-
replies: rules mapped to answers. A rule can be:- a path on the app:
"/api/items" - a method and a path:
"POST /api/items" - a full address:
"https://api.example.com/v1/**" - a host:
"*.example.com"
*matches within one path segment and**matches across segments. The most literal matching rule wins. An answer is{ status?, json?, body?, type?, headers? }, wherebodyis text or bytes, or a function of the request that returns one. ra checks every rule and every fixed answer when it reads the config, and says how to write one it cannot use. An answer that a function returns is checked when it is returned. - a path on the app:
-
block: hosts or addresses to drop quietly, such as analytics. -
allow: outside hosts the page may really reach, such as a font CDN. -
upstreams: stand-in servers for what the app's server calls. Each name gets a loopback address, passed toapp.commandandapp.envas{upstream.NAME}. Point your server's API base URL at it.
ra decides what happens to each request in this order: a reply, then a block, then the app itself, then an allow. Anything else is stopped and reported as an outside finding.
The browser follows a redirect by itself, so routing sees only the first request. A reply cannot answer where a redirect leads: give the reply to the address that redirects. ra stops every hop that leaves the app and its allowed hosts, and reports it. It stops a hop by its host, so a hop goes through to an allowed host even when the allow rule names only some paths there, and to any path on the app, even one under block. The states of one run share a browser, so a host that one state allows is open to the others' redirects too. ra reports each such hop as having gone through, and says why.
states are named entries. Each is a path, or an object with these fields:
url, plus a one-linenote.world, laid over the project's world.storage,session, andcookies: the starting localStorage, sessionStorage, and cookies.clock: the time the page believes it is.ready: a selector that must be visible before the state counts as reached.steps(page, reached): actions that reach the state after the page loads.see: text that must be visible.expect(page, reached): anything else that must hold; throw to fail.status: the response status this state is meant to have, when it is not a success.views: views for this state instead of the project's.accept: findings to accept for this state.scroll: whether ra scrolls through the page, testing each control as it passes the middle of the screen. A state without steps is scrolled unless this isfalse. A state with steps is looked at where its steps leave it unless this istrue.live: true: marks the state as safe to look at on a deployment.javascript: false: looks at the page with its scripts turned off, as a reader without JavaScript or a crawler sees it,<noscript>content included. Every check still runs. It is still a read-only page load, so it does not make a state local, and a run against a deployment may use it withoutlive. With scripts off,sessionis not set, since no script could read it, andseecannot match text inside<noscript>; check that text inexpectwith a CSS locator. The browser refuses the page's scripts and script preloads then, and ra does not report that.
A state with its own world or steps only makes sense on your machine. Against a deployment, ra check --url https://… skips such states unless they are marked live, and ra look refuses them.
Against a deployment, the deployment answers for itself: no reply rule stands in for it, though block still applies to its paths. Outside hosts stay closed unless they are allowed, so a check against a deployment shows exactly what the page depends on. It answers whether the deployment looks right, not whether the services behind it work. Give ra the address the deployment settles on, since only that origin counts as the app: when it redirects to https or to www., the page does not load, and the finding names the address to look at instead.
accept lists findings you have decided to live with: { finding: "contrast", match: "hero", why: "The hero text sits on a photo we test by hand." }. A why is required, and it is printed wherever the finding appears. When every state is checked, ra check names the accept entries that matched nothing, so stale ones get removed.
Other settings: tapTarget (default 24), timeout (default 30000), settle (default 5000), locale (default en-US), and timezone (default UTC). timeout is how long ra waits for a page to load and for its ready mark, and how long a state's steps, its expect, and ra's own checks may take. A part that runs longer is reported, and the run goes on with the next look. A state's steps and the --then code are timed as a whole, so a long flow may need a larger timeout. It takes milliseconds above 0 and up to 2147483647.
The browser
ra runs the Chromium that your project's own playwright-core installed, in headless mode. Before launching, it:
- resolves the executable and follows symlinks
- refuses any path into an installed Google Chrome
- requires the file to sit in Playwright's versioned browser directory
- learns Playwright's default switches for that version without starting a browser, by pointing Playwright at a script that writes down its arguments
It then launches with:
- a single
--disable-featuresswitch holding Playwright's list plusPaintHoldingandMacAppCodeSignClone --mute-audio- the closed world: a proxy that refuses everything, bypassed only for the app on its own port and for the allowed hosts; a host-resolver rule that lets no other name resolve; and WebRTC held to proxied connections, which that proxy refuses
After launch, ra reads Browser.getBrowserCommandLine and refuses to continue unless the running browser has every one of these. Every run ends with a receipt line. ra doctor shows the same receipt and tries the closed world: a throwaway app must answer, while another port on this machine, an IP address, an outside host, and a WebRTC connection must each be stopped.
ra runs on macOS and Linux with playwright-core 1.58 or later. Its browser tests run on 1.58.2, 1.62.1, and 1.65.0.
As a library
defineConfig is all most projects need. Scripts that drive a browser themselves can also use:
-
openBrowser: the launch policy and its receipt -
closeWorld: the closed world's routing, applied to anyBrowserContext. Launch the browser with the switches beneath it, so that what routing never sees is stopped too.reachableHostsreturnsnullwhen a world lets every host through, and then there is nothing to close:TypeScriptconst hosts = reachableHosts(worlds); const owned = await openBrowser({ args: hosts === null ? [] : closedWorldSwitches(origin, hosts) });Like Playwright,
openBrowsercloses the browser on SIGINT, SIGTERM, and SIGHUP, and exits on Ctrl-C. PasshandleSignals: falsewhen your script handles those signals itself. -
ruleProblem: what is wrong with a rule, in words, ornull -
observeandinspectPage: a look. When one browser serves several worlds, passobservethe same hosts asreachable, so that it knows which redirects the browser let through. -
compareLooks: a diff