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 } from '@playwright/test';

export function loginLocators(page: Page) {
  return {
    email: page.getByLabel('Email'),
    password: page.getByLabel('Password'),
    submit: page.getByRole('button', { name: 'Sign in' }),
    error: page.getByRole('alert'),
  };
}

Use them in tests without hiding intent.

// tests/e2e/login.spec.ts
import { expect, test } from '@playwright/test';
import { loginLocators } from '../locators/login';

test('invalid login shows accessible error', async ({ page }) => {
  await page.goto('/login');
  const login = loginLocators(page);
  await login.email.fill('user@example.com');
  await login.password.fill('wrong-password');
  await login.submit.click();
  await expect(login.error).toHaveText('Invalid email or password');
});

Healing Proposal Script

Generate proposals, not silent edits.

// scripts/propose-locator-heal.ts
type LocatorProposal = {
  testFile: string;
  oldLocator: string;
  proposedLocator: string;
  reason: string;
  confidence: 'low' | 'medium' | 'high';
  evidence: string[];
};

const proposal: LocatorProposal = {
  testFile: 'tests/e2e/login.spec.ts',
  oldLocator: "page.locator('.primary-btn')",
  proposedLocator: "page.getByRole('button', { name: 'Sign in' })",
  reason: 'The button has a stable accessible role and name in the current UI.',
  confidence: 'high',
  evidence: ['screenshot: login-button.png', 'dom: button text Sign in'],
};

console.log(JSON.stringify(proposal, null, 2));

Selenium Pattern

When using Selenium, still prefer semantics where possible.

import { By, WebDriver } from 'selenium-webdriver';

export async function clickButtonByName(driver: WebDriver, name: string): Promise<void> {
  const button = await driver.findElement(
    By.xpath(`//button[normalize-space(.)='${name}' or @aria-label='${name}']`),
  );
  await button.click();
}

Use XPath as a bridge only when the framework lacks a better role locator.

No-Heal Rules

Never heal automatically in these cases.

1. The expected accessible name disappeared.
2. The element role changed incorrectly.
3. The test now matches multiple visible elements.
4. The assertion must be weakened to pass.
5. The product copy changed and needs product approval.
6. The user flow changed.
7. The old selector pointed to a security or payment action.
8. The failing page shows a real error state.
9. The replacement uses brittle layout CSS.
10. There is no screenshot or DOM evidence.

Review Workflow

Require these artifacts with every healing change.

1. Failing test output.
2. Screenshot before repair.
3. Old locator.
4. New locator.
5. Reason for equivalence.
6. Assertion unchanged or strengthened.
7. Local rerun result.
8. Reviewer approval.

Reference Table

Locator Type	Stability	Use When
Role plus name	High	Interactive controls and headings
Label	High	Form fields
Test id	High	Stable product-owned hooks
Text	Medium	Stable visible copy
Placeholder	Medium	No label exists yet
CSS class	Low	Component internals only
XPath	Low	Legacy bridge with review

Common Mistakes

1. Calling every selector update self-healing.
2. Healing to a CSS class generated by a build tool.
3. Letting a bot commit locator changes without review.
4. Weakening assertions during repair.
5. Ignoring accessibility regressions that caused the failure.
6. Matching the first button on a page.
7. Using test ids as a substitute for accessible names.
8. Keeping no record of healed locators.
9. Retrying failed tests until one locator happens to work.
10. Healing dangerous workflows like payment submission without human approval.

Checklist

• Locator policy is documented.
• Role and label locators are preferred.
• Test ids are stable product contracts.
• Healing proposals include evidence.
• Assertions are unchanged or stronger.
• No-heal rules are enforced.
• Reviewer approves locator repairs.
• Repaired tests are rerun locally.
• Repeated repairs are tracked.
• Product accessibility bugs are fixed instead of hidden.