selector-writing-guide

Verdex Selector Writing Guide: From Exploration to Production-Ready Selectors

A comprehensive guide for writing stable, role-first Playwright selectors using Verdex MCP's progressive disclosure tools.

---

Table of Contents

1. Core Principles
2. The Verdex Workflow
3. The Winning Pattern
4. Tool Usage Guide
5. Real-World Example Walkthrough
6. Common Pitfalls & Solutions
7. Selector Pattern Library
8. Token Efficiency Guidelines
9. Quick Reference

---

Core Principles

✅ Always Follow This Priority Order:

1. Check uniqueness FIRST - If an element is unique on the page, don't over-scope
2. Use Playwright built-in locators - getByRole(), getByTestId(), getByLabel(), etc.
3. Container → Content → Role pattern - Scope to stable containers, filter by content, target by role
4. Minimal chain depth - Keep selector chains ≤ 2-3 levels deep
5. Role-first targeting - Always end with semantic roles when possible

❌ Never Do These:

• ❌ Positional selectors: .nth(0), .first(), .last()
• ❌ Old locator syntax: locator("text=..."), locator("role=...") (use getByText(), getByRole())
• ❌ Parent traversal: .locator('..')
• ❌ Excessive nesting: 4+ level chains like div > div > div > button
• ❌ Class-only selectors: .locator('div.class1.class2.class3')
• ❌ Filter in wrong place: Filtering buttons by text that's in sibling elements

---

The Verdex Workflow

Step-by-Step Process

graph TD
    A[1. browser_navigate] --> B[2. browser_snapshot]
    B --> C{Element Unique?}
    C -->|Yes| D[Use simple selector]
    C -->|No| E[3. resolve_container]
    E --> F{Found stable anchor?}
    F -->|Test ID/Landmark| G[Use as container]
    F -->|Generic divs| H[4. inspect_pattern]
    H --> I[5. extract_anchors if needed]
    I --> G
    G --> J[Generate selector]