how to update selectors after a UI refactor

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

(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/pstAExu-Gw9lCNQdQkG8FaKg