The one-minute version. relai points at elements on your page (a button, a field, a card). If that element has a small, stable label in its code called a test hook, relai locks onto it perfectly and finds it again on every future visit — even after you redesign the page. Adding these takes seconds and is the single biggest thing you can do to make relai more reliable. You only need them on the handful of things people actually report bugs about.
What’s a “test hook”?
It’s a tiny, invisible name you add to an element in your site’s code. It doesn’t change how anything looks or works — it’s just a durable handle. The common one looks like this:
data-testid="add-to-cart"Your developers may already use these for automated testing (that’s where the name comes from). relai reads the same handles.
Why relai cares
When an element has no stable handle, relai has to identify it by softer clues — its visible text, its position on the page, the shape of the surrounding layout. Those clues change the moment someone edits the wording or restyles the page, and then relai can lose the element or grab the wrong one. A test hook doesn’t change when the design does, so relai keeps finding the right thing.
Exactly what to add, and where
Add a data-testid to the opening tag of the element, with a short, descriptive, lower-case name:
Before
<button class="btn btn-primary">Add to cart</button>After
<button class="btn btn-primary" data-testid="add-to-cart">Add to cart</button>That’s the whole change. (data-cy or a stable id also work — but pick one and be consistent.)
What it does to relai’s confidence
relai scores every capture 0–100 for how reliably it can re-find the element. Test hooks put it at the top of the scale:
data-testid— 98- A stable
id— 85 - Just an aria-label — 62
- Just its visible text — 55
- Nothing but its position — 8–12
A test hook takes an element to 98 — the top of the scale — and keeps it there even after you ship a redesign, while softer clues like visible text or position slip the moment the page changes.
The rules for a good hook
- Make it descriptive:
data-testid="checkout-button", notdata-testid="btn1". - Keep it stable: the same element should keep the same hook across deploys. Do not let your build tools auto-generate or randomize these — a hook that changes every release is worse than none.
- Lower-case with dashes is the convention:
email-field,save-draft,nav-billing.
Which elements are worth it
You don’t need to do your whole app. Add hooks to the things people file bugs about — roughly the 20% that matters:
- Primary action buttons: submit, save, checkout, add to cart, delete, publish.
- Key form fields: email, password, search, quantity, the main inputs on important forms.
- Important navigation: the main menu items and tabs people reference (“the Billing tab”).
- Status / result areas: an error banner, a success message, an order-total line — anything a bug report would point at.
Skip decorative text, icons, and layout wrappers. If you’d never write “the X is broken” about it in a bug report, it doesn’t need a hook.
That’s it
Spend 20 minutes tagging your top screens’ key buttons and fields, keep the names stable, and relai’s accuracy on exactly the elements you care about jumps dramatically — no relai settings to change.