Catch the UI bugs your agent can't see.
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.
Mocking
The world
Replies you write.
Anything else is stopped.
Real browser
Your app
Unchanged, at each screen size you list.
Perception
The look
Measures the page, with no AI model.
What your agent reads
cut-off "Subscribe to updates" is cut off on the right by its own box (84px hidden).
covered button "Pay now" is covered by span.veil; a click or tap on it would land on that instead.
How it compares
An agent that wants to know whether its UI change worked has three easy options, and each misses something.
| Screenshot to a model | Script against the network | Accessibility snapshot | ra | |
|---|---|---|---|---|
| Who decides what is wrong | The model, by eye | Your assertions | The model, from text | Measurements |
| Contrast, overlap, clipping, covering | Often misjudged | Only what you assert | Not in the tree | Measured and reported |
| Live services in the loop | Unless you mock them | Unless you mock them | Unless you mock them | Only the hosts you allow by name; any other request is stopped and reported |
| Empty, failing, and overflowing states | Reached by hand | Mocks you write | Reached by hand | Named once in a config |
A screenshot for a model to judge. Models are weakest at the measurements that layout bugs come down to. In UI-Lens (CVPR 2026), nine multimodal models judged screens from 11 mobile apps. On text overflow their accuracy averaged 50.04%, where a coin flip scores 50%, and on container overlap 54.14%. A screenshot also shows only what fits in it. The broken fixture page is 921px wide in a 390px view, so a picture of the screen crops more than half of it, and a picture of a long page is scaled down before the model sees it: Claude's docs cap the long edge at 2,576px, or 1,568px before Claude 4.7, so a page 5,000px tall arrives at half its size or less. ra measures instead: boxes from the layout engine, and contrast from the painted pixels.
A Playwright script against the real network. Browser tests flake far more than most tests. At Google, WebDriver tests were flaky six to eleven times as often as tests overall: 10.45% in Java and 18.72% in Python, against 1.65% (Google Testing Blog, 2017). A 2025 study found that three quarters of flaky tests fail together in clusters, with “intermittent networking issues and instabilities in external dependencies as the predominant causes” (Parry et al.). Playwright's own advice is “Only test what you control” (best practices). ra does that for every state, with no test code: its world is fake by default, and a request that nothing in it answers is stopped and reported.
An accessibility snapshot. A tree of roles and names is text a model can read, but it leaves out colour, geometry, and stacking order, so it cannot show low contrast, overlap, clipping, or a covered button. On the broken fixture page, those are 29 of the 37 findings. ra prints the same kind of outline and puts measured findings beside it.
Other tools
This list dates from November 2026, and each of these tools moves fast.
- Agent browsers, such as Playwright MCP, Chrome DevTools MCP, and agent-browser, give the agent a page to drive, its accessibility tree, and pictures. Whether the layout is right is left to the model. ra measures the layout and hands the agent a verdict.
- Visual regression tools, such as Chromatic, Percy, Argos, Meticulous, and BackstopJS, compare new pictures with earlier ones. They show every change, wanted or not, and someone decides which changes are bugs. A bug that was there from the start is part of the baseline.
ra checkneeds no baseline, andra snapandra diffsay in words what moved during one change. - Accessibility engines, such as axe-core and Lighthouse, check many more rules than ra has. Run one alongside ra, which adds what only the painted page shows: contrast over images and gradients, text that is clipped or spills, and controls that something else covers.
- Rendered-UI linters are the closest. renderlint shares ra's premise and measures contrast the same way, with more rules, a sweep across widths, stress passes with longer text, and a Stop hook for Claude Code. Impeccable's
detectlooks for design “slop” with deterministic rules. ra puts its weight on the world around the page: each state brings its own replies, storage, cookies, and clock, a request that nothing answers is reported, and the same closed world holds when ra looks at a deployment.
What it finds
Each finding is one sentence that names the element and, where it can, says by how much.
That is ra look broken --at phone on a fixture page of planted problems. It printed 37 findings, and the picture shows seven. There are 19 kinds:
- Layout
page-scroll: the page scrolls sideways.cut-off: text or a control is clipped by a box that hides overflow.spill: text runs out of its box.overlap: two pieces of text are painted over each other.covered: something sits on top of a control, so a click would land on that instead.
- Reading and reaching
contrast: text has too little contrast with what is painted behind it.small-target: tap targets on touch views are small and crowded.no-name: a control has no accessible name, or an image has no alt text.
- Content
image: an image did not load, or is stretched.blank: the page shows nothing.document: there is no title or viewport, or the status is unexpected.error-overlay: a dev-server error overlay is showing.
- Behaviour
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, 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 says how each kind is decided, what it deliberately leaves alone, and how to accept one.
How it works
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:
- A reply you wrote (
replies) answers in the server's place. - A host you block (
block), such as analytics, is dropped quietly. - The app itself answers its own paths.
- A host you allow (
allow), such as a font CDN, is really reached. - Anything else is stopped and reported as an
outsidefinding.
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 |
For coding agents
ra comes with a skill, skills/ra/SKILL.md, 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:
mkdir -p .claude/skills
cp -R node_modules/@hraness/ra/skills/ra .claude/skills/The loop:
- Run
ra look <state> --at phone, read the findings and the outline, and fix what is wrong. - Run
ra lookagain to confirm. Runra checkbefore handing off. - For a change with a wide reach, run
ra snapfirst andra diffafterwards. - Open a picture only when the words leave a doubt, such as how a gradient looks. Every look writes
.ra/look/<state>.<view>.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 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).
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)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). 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?”
- The state is expensive to reach by hand.
- A change has a visual blast radius.
- An agent is changing UI.
Do not use ra for
- Logic.
- Restating the implementation.
- Proving a live system works.
- Pixel baselines in CI, or coverage ledgers.
- Cross-browser matrices.
- A full accessibility audit.
Start
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:
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 phoneIf 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 and run ra check. To have your coding agent run ra by itself, give it the skill.