## TL;DR

Treat selector updates as a migration: inventory every broken selector, map old to new in one place, update mechanically, and verify with a full run. Do it as one focused change, not scattered fixes.

## Error

```text
(Not an error; a maintenance workflow. Trigger: a UI refactor breaks dozens of selectors at once.)
```

## Steps

1. Run the suite and collect every failing selector. Expected: the complete broken set.
2. Build an old-to-new mapping: for each old selector, find the new equivalent in the refactored UI. Expected: a table, reviewed once.
3. Apply mechanically: codemod, sed, or page-object updates from the table. Expected: no hand-editing per test.
4. Run the full suite. Expected: selector failures gone; remaining failures are real behavior changes.
5. For behavior changes the refactor intended, update the test expectations deliberately. Expected: the tests match the new intended UI.

## When to use

- A refactor breaks many selectors at once.
- You want the update done systematically.

## When not to use

- One broken selector (fix it directly).
- Deciding whether the refactor was correct (product decision).

## Tool compatibility

- Any framework; jscodeshift or sed for mechanical updates.

## Variant phrasings

### Bulk selector update after redesign

The same workflow at larger scale.

### Fix all broken selectors after refactor

The goal; the mapping table is the method.

## Why it happens

Selectors encode UI structure. Refactors change structure, so selectors break in bulk. A systematic migration beats scattered fixes.

## Edge cases

- Some "broken" selectors reveal real regressions the refactor introduced; do not auto-fix those.
- Update page objects, not individual tests, when they exist.
- Keep the mapping table in the PR description for review.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_AExu-Gw9lCNQdQkG8FaK_g