# How it works

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://hraness.github.io/ra/media/ra-flow-dark.png">
  <img src="https://hraness.github.io/ra/media/ra-flow.png" width="830" alt="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).">
</picture>

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.
