ra

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.

Read the docsGitHub

Version 0.1.6 · MIT licence · Node 22.18 or later

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 modelScript against the networkAccessibility snapshotra
Who decides what is wrongThe model, by eyeYour assertionsThe model, from textMeasurements
Contrast, overlap, clipping, coveringOften misjudgedOnly what you assertNot in the treeMeasured and reported
Live services in the loopUnless you mock themUnless you mock themUnless you mock themOnly the hosts you allow by name; any other request is stopped and reported
Empty, failing, and overflowing statesReached by handMocks you writeReached by handNamed 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 check needs no baseline, and ra snap and ra diff say 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 detect looks 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.

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 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
    • console: an error was logged.
    • request: a request failed or answered 4xx/5xx.
    • outside: a request left the world.
    • load: the page did not load.
    • busy: the page never went quiet.
    • 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, 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:

  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 look: the perception half

The look reads the page five ways, and no model takes part in any of them:

ReadingHow ra takes itWhat it finds
BoxesThe 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 topThe 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 picturesThe 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 documentEach 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 networkEvery 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

How it works in full

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:

Terminal
mkdir -p .claude/skills
cp -R node_modules/@hraness/ra/skills/ra .claude/skills/

The loop:

  1. Run ra look <state> --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/<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
Terminal
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.

When to use it in full

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:

Terminal
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 and run ra check. To have your coding agent run ra by itself, give it the skill.