selector-development

Adds a single inert test attribute to frontend elements lacking stable selectors for e2e tests.

5|2|Updated May 19, 2026
One-click install
npx skills add https://github.com/civitas-cerebrum/achilles --skill selector-development-civitas-cerebrum
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: selector-development
Source: https://github.com/civitas-cerebrum/achilles/tree/main/skills/selector-development
Command: npx skills add https://github.com/civitas-cerebrum/achilles --skill selector-development-civitas-cerebrum

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? End-to-end tests break when elements lack stable selectors, forcing fragile locators based on copy, CSS classes, or DOM position. This Skill closes that gap by adding one inert test attribute (data-testid or the project's detected convention) to the offending element and proving the change has zero functional or visual impact before resuming test authoring. ## Core Features & Use Cases - JIT mode: Instruments exactly one element with one attribute in one round-trip, triggered from Stage 2 inspection escalation, failure-diagnosis of fragile selectors, or a direct user request. - Audit mode: Iterates the journey map page-by-page to instrument every interactive or asserted node lacking a stable selector, with a ledger for deduplication and resumption. - 8-step guardrail pipeline: Enforces before/after screenshots, typecheck, unit tests, e2e run, visual diff (0-pixel threshold), and commit via hook-gated receipts, with automatic revert on any failure. - Use Case: A Playwright spec fails because the checkout button has no stable locator. The Skill appends data-testid="submit-button" to the button's opening tag, runs the full guardrail pipeline, commits the change, and returns control to the test-authoring workflow. ## Quick Start Ask the agent to add a stable selector to the checkout button so the failing e2e spec can target it reliably.

Frequently Asked Questions about selector-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add stable selectors to elements for Playwright e2e tests?

Invoke the skill with a request like "add stable selectors to the cart drawer". It appends one inert attribute such as data-testid to the target element's opening tag, then validates the change through typecheck, unit tests, e2e, and a visual diff before committing.

What test attribute does the skill add to frontend elements?

It detects the project's existing convention by scanning the frontend source once per session. If data-testid already appears it uses that; otherwise it matches the most frequent of data-cy, data-qa, or data-test, defaulting to data-testid.

Can I audit selectors across an entire application at once?

Yes, Audit mode instruments all pages by iterating the journey map, but it requires a complete sentinel-bearing tests/e2e/docs/journey-map.md. It is opt-in via phrases like "audit selectors across the app" and uses a ledger for deduplication and resumption.

Does selector instrumentation work when tests live in a separate repo?

No. The workspace gate requires both frontend source and tests/e2e/ with at least one *.spec.ts file in the same workspace. Cross-repo or monorepo cross-package instrumentation is explicitly out of scope.

What happens if adding the attribute breaks a test or changes the UI?

Any guardrail failure in typecheck, unit tests, e2e, or the visual diff triggers an automatic revert via git checkout, deletes the receipt, and returns status blocked with the failing artifact path. The pipeline never commits a non-inert change.

Why does the skill refuse to instrument some elements?

It declines when the element already has a stable selector, when a third-party component strips unknown props, or when the change would require structural modification. In these cases it returns status blocked or skipped rather than improvising a wrapper or broader edit.