# Locator Healer Agent

> Skill tự động phát hiện và sửa chữa locators bị hỏng khi automation tests fail do thay đổi DOM.

- **Type:** Skill
- **Install:** `agentstack add skill-anhtester-claude-testing-kit-locator-healer-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [anhtester](https://agentstack.voostack.com/s/anhtester)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [anhtester](https://github.com/anhtester)
- **Source:** https://github.com/anhtester/claude-testing-kit/tree/main/.claude/skills/locator_healer_agent

## Install

```sh
agentstack add skill-anhtester-claude-testing-kit-locator-healer-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

1. Inspect current DOM or UI hierarchy
2. Compare old locator with current page structure
3. Identify updated attributes
4. Generate a replacement locator
5. 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:

1. Accessibility attributes (`aria-label`, `role`)
2. `data-testid` / `data-test`
3. `id` (if stable, not auto-generated)
4. Semantic locator (Playwright `getByRole`, `getByLabel`)
5. `css selector` (stable attributes)
6. `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:

- [ ] Locator must match exactly one element
- [ ] Element is the correct target (verify text/attributes)
- [ ] Test must pass successfully
- [ ] Locator is stable across page reloads

---

## Rules References

- `.claude/rules/locator_strategy.md` — Master locator priority map
- `.claude/rules/automation_rules.md` — General automation best practices

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [anhtester](https://github.com/anhtester)
- **Source:** [anhtester/claude-testing-kit](https://github.com/anhtester/claude-testing-kit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anhtester-claude-testing-kit-locator-healer-agent
- Seller: https://agentstack.voostack.com/s/anhtester
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.