Recover Playwright selectors after UI refactors with QA Skills
Compare old and new UI evidence, repair confirmed locator drift in existing Playwright tests, and return a validated diff with per-change evidence.
npx skills add agentskillexchange/skills --skill recover-playwright-selectors-after-ui-refactors-with-qa-skills
Use the selector-drift-recovery skill from QA Skills when a UI refactor has broken multiple existing Playwright locators and the intended user behavior should remain the same. The agent compares pre-refactor and current UI evidence, distinguishes selector drift from application regressions, proposes narrowly scoped locator changes, reruns the affected suite, and prepares a review packet with a confidence score and screenshot for each change. Invoke it explicitly as selector-drift-recovery in a compatible agent host.
What this skill actually does
Inputs are the affected test sources and page objects, the new build, a reproducible failing suite, and an old-DOM reference such as a retained trace, old staging build, or renderable pre-refactor code. Use Playwright 1.50 or later and the project’s existing Node/TypeScript test tooling. Install the entire upstream skills/selector-drift-recovery/ directory, including its references, into the host’s configured skill directory. Read SKILL.md and load references/recovery-scripts.md for implementation helpers. No QA runner or all-50-skills installation is required.
Capture matching old/new aria snapshots after the application’s own readiness signal. Also retain a markup outline when class, id or data-hook changes can be invisible to aria snapshots. Preserve the test process exit and every failed or timed-out attempt, including retries that later passed. Inspect actual test/POM source and UI behavior before marking a target confirmed-selector-drift. A timeout, reporter line number or guessed route is insufficient evidence for a source edit. Inventory latent locators behind the first failing step too.
Prefer test IDs, accessible roles/names and labels, applying region scoping until each replacement is unique. Preserve the original assertion’s intent. Automatically apply only candidates that satisfy the documented score floor of three and have evidence; keep ambiguous and lower-scoring candidates visible for human review. Edit inspected source occurrences or use an appropriate AST transformation instead of replacing matching strings across files. Run the full affected suite, preserve its exit status and nonempty result counts, and account separately for flakes, skips, blocked cases and unresolved failures.
Run the bundled references/score-candidates.mjs against the recovery candidate file. Its schema/score check does not verify semantic equivalence, screenshots or test execution. If there are no applied edits, report the unscorable result; reviewer-accepted sub-floor changes retain their failing score rather than being relabeled. Hand back a grouped review diff with per-change evidence and unresolved items. Open a recovery PR only when the user has authorized that external action; require human review before merging.
This workflow repairs confirmed refactor-driven locator drift in an existing Playwright suite. It excludes runtime self-healing, writing a new suite, changing test frameworks, masking application bugs, weakening assertions, or silently deleting tests. If old UI evidence is missing or behavior changed, stop and report the missing prerequisite or route to test redesign. Upstream’s dated campaign report contains a nine-test TodoMVC selector-recovery example with four stacked regression checks, but those are maintainer-reported experiments, not independently reproduced results or proof of general improvement.
Upstream intentionally supports Claude Code, Codex, Cursor and other Agent Skills-compatible runtimes, so Multi-Framework reflects the skill’s invocation rather than a fallback taxonomy. Exact reviewed source: selector-drift-recovery/SKILL.md, recovery playbook, and dated workflow report. Reviewed revision: 62434253c2592f27b494609c27f224939c86346d. Metadata only; no application testing, package installation or security audit was performed in this intake.