ra
All pages

Reference

View Markdown
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

CommandWhat 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 statesLists the states this project names.
ra doctorShows 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 as PORT.
  • { 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), and narrow (320×640, touch).
  • A size such as 1024x768 also 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? }, where body is 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.

  • 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 to app.command and app.env as {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-line note.
  • world, laid over the project's world.
  • storage, session, and cookies: 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 is false. A state with steps is looked at where its steps leave it unless this is true.
  • 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 without live. With scripts off, session is not set, since no script could read it, and see cannot match text inside <noscript>; check that text in expect with 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-features switch holding Playwright's list plus PaintHolding and MacAppCodeSignClone
  • --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 any BrowserContext. Launch the browser with the switches beneath it, so that what routing never sees is stopped too. reachableHosts returns null when a world lets every host through, and then there is nothing to close:

    TypeScript
    const hosts = reachableHosts(worlds);
    const owned = await openBrowser({ args: hosts === null ? [] : closedWorldSwitches(origin, hosts) });

    Like Playwright, openBrowser closes the browser on SIGINT, SIGTERM, and SIGHUP, and exits on Ctrl-C. Pass handleSignals: false when your script handles those signals itself.

  • ruleProblem: what is wrong with a rule, in words, or null

  • observe and inspectPage: a look. When one browser serves several worlds, pass observe the same hosts as reachable, so that it knows which redirects the browser let through.

  • compareLooks: a diff