Healing and re-recording
When the UI changes: healing
A cached step fails mid-run → bounded retries → the agent attaches to the same browser at the exact point of failure, diagnoses (drift vs defect), and either finishes the scenario (yellow + proposal) or fails it with an explanation (red). Then:
npx saffron accept # inspect the heal
npx saffron accept <file> --propagate # fix every cache using the same locator
npx saffron accept <file> --with-feature-edit # also rewrite the adapted .feature steps
--propagate: if the heal fixed a locator other scenarios also use (same role/name core), they're repaired in the same accept, one heal, N scenarios, zero extra tokens.--with-feature-edit: applies the agent's corrected Gherkin to your.featurefile (Background steps are skipped: those you edit yourself) and keeps the cache in sync.
Assertions never heal (default). If a Then fails as written, the run
is red and the report explains why. If the change is intentional, update
the .feature (or accept the suggested edit) and let the scenario
re-record. Projects that want checkpoint flexibility can opt into
--assertion-policy adaptable-mid: mid-scenario assertions may then be
adapted (with an adaptation note, a suggested .feature edit, proof
replay, and your accept gate), but the final assertion block of every
scenario stays strict under any policy.
When a recording is wrong
Caches are never hand-edited; the honest fix is saffron run --rerecord
on the affected scenarios, which discards their caches and records them
fresh (seeded from every other recording) into a reviewable proposal.
Two guards keep bad recordings out of the tree: a fill recorded with an
empty value on a step that passes one marks the proposal UNVERIFIED with
the reason, and saffron accept --all skips UNVERIFIED proposals unless
told otherwise. The recorder also understands every way the agent can
type (fill, pressSequentially, type) and drops the clearing
fill('') that precedes typing into the same field.