debugging-web-selectors

Diagnose broken or ambiguous web selectors and return ranked replacement candidates.

Updated Apr 11, 2026
One-click install
npx skills add https://github.com/celikgo/webmobai --skill debugging-web-selectors-celikgo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debugging-web-selectors
Source: https://github.com/celikgo/webmobai/tree/main/.claude/skills/debugging-web-selectors
Command: npx skills add https://github.com/celikgo/webmobai --skill debugging-web-selectors-celikgo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a Playwright test fails because a selector stopped matching — an element was renamed, the locator matches zero elements, or a strict-mode violation fires because it matches too many — this Skill diagnoses exactly why the locator broke and proposes verified replacement selectors instead of letting the test fail. ## Core Features & Use Cases - Live selector X-ray: Uses webmobai_describe_selector to show the match count and per-match fingerprints (tag, text, role, aria-label, data-testid, position, visibility), splitting the diagnosis into wrong selector, timing race, or ambiguity. - Self-healing triage: Reads the failure payload from webmobai_assert_visible/hidden/text/count, which includes a prior element fingerprint, up to 5 ranked replacement candidates with similarity scores, and a failure-context bundle (URL, title, viewport, console and network errors, screenshot). - Verified fixes: Confirms the winning candidate resolves to exactly one match and passes the original assertion before reporting it. - Use Case: A test fails with "#submit-btn not found" on a checkout page. The Skill navigates to the page, X-rays the selector (0 matches with an id diagnostic), triggers the assertion to surface ranked candidates, and reports that the id was renamed — recommending the stable [data-testid="checkout-submit"] replacement, verified with a passing assert_visible. ## Quick Start Debug why my selector #submit-btn no longer matches on the checkout page and suggest a working replacement.

Frequently Asked Questions about debugging-web-selectors

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

FAQPage Schema
How do I debug a Playwright selector that matches 0 elements?▼

Use webmobai_describe_selector to X-ray the selector live on the page. A 0-match result includes targeted diagnostics for #id and [data-testid] shapes, and you should try a short webmobai_wait_for to rule out a timing race before declaring the selector dead.

How do I fix a strict mode violation caused by an ambiguous locator?▼

Run webmobai_describe_selector to list all matches with their distinguishing attributes, identify the intended element, and build a tighter selector from a stable unique attribute — prefer data-testid, then id, then role plus accessible name — avoiding positional selectors.

How does self-healing selector recovery work in WebMobAI?▼

When assert_visible, assert_hidden, assert_text, or assert_count fails, the response includes a prior element fingerprint and up to 5 ranked replacement candidates with similarity scores. The fingerprint is seeded by a prior successful click or type using the exact same selector string in the session.

Why does the self-healing response show no replacement candidates?▼

Candidates require a prior successful interaction with the exact selector string in the current session, since scoring is computed against that stored fingerprint. Without a snapshot, only the failure-context block is returned, so use describe_selector to build a replacement manually.

Can self-healing suggest replacements for plain div or span elements?▼

No. Candidate scoring only walks interactive-ish elements: a, button, input, select, textarea, [role], [data-testid], and [tabindex]. For plain divs or spans, use describe_selector's live match list to construct the replacement yourself.

When should I not treat an element-not-found failure as a selector problem?▼

Check the failure-context Current URL first — a silent redirect to a login page means the session expired, not the selector. Also, a HIDDEN (0x0) fingerprint indicates a visibility bug, and a blank page calls for a smoke test rather than selector debugging.