| name | Locator Healer Agent |
| description | Skill tự động phát hiện và sửa chữa locators bị hỏng khi automation tests fail do thay đổi DOM. |
Locator Healer Agent
Purpose: Automatically repair broken locators when automation tests fail.
When to Use
Use this skill when:
- A test fails with "element not found" or "element detached" errors
- UI has changed and existing locators no longer work
- After a frontend deployment that modifies DOM structure
Responsibilities
When a locator fails:
- Inspect current DOM or UI hierarchy
- Compare old locator with current page structure
- Identify updated attributes
- Generate a replacement locator
- Re-run test to verify the fix
Detection Strategy
Locator is considered broken when:
- Element not found (NoSuchElementException / TimeoutError)
- Element detached from DOM
- Selector matches zero elements
- Selector matches wrong element (different text/position)
Healing Workflow
Step 1: Analyze the Error
- Read error log to identify which locator failed
- Identify the Page Object file and line number
Step 2: Inspect Current DOM
- Open the page using MCP tools
- Navigate to the same state as the failing test
- Inspect the target area in DOM
Step 3: Find Alternative Locator
Try the following in priority order:
- Accessibility attributes (
aria-label, role)
data-testid / data-test
id (if stable, not auto-generated)
- Semantic locator (Playwright
getByRole, getByLabel)
css selector (stable attributes)
xpath (relative, not positional)
Step 4: Validate & Replace
- Verify the new locator matches exactly one element
- Verify the element is the correct one (text, position, behavior)
- Replace the broken locator in the Page Object class
- Re-run the test
Difference from Smart Locator Agent
| Aspect | Locator Healer | Smart Locator |
|---|
| Trigger | Test failure (reactive) | New element (proactive) |
| Input | Broken locator + error log | HTML/DOM element |
| Goal | Fix existing locator | Generate new locator |
| Workflow | Error → Inspect → Replace → Verify | Inspect → Generate → Validate |
Verification
After healing:
Rules References
.agent/rules/locator_strategy.md — Master locator priority map
.agent/rules/automation_rules.md — General automation best practices