Runbook 16 — Locator Intelligence Agent

Replace brittle manual locator authoring with a deterministic pipeline that discovers, validates, refines, and persists locator candidates as reusable artifacts.

Objective

Replace brittle manual locator authoring with a deterministic locator pipeline.
Derive locator candidates from the live system instead of guessing them first.
Validate candidates against the page and record pass/fail results.
Refine ambiguous matches through scoping and persist the outputs as reusable artifacts.

Key shift

Locators are not manually guessed. They are derived from the live system, validated against reality, and refined until deterministic.

Definition of done

✔ Real page inventory generated from the live system.
✔ Locator candidates derived from accessibility semantics.
✔ Validation results recorded as pass/fail evidence.
✔ Ambiguous locators resolved through scoping or flagged.
✔ Outputs stored as reusable artifacts.

System overview

Flow

DISCOVERY → VALIDATION → REFINEMENT → ARTIFACTS → TESTS → RELEASE SIGNAL

Discovery	Extract interactive elements from the live DOM.
Validation	Check each locator candidate against the actual page.
Refinement	Resolve ambiguity with scoped strategies or flag risk.
Artifacts	Persist locator maps, validation results, and refinements as structured JSON.
Tests	Use validated locators in Playwright instead of brittle hand-authored selectors.
Release signal	Reduce locator-driven noise and improve CI trust.

Locator priority model

1. getByRole(role, { name })
2. getByLabel()
3. getByPlaceholder()
4. getByText()
5. CSS / XPath (last resort, high risk)

Risk model

LOW: unique role + accessible name
MEDIUM: repeated names or dynamic text
HIGH: brittle selectors or fallback-only strategies

Artifact contract

Canonical location	`test-results/locators/`
Locator inventory	`locator-map.json`
Validation results	`locator-validation.json`
Refinement output	`locator-refinements.json`

Recommended structure

/test-results/
  locators/
    locator-map.json
    locator-validation.json
    locator-refinements.json

Critical

These artifacts allow debugging without reruns and power downstream intelligence.

Commands

Discover, validate, refine

# Discover
node scripts/run-locator-extraction.js

# Validate
node scripts/validate-locators.js

# Refine
node scripts/generate-scoped-candidates.js

Operator rule

If a locator is ambiguous, do not guess. Scope it, validate it, or fix accessibility.

Validation outcomes

Valid: use in test
Ambiguous: apply scoped locator refinement
Still failing: fix accessibility or mark as high-risk fallback

Expected outputs

✔ Inventory of interactive elements
✔ Ranked locator candidates
✔ Validation results
✔ Scoped improvements
✔ Reusable test-ready locator data

Failure modes

Multiple matching elements: apply scoping.
Missing accessibility semantics: improve markup before relying on fallback selectors.
Dynamic or unstable text: prefer stronger accessibility-based locators.
Fallback to CSS / XPath: usable but high-risk.

Connection to the intelligence layer

Sprint 14: locator failures become structured artifacts.
Sprint 15: failures are classified as locator vs assertion vs environment.
Sprint 16: the system derives and improves locator candidates.
Sprint 17: release decisions consume validated signal.

Outcome

Locator quality directly impacts release confidence.

Operational value

Removes brittle locator authoring.
Standardizes accessibility-first testing.
Creates reusable intelligence artifacts.
Improves CI signal quality.
Strengthens release confidence.