Did the app break, or did the tests go stale?
A pull request goes red. Two end-to-end tests fail. Before anyone can fix anything, someone has to answer a question the build does not: did this change break the app, or did it change the app on purpose and leave the tests behind?
Both happen every week, and they call for opposite responses. A regression gets fixed before merge. A stale test gets updated, and the change ships. Getting it wrong costs either a bug in production or an afternoon spent debugging a test that was doing its job.
The failure output does not help much. It tells you which line threw and which locator timed out:
Error: locator.click: Timeout 5000ms exceeded.
- waiting for getByTestId('place-order')What it does not tell you is the one fact that would settle the question: which part of the product the test was exercising, in terms you could match against the diff. getByTestId('place-order') is an address, not a name. Nothing in the run records that this test was about the Place order button, so nothing can notice that the pull request is the one that removed it.
Name the controls
razo is a thin layer over Playwright that makes that fact explicit. Every control a test touches is declared with a type and a human name:
import { Button, Input, Label } from '@razohq/razo';
test('export a model', async ({ page }) => {
await new Input(page, 'filename', 'Filename').fill('mi-llavero');
await new Button(page, 'export', 'Export').click();
await new Label(page, 'status', 'Export status').expectText('Exported mi-llavero.3mf');
});The name is required. An anonymous control is rejected by the constructor, because everything below depends on it.
Two outputs from every step
Each action and assertion produces two things at once.
The first is a sentence in the Playwright report, built from one fixed template per verb:
Type "mi-llavero" into field "Filename"
Click button "Export"
Assert label "Export status" has text "Exported mi-llavero.3mf"A failing report now reads like a description of what the user was trying to do, which is useful on its own.
The second is a structured record of the same step, written to test-results/<test>/razo-steps.json:
{
"action": "click",
"controlType": "button",
"name": "Export",
"sentence": "Click button \"Export\"",
"selector": "[data-testid=\"export\"]",
"status": "failed",
"error": "locator.click: Timeout 5000ms exceeded.",
"timestamp": "2026-10-21T07:34:12.418Z"
}A failed assertion also records expected and the actual value read from the DOM. The sentence is for a person reading the report. The record is for a machine, and it is what makes the rest possible.
Joining the test to the diff
With that record, a failing test is no longer just a stack trace. It is a list of named controls it drove, which can be compared with what the pull request changed.
That is what the razo analyzer does on a pull request. On razohq/razo-demo#1, a public PR that hides a checkout button and breaks two of its own tests, it posted:
Intentional change — PR intentionally hides the Place order button and removes the Mouse row; both failing tests assert the old UI.
placing the order confirms it— tests/checkout.spec.ts ↳ touched button "Place order", which this PR changed intests/checkout-page.tsthe cart lists both items— tests/checkout.spec.ts
The second line is the part that needs razo. The analyzer knows the test clicked a control named Place order because the test said so, and it can see that the diff touched it.
It also knows what it cannot know. Blank that PR's description and the verdict becomes Undetermined: the diff says what changed, never whether it was meant, so razo describes the change and asks the author instead of guessing. How the analyzer reaches a verdict is the subject of the next post.
Healing that does not hide anything
Naming controls has a second payoff. When a test's locator stops matching anything, usually because a data-testid was renamed, razo already knows the control is a button called Export. It tries the fallbacks you declared, then role=button[name="Export"], and uses the first that matches exactly one element.
This is deterministic. No model runs inside your tests. And it is never silent: a healed step passes, but its record carries healed: { from, to }, so the drift shows up in the report instead of being absorbed. Set RAZO_HEALING=fail and the same situation fails with a "locator drift" error that names the locator that would have worked.
Healing only applies when the element cannot be found at all. An element that exists and fails an action or an assertion fails normally, because that is what a regression looks like.
What the page did
Sometimes the most useful clue is not in any step. The button was clicked, the request behind it answered 500, and the test failed three steps later waiting for a confirmation that never came.
Since razo 0.4.0, the framework listens to the page while the test runs and records console errors, uncaught exceptions, failed requests and 5xx answers, each with the step it followed. A failed test also names its first anomaly:
"firstAnomaly": {
"kind": "http-error",
"text": "POST https://shop.test/api/orders → 500",
"afterStep": "Click button \"Place order\""
}"The order API answered 500 right after the click" is a very different conversation from "the test timed out", and it comes from the page's own events, with no trace to open.
Secrets stay out
A narrated step that types into a password field would put the password in the report. razo detects password and one-time-code fields and masks the value as ******** in the sentence, the record and the error. sensitive: true covers secrets in ordinary inputs. The analyzer masks secrets again before anything leaves the machine.
Where it is now
razo 0.1.0 went out in July 2026. Today the framework has 20 controls, narrated assertions, self-healing locators, a Vite plugin that generates data-testids from component names, and page signals. It is MIT licensed and has no runtime dependencies.
Around it there are three more pieces, each with its own post coming:
- The analyzer, which turns failed runs into a verdict on the pull request.
- razo.ar, the dashboard that keeps the runs and their verdicts.
- Morning triage, which groups last night's failures by cause and says what each group is, without calling a model.
To try it:
npm install -D @razohq/razoThe getting started guide takes a few minutes, and the code is on GitHub.