How do I keep a recorded browser workflow useful when the page changes?

What should a selector identify?

Prefer a unique field label, role and accessible name, or stable test ID. “Create customer” describes the intended button more clearly than the third button inside the second panel. Text alone can also be ambiguous when several panels repeat the same words.

Ritoko’s recorder checks whether a candidate matches only the selected element and flags fragile positional targets. Review those targets before saving. A fallback should identify the same control by another stable property, not simply match whichever button still exists.

"target": {
  "primary": { "by": "role", "role": "button", "name": "Create customer" },
  "fallbacks": [{ "by": "testid", "id": "create-customer" }]
}

This example applies only if both selectors uniquely identify your application’s actual submit control. Do not copy its test ID into an unrelated site.

Why is a matching selector not enough?

A button can keep the same name while its behavior changes. Check the resulting record, not just that the click completed. Use an expect containing the current row’s email, reference or other business evidence. Check an iframe target in the correct frame, and allow enough time for a real confirmation to appear.

Build a repeatable starting point for each item, such as navigation to a new-record form. Treat autosave and auto-submitting controls as possible writes. A successful field fill is not proof that nothing irreversible happened.

What do I do when a target stops matching?

1. Inspect the paused step, page snapshot and intended business action.
2. Confirm whether the page changed or whether login, MFA, an error or the wrong account caused the mismatch.
3. Choose a new unique target for the same action and use step_repair. A commit-target replacement additionally requires confirmCommitTarget: true after checking that it is the same submit control.
4. Resume the run. Before submission the item restarts its form; after submission only eligible confirmation repair can continue on the same document.

Automatic recorded fallbacks must also match a single element. The direct runner reports fallback usage; a fallback on the commit step raises a warning to check the submit control. Host mode currently does not offer selector repair or report fallbacks. See execution and recovery.

What if the selector failure happened after submission?

Do not recreate the record to repair its receipt screen. A missing verification target can pause the first submitted item once; other failures after commit can become review. Expected text absent from the page is also a failed verification, not something a replacement selector necessarily fixes.

Use the uncertain-write recovery procedure if the result cannot be proved. Selector repair restores a target; it does not establish whether a previous business write succeeded. Test the repaired workflow on a small batch before relying on it for a large recurring job.