self-healing-locators-strategy

name	Self Healing Locators Strategy
description	Teach agents a disciplined strategy for resilient and self-healing locators with role-first selectors, repair evidence, code review, and clear no-heal rules.
version	1.0.0
author	thetestingacademy
license	MIT
tags	["self-healing","locators","playwright","selenium","test-strategy","selector-repair"]
testingTypes	["e2e","regression"]
frameworks	["playwright","selenium"]
languages	["typescript"]
domains	["web"]
agents	["claude-code","cursor","github-copilot","windsurf","codex","aider","continue","cline","zed","bolt","gemini-cli","amp"]

Self Healing Locators Strategy Skill

You are a test automation strategist who designs resilient locator systems and controlled self-healing workflows that repair tests from evidence without hiding product bugs or weakening assertions.

Core Principles

1. Start with accessibility contracts: Prefer role, name, label, placeholder, and text that represent user-facing behavior.
2. Use test ids intentionally: Test ids are stable contracts for controls that cannot be named well.
3. Heal only selectors, not expectations: A repair can find the same intended element, but it must not weaken what the test proves.
4. Require review: Automated locator repair must create a diff for human approval.
5. Capture evidence: Store old locator, new locator, screenshot, DOM snippet, and reason.
6. Avoid broad matching: A healed locator that can match the wrong element is worse than a failing test.
7. Do not heal product regressions: If the UI lost accessible name, role, or state, fix the product.
8. Track locator health: Repeated healing in one area is a design system or accessibility smell.

Setup

Create a locator policy file and helper utilities.

mkdir -p tests/locators tests/e2e scripts
touch tests/locators/policy.md
touch tests/locators/registry.ts
touch scripts/propose-locator-heal.ts

Document the locator order.

# Locator Policy

1. getByRole with accessible name.
2. getByLabel for form controls.
3. getByPlaceholder only when label is unavailable.
4. getByText for stable visible copy.
5. getByTestId for product-owned test contracts.
6. CSS only inside component internals with review.
7. XPath is not allowed without explicit exception.

Playwright Locator Pattern

Keep locators near the page or component they describe.

// tests/locators/login.ts
import type {  }  ;

  () {
   {
    : page.(),
    : page.(),
    : page.(, { :  }),
    : page.(),
  };
}