# ra > ra opens your web app in Chromium, inside a fake world you describe, and tells your coding agent in sentences what a person would find wrong: text cut off, a button that something else covers, grey text too pale to read, or a page that scrolls sideways on a phone. It is UI testing for agents, made to run in the middle of a change. Catch the UI bugs your agent can't see. # Start ra opens your web app in Chromium, inside a fake world you describe, and tells your coding agent in sentences what a person would find wrong: text cut off, a button that something else covers, grey text too pale to read, or a page that scrolls sideways on a phone. It is UI testing for agents, made to run in the middle of a change. ra needs Node 22.18 or later, on macOS or Linux. Install it from its GitHub release, then look at a page of your running app: ```sh npm install -D https://github.com/hraness/ra/releases/download/v0.1.6/hraness-ra-0.1.6.tgz playwright-core npx playwright-core install chromium npx ra look http://127.0.0.1:3000/ --at phone ``` If your project already has `playwright` or `@playwright/test`, leave `playwright-core` out and install the browser with `npx playwright install chromium`. That first look needs no config. It prints the findings, an outline of the page, a sketch of its layout, and where it saved two pictures. To check every screen of your app in one run, [name its states](https://hraness.github.io/ra/docs/setting-up/) and run `ra check`. To have your coding agent run ra by itself, give it [the skill](https://hraness.github.io/ra/docs/for-coding-agents/). # What it finds Each finding is one sentence that names the element and, where it can, says by how much. A phone screenshot of ra's broken fixture page with seven numbered problems, beside the sentences ra printed for them: the page scrolls sideways by 531px, a button's label is cut off by 84px, a long word runs 119px past its box, two lines are drawn over each other, a Pay now button is covered by another element, two tap targets are 18 by 18 pixels, and grey text has 1.9:1 contrast. That is `ra look broken --at phone` on [a fixture page](https://github.com/hraness/ra/blob/main/test/fixtures/site/broken.html) of planted problems. It printed 37 findings, and the picture shows seven. There are 19 kinds: - **Layout:** - [`page-scroll`](https://hraness.github.io/ra/docs/findings/#page-scroll): the page scrolls sideways. - [`cut-off`](https://hraness.github.io/ra/docs/findings/#cut-off): text or a control is clipped by a box that hides overflow. - [`spill`](https://hraness.github.io/ra/docs/findings/#spill): text runs out of its box. - [`overlap`](https://hraness.github.io/ra/docs/findings/#overlap): two pieces of text are painted over each other. - [`covered`](https://hraness.github.io/ra/docs/findings/#covered): something sits on top of a control, so a click would land on that instead. - **Reading and reaching:** - [`contrast`](https://hraness.github.io/ra/docs/findings/#contrast): text has too little contrast with what is painted behind it. - [`small-target`](https://hraness.github.io/ra/docs/findings/#small-target): tap targets on touch views are small and crowded. - [`no-name`](https://hraness.github.io/ra/docs/findings/#no-name): a control has no accessible name, or an image has no alt text. - **Content:** - [`image`](https://hraness.github.io/ra/docs/findings/#image): an image did not load, or is stretched. - [`blank`](https://hraness.github.io/ra/docs/findings/#blank): the page shows nothing. - [`document`](https://hraness.github.io/ra/docs/findings/#document): there is no title or viewport, or the status is unexpected. - [`error-overlay`](https://hraness.github.io/ra/docs/findings/#error-overlay): a dev-server error overlay is showing. - **Behaviour:** - [`console`](https://hraness.github.io/ra/docs/findings/#console): an error was logged. - [`request`](https://hraness.github.io/ra/docs/findings/#request): a request failed or answered 4xx/5xx. - [`outside`](https://hraness.github.io/ra/docs/findings/#outside): a request left the world. - [`load`](https://hraness.github.io/ra/docs/findings/#load): the page did not load. - [`busy`](https://hraness.github.io/ra/docs/findings/#busy): the page never went quiet. - [`expect` and `steps`](https://hraness.github.io/ra/docs/findings/#expect-and-steps): your own checks or steps failed. A false alarm sends an agent to change a page that was right, so ra counts one as a bug. Its twin fixture, [`tricky.html`](https://github.com/hraness/ra/blob/main/test/fixtures/site/tricky.html), holds 14 sections of things that only look wrong, such as deliberate ellipses, line clamps, scrolling strips, off-screen drawers, and screen-reader-only text. ra's tests fail if it reports anything there, at desktop or phone size, in dark mode, with scripts off, or after a jump down the page. [docs/findings.md](https://hraness.github.io/ra/docs/findings/) says how each kind is decided, what it deliberately leaves alone, and how to accept one. # How it works How ra works. Your app runs unchanged in a real browser, at each screen size you list. Its requests go to the world, the mocking half, where the replies you write answer and anything else is stopped. What the app drew goes to the look, the perception half, which measures the page with no AI model. Your agent reads one sentence per problem, such as: “Subscribe to updates” is cut off on the right by its own box (84px hidden). ra has two halves, and your app runs unchanged between them. Nothing runs inside your app: there is no SDK, bridge, test build, or fixtures database. ## The world: the mocking half The world is everything outside your app, and you describe it in `ra.config.ts`. It decides what each request gets, in this order: 1. **A reply you wrote** (`replies`) answers in the server's place. 2. **A host you block** (`block`), such as analytics, is dropped quietly. 3. **The app itself** answers its own paths. 4. **A host you allow** (`allow`), such as a font CDN, is really reached. 5. **Anything else** is stopped and reported as an `outside` finding. The broken fixture page makes seven requests. The app answers five, and the two to `api.example.com` and `analytics.example.com`, which nothing in its world answers, are stopped and reported. Beneath those rules the browser itself is closed, so what routing never sees, such as a redirect hop, an IP address, or a WebRTC connection, is stopped too ([the browser](https://hraness.github.io/ra/docs/reference/#the-browser) says how). `ra doctor` tries four ways out, and each must be stopped. The world stays closed when ra looks at a deployment, too. A **state** is a URL into a world: a path, plus the replies, storage, cookies, and clock that go with it, and optional steps. You name each state once, such as an empty inbox, a failed payment, or a name 80 characters long, and ra looks at it through every **view** you list, such as desktop, a phone, and dark mode. Stand-in servers (`upstreams`) answer what your app's *server* calls. ## The look: the perception half The look reads the page five ways, and no model takes part in any of them: | Reading | How ra takes it | What it finds | | --- | --- | --- | | Boxes | The layout engine's own rectangles for each element and each line of text, set against the screen, the boxes that clip them, each other, and each image's own size. | `page-scroll`, `cut-off`, `spill`, `overlap`, `small-target`, `image`, `blank` | | What is on top | The element the browser reports on top at the centre of each control, tested as ra scrolls down the page in half-screen steps, up to 40 screens. | `covered` | | Two pictures | The page as it is, and the page with every glyph made transparent, which shows the true background under each line of text, whatever painted it: a gradient, a photo, an overlay, or a blend. | `contrast` | | Roles, names, and the document | Each control's role and accessible name, which ra also prints as the outline, and the page's title, viewport, and response status. | `no-name`, `document`, `error-overlay` | | The console and the network | Every error logged and every request made, until the network has been quiet for 200 ms or 5 seconds have passed. | `console`, `request`, `outside`, `load`, `busy` | Your own checks add the last two kinds, `expect` and `steps`. What comes out is text first, with two pictures for when the words leave a doubt. `ra check` takes the same look at every state through every view, and exits 1 when anything is wrong. # When to use it A browser check costs more than a unit test: each look loads the page in a real browser and waits for it to settle, and browser tests flake more than most ([how it compares](https://hraness.github.io/ra/docs/how-it-compares/)). So ra is worth running when the answer depends on what a browser paints. **Use ra when:** - **The question is “what does a person see here?”** For example, whether this fits at 320px, whether dark mode keeps the text readable, whether anything covers the button, and whether the long name spills out of its card. Only the layout engine knows, because the answer depends on the fonts, the cascade, and the width of the screen. - **The state is expensive to reach by hand.** Examples are an empty inbox, a failed payment, a 3,000-row table, an upstream returning 500, a name 80 characters long, or a clock just before midnight. You name each one once as a URL plus a fake world, and from then on one command reaches it. - **A change has a visual blast radius.** Examples are a CSS refactor, a design-token change, or a dependency bump. Run `ra snap`, make the change, then run `ra diff`. It tells you which elements moved, resized, appeared, or vanished, which outline lines changed, and which findings are new. - **An agent is changing UI.** It works from text it can act on, and opens a picture only when the text is not enough. **Do not use ra for:** - **Logic.** If it can be tested without a browser, test it without one. - **Restating the implementation.** Asserting `toHaveCSS("color", "rgb(…)")` or a class name proves that you wrote what you wrote. ra asks what a person would ask instead: whether the text can be read, whether the control can be reached, and whether it fits. - **Proving a live system works.** ra closes the world on purpose. Smoke tests and monitoring against real services do that job. `ra check --url https://…` against a deployment checks what the deployment *shows*, and the outside world stays closed even then. - **Pixel baselines in CI, or coverage ledgers.** Rendering varies from host to host, so a baseline holds only where it was made ([design decisions](https://hraness.github.io/ra/docs/design-decisions/)). Snapshots in ra live on your machine for the length of one change. CI runs `ra check`, which has no baselines. - **Cross-browser matrices.** ra drives Chromium only. Use Playwright Test when WebKit- or Firefox-specific behaviour matters. - **A full accessibility audit.** ra reports what a person would trip over: unnamed controls, missing alt text, low painted contrast, and small tap targets. Run axe or a manual audit for the rest. ## Limits - ra drives Chromium only, on macOS and Linux. - It is not a full accessibility audit. - Placeholder text is not checked for contrast yet. - Contrast is read from painted pixels, so text close to a threshold can pass under one system's font rendering and fall short under another's. - Pictures and contrast cover at most the first 12,000px of a page. ra says so when a page is taller. - When a page scrolls inside an element rather than as a whole, its pictures show that element's first screen, and ra says so. # Setting up ra needs Node 22.18 or later and a Playwright in your project: `playwright-core`, `playwright`, or `@playwright/test`. With Bun, install it like this: ```sh bun add -d https://github.com/hraness/ra/releases/download/v0.1.6/hraness-ra-0.1.6.tgz playwright-core bunx --no-install playwright-core install chromium ``` To upgrade, give the new release's address the same way. npm replaces the old one: `npm install -D `. Bun stops with `DependencyLoop` while its lockfile names the old address, so remove ra and add it again (`bun remove @hraness/ra`, then `bun add -d `), or change the address in `package.json` and run `bun install`. `ra look` also takes the address of a deployment: ```sh npx ra look https://example.com/pricing --at phone.dark ``` To name states, add `ra.config.ts` at the project root: ```ts import { defineConfig } from "@hraness/ra"; export default defineConfig({ app: { command: "bun run dev --port {port}" }, views: ["desktop", "phone", "phone.dark"], world: { allow: ["fonts.googleapis.com", "fonts.gstatic.com"], block: ["*.posthog.com"], replies: { "GET /api/me": { json: { name: "Ada" } } }, }, states: { home: "/", pricing: "/pricing", "inbox-empty": { url: "/inbox", world: { replies: { "GET /api/messages": { json: [] } } } }, "inbox-down": { url: "/inbox", world: { replies: { "GET /api/messages": { status: 500, json: { error: "down" } } } }, see: ["Something went wrong"], }, "long-name": { url: "/settings", world: { replies: { "GET /api/me": { json: { name: "Wolfeschlegelsteinhausenbergerdorff" } } } }, }, }, }); ``` Then: ```sh npx ra states # what this project names npx ra look inbox-empty --at phone npx ra check # every state through every view; exits 1 on findings npx ra snap && $EDITOR app.css && npx ra diff ``` Node strips the types from `ra.config.ts`, so relative imports in it need their `.ts` extension, and it cannot use path aliases. [Recipes](https://hraness.github.io/ra/docs/recipes/) covers choosing states and views for each kind of app. # For coding agents ra comes with a skill, [`skills/ra/SKILL.md`](https://hraness.github.io/ra/docs/skill/), that teaches a coding agent when to reach for ra and how to read what it prints. It ships in the package. Copy it to where your agent reads skills; for Claude Code, that is: ```sh mkdir -p .claude/skills cp -R node_modules/@hraness/ra/skills/ra .claude/skills/ ``` The loop: 1. Run `ra look --at phone`, read the findings and the outline, and fix what is wrong. 2. Run `ra look` again to confirm. Run `ra check` before handing off. 3. For a change with a wide reach, run `ra snap` first and `ra diff` afterwards. 4. Open a picture only when the words leave a doubt, such as how a gradient looks. Every look writes `.ra/look/..png` (the first screen) and `.full.png` (the whole page). A look is short, and it is text the agent can act on. On ra's fixture site, a page with nothing wrong prints 52 lines, about 500 tokens at four characters a token: “no findings”, an outline whose lines map onto `getByRole`, a sketch of the layout, and where the pictures are. The broken page at phone prints 123 lines, about 1,900 tokens, for 37 findings. A picture of that whole page, 921×2523, would cost up to 3,003 tokens under [Claude's formula](https://platform.claude.com/docs/en/build-with-claude/vision) of one token for each 28×28-pixel patch. When one faint colour is used in many places, a look names the first ten texts and counts the rest. On one public page, 235 of 237 findings were the same grey at 3.5:1: listing every one took 532 lines, and naming ten takes 83 ([#11](https://github.com/hraness/ra/pull/11)).
A look at a page with nothing wrong, trimmed ``` $ npx ra look home --at desktop home at desktop (1440×900) http://127.0.0.1:57437/ — 200 — "Fixture — Home" page 1440×1237, 3 requests, 1.1s no findings outline banner link "Fixture" → / navigation "Main" link "Tricky" → /tricky link "Broken" → /broken link "App" → /app main heading "A page with nothing wrong" [level=1] paragraph: This page is the control. Whatever ra reports here is a false alarm, at any width and in either colour scheme. link "Open the app" → /app … heading "A form" [level=2] textbox "Email" checkbox "Send me news" button "Sign up" contentinfo … layout header.top 1440×65 at 0,0 sticky, 3 items in nav, 3 across nav "Main" 192×40 at 1228,12 3 items, 3 across main "A page with nothing wrong" 960×1027 at 240,65 3 items in ul.cards, 3 across form 920×176 at 260,836 3 items stacked footer 1440×145 at 0,1092 3 items in nav, 3 across nav "Footer" 1400×40 at 20,1117 3 items, 3 across pictures: .ra/look/home.desktop.png (first screen), .ra/look/home.desktop.full.png (whole page) ```
# In CI Run `ra check`. It needs no stored baselines, so it only fails when something is wrong now: ```yaml - run: bun install --frozen-lockfile - run: bunx --no-install playwright-core install --with-deps chromium - run: bunx --no-install ra check ``` A failing check prints each finding once, tagged with the views it shows at when that is not every view, and ends with a receipt for the browser it ran. This is ra's own fixture site, trimmed: ``` $ ra check ra check — 23 states, 33 looks in 10.4s — http://127.0.0.1:58744 ✗ noscript /noscript contrast "This line shows only when scripts are o…" has 1.9:1 contrast (#b9bdc7 on #ffffff); text this size needs 4.5:1. at p.faint "This line shows only when scripts are o…" ✗ broken /broken cut-off "Subscribe to updates" is cut off on the right by its own box (84px hidden). at button.button.cut "Subscribe to updates" covered button "Pay now" is covered by span.veil; a click or tap on it would land on that instead. at button.button "Pay now" outside The page asked api.example.com for data (GET https://api.example.com/v1/me); nothing in its world answers. Give api.example.com a reply, or list it under allow or block. page-scroll The page scrolls sideways by 531px. Sticking out: div.too-wide "This box is 900 pixels wide whatever th…" (900px wide, ends 530px past the edge). [phone, phone.dark] … ✗ pinned /pinned covered button "Add to cart" is covered by p "Free shipping over fifty"; a click or tap on it would land on that instead. covered p.cookies "This site keeps a cookie." covers 2 controls: button "Help", button "Chat". at button.help "Help" … ✗ leave /leave load The page did not load, because a redirect from /leave sent it outside its world, to https://example.com/ (net::ERR_PROXY_CONNECTION_FAILED at http://127.0.0.1:58744/leave). The outside finding says more. outside A redirect from /leave tried to take the page to https://example.com/, which is not in its world, and was stopped. The browser follows redirects by itself, so a reply for example.com cannot answer it. Give /leave a reply that does not redirect there, or list example.com under block to stop it quietly, or under allow to let it through. … ✓ home ✓ tricky … 57 findings in 13 of 23 states, with 3 notes. Look closer: ra look noscript --at desktop browser: Chromium 158.0.8127.18, playwright-core 1.65.0, ~/Library/Caches/ms-playwright/chromium-1254/…/Google Chrome for Testing ``` `ra check --json` prints every look as data, for tools that want more than the exit code. # Recipes ra works the same way for every kind of app: it reaches the app, names states, closes the world and looks. What changes from one kind to the next is how the app is started and where its outside world lives. ## Choosing states and views Name a state for each **visual risk**, not for each route. Three to five states per screen that matters usually covers it: - **typical**: realistic data. - **empty**: no items yet, a new account. - **overflowing**: long names, many items, long words, large numbers. - **failed**: an upstream returns an error, or something times out. - **edge of time or place**: a date near midnight, a different locale, a different `clock`. Leave out what a unit test already proves, and states nobody will ever see. For views, use `desktop` and `phone` always. Add `phone.dark` when the app has a dark theme, since dark mode is where contrast breaks. Add `narrow` (320px) when layouts are tight. `tablet` is rarely worth its time. A look takes about one to four seconds, and four run at once. Thirty states through three views is about a minute. ## A static site Marketing sites, documentation and landing pages. ```ts export default defineConfig({ app: { static: "dist" }, views: ["desktop", "phone", "phone.dark", "narrow"], world: { allow: ["fonts.googleapis.com", "fonts.gstatic.com"], block: ["*.plausible.io", "*.googletagmanager.com"], }, states: { home: "/", pricing: "/pricing", docs: "/docs/getting-started", "not-found": { url: "/no-such-page", status: 404 }, }, }); ``` Build, then `ra check`. These states need no world of their own, so the same config can check the deployment once it is live: ```sh ra check --url https://example.com ``` The outside world stays closed against a deployment too. A third-party script that the page depends on has to be in `allow` (or passed with `--allow`), and that is how you learn what the page depends on. ## A browser app with an API A single-page app, or any page that fetches from the browser. ```ts export default defineConfig({ app: { command: "bun run dev --port {port}", ready: "/" }, views: ["desktop", "phone", "phone.dark"], world: { replies: { "GET /api/me": { json: { id: 1, name: "Ada Lovelace", plan: "pro" } }, "GET /api/projects": { json: [{ id: 1, name: "Analytical Engine", updated: "2026-01-02T10:00:00Z" }] }, }, }, states: { projects: "/projects", "projects-empty": { url: "/projects", world: { replies: { "GET /api/projects": { json: [] } } } }, "projects-many": { url: "/projects", world: { replies: { "GET /api/projects": { json: Array.from({ length: 200 }, (_, i) => ({ id: i, name: `Project ${i} with a name long enough to wrap twice`, updated: "2026-01-02T10:00:00Z" })) }, }, }, }, "projects-down": { url: "/projects", world: { replies: { "GET /api/projects": { status: 503, json: { error: "unavailable" } } } }, see: ["Try again"], }, "signed-out": { url: "/projects", world: { replies: { "GET /api/me": { status: 401, json: {} } } }, see: ["Sign in"] }, }, }); ``` A reply can be a function of the request, for an API whose answer depends on what was sent: ```ts "POST /api/search": ({ body }) => ({ json: { results: JSON.parse(body ?? "{}").q === "" ? [] : results } }), ``` An error the world is told to give, such as the 503 above, is the state itself, not a finding. A page that falls over because of it is a finding. ## A server-rendered app whose server calls other services Next.js server components, Remix loaders, Rails or Django views. The browser never sees these calls, so routing cannot fake them. Give the server stand-ins instead: ```ts export default defineConfig({ app: { command: "bun run dev --port {port}", env: { CONTENT_API_URL: "{upstream.content}", PAYMENTS_API_URL: "{upstream.payments}" }, }, world: { upstreams: { content: { "GET /articles": { json: articles } }, payments: { "GET /v1/customer": { json: { status: "active" } } }, }, }, states: { front: "/", "front-empty": { url: "/", world: { upstreams: { content: { "GET /articles": { json: [] } } } } }, "billing-lapsed": { url: "/account", world: { upstreams: { payments: { "GET /v1/customer": { json: { status: "past_due" } } } } } }, }, }); ``` Each stand-in is a loopback server whose replies change with the state being looked at. Because of that, looks run one at a time when upstreams are in use. A call the server makes that no reply covers becomes an `outside` finding, so you see every service the page touches. If the app reads its service addresses from constants rather than from the environment, make them configurable. That is the one change ra may ask of an app, and it is usually a single line. ## An app with its own database ra does not seed databases. You have three options: - Point the app at a fixture database in `app.command`, such as `DATABASE_URL=file:./fixtures/demo.db bun run dev --port {port}`, and keep that file small and committed. - Let the app read the data it shows through a service you can stand in for with `upstreams`. - Reach the state through the interface with `steps`, when that is quick. ## A large web surface Apps with hundreds of routes, such as dashboards, settings or content sites: - Name states for each *template*: one list page, one detail page, one settings form and one empty state each. Add a state for every page that has broken before. - Use `ra look /any/path` freely while working. Ad hoc paths need no config. - Keep `ra check` to the 20 to 40 states that carry the risk. If it grows slow, check fewer states before reaching for fewer views. ## A desktop or native app's web surfaces ra looks at what runs in a browser: - The product's marketing site and documentation. - Its web renderer, when that renderer can run in a plain browser with a fallback for its native bridge (`window.__TAURI__`, an Electron preload). That fallback is the app's job, and it is usually worth having anyway. ra does not look at native interfaces built with SwiftUI, AppKit or UIKit. Use the platform's own tools for those. ## Pages drawn on a canvas Canvas, WebGL and terminal-like interfaces show little to the outline and the layout checks. ra still takes pictures, checks the page around the canvas, and runs `see` and `expect`. If most of the page is canvas, ra is the wrong tool for it. ## A check after deploying ```sh ra check --url https://staging.example.com ``` `ra check` skips states that bring their own world or steps, and `ra look` refuses them. Mark one `live: true` if it is safe there. The deployment answers for itself: no reply rule stands in for it, though `block` still applies to its paths. Outside hosts stay closed unless allowed. This answers "does the deployment look right?". It does not answer "do the services behind it work?": that is what monitoring is for. # Reference ## Commands | Command | What it does | | --- | --- | | `ra look ` | 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 ""` narrows it to part of the page. `--then ""` 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 ` uses an app that is already running, or a deployment. `--allow ` lets the page reach that host during this run. `--json` prints data instead of text. `--config ` and `--jobs ` 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, `