@sun-asterisk/sungen 2.3.1 → 2.4.1

package/dist/orchestrator/templates/ai-instructions/claude-skill-selector-fix.md

@@ -1,312 +1,125 @@
 ---
 name: sungen-selector-fix
-description: 'Selector generation and fixing strategy for make-test — explores live page, generates selectors.yaml, auto-fixes on test failure. Auto-loaded by make-test command.'
+description: 'Selector fixing strategy — diagnose failures, explore live page targeted, fix broken selectors. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## Selector Generation & Fix Strategy
+## Strategy: Fix Only What Breaks
 
-### When to Generate Selectors
+Most selectors auto-infer from Gherkin element types (see `sungen-selector-keys` skill). Only add YAML entries for selectors that fail during test execution.
 
-Selectors are generated during `/sungen:make-test`, NOT during `/sungen:make-tc`. This ensures selectors are always validated against the live page.
+**Minimal `selectors.yaml`**: page selectors (required), overrides for elements where auto-infer doesn't work. Never generate a full page catalog upfront.
 
 ---
 
-### Step 1: Authenticate
+## Step 1: Diagnose Failures
 
-1. Read `baseURL` from `playwright.config.ts`
-2. `browser_navigate` to `baseURL`
-3. If redirected to login, ask the user to log in manually:
-   > "This page requires login. Please log in using the browser. Confirm when you're done."
-4. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+Parse Playwright error output to categorize failures:
 
-**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
-**Never use `browser_evaluate` to inject cookies or localStorage.** Use `browser_evaluate` only to read DOM info (e.g. detect `data-testid` attributes, check element properties).
+| Error pattern | Root cause | Fix target |
+|---|---|---|
+| `No element found` / `strict mode violation` | Selector mismatch | `selectors.yaml` |
+| `toBeVisible` timeout | Wrong name or missing element | `selectors.yaml` |
+| `toHaveText` / `toHaveValue` mismatch | Wrong expected data | `test-data.yaml` |
+| `page.goto` error | Wrong URL | page selector in `selectors.yaml` |
+| `frame` error | Element inside iframe | add `frame` field |
 
----
+**Group by root cause** — if 5 tests fail because `[Submit]` button has a different name, that's 1 fix, not 5.
 
-### Step 2: Build an Element Catalog from the Snapshot
+**Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
-**Never guess or infer selector names from Gherkin labels. Always copy exact values from the snapshot.**
+---
 
-After taking the snapshot, mentally catalog ALL accessible elements:
+## Step 2: Targeted MCP Exploration
 
-- **Buttons**: list each `button "..."` with its exact accessible name
-- **Links**: list each `link "..."` with its exact accessible name
-- **Headings**: list each `heading "..."` with level and exact name
-- **Inputs**: list each `textbox`, `searchbox`, `combobox` — note if it has an accessible name or not
-- **Regions/landmarks**: `region "..."`, `navigation "..."`, `dialog "..."`
-- **Images**: `img "..."` with accessible name (alt text)
+Only when `test-results/` screenshots are insufficient:
 
-Then check for `data-testid` attributes (more stable than accessible names):
-```js
-// browser_evaluate — read-only, safe:
-Array.from(document.querySelectorAll('[data-testid]'))
-  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
-```
+1. Read `baseURL` from `playwright.config.ts`
+2. `browser_navigate` to target page
+3. If redirected to login → ask user to log in manually via MCP browser
+4. Take **ONE** `browser_snapshot` — fix all broken selectors from this single snapshot
+
+**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
 
 ---
 
-### Step 3: Map Gherkin Labels → Selectors
+## Step 3: Fix Broken Selectors
 
-For each `[Reference]` in the `.feature` file, find the best match in the element catalog.
+For each failed selector, find the correct locator from the snapshot:
 
-#### Selector priority (use first applicable)
+Selector priority (use first applicable):
 
-| Priority | type | When to use |
+| Priority | type | When |
 |---|---|---|
-| 1 | `testid` | `data-testid` attribute exists |
-| 2 | `role` + exact name | Interactive elements (button, link, heading) |
-| 3 | `placeholder` | Input with visible placeholder text |
-| 4 | `label` | Form field with `<label>` association |
-| 5 | `locator` (CSS / aria attr) | No accessible name (e.g. bare searchbox, icon button) |
-| 6 | `text` | Static text only — avoid for dynamic/data-driven content |
-
-#### The exact name rule
+| 1 | `testid` | `data-testid` exists |
+| 2 | `role` + exact name | Interactive elements |
+| 3 | `placeholder` | Input with placeholder |
+| 4 | `label` | Form field with `<label>` |
+| 5 | `locator` (CSS) | No accessible name |
+| 6 | `text` | Static text only |
 
-Copy the accessible name **character-for-character** from the snapshot. Do not transform, translate, or infer from the Gherkin label.
+**Exact name rule**: copy name character-for-character from snapshot. Never infer from Gherkin label.
 
-```yaml
-# BAD — name inferred from Gherkin label, not from snapshot
-notification bell:
-  type: 'role'
-  value: 'button'
-  name: 'Notification Bell'
-
-# GOOD — exact name from snapshot: button "Notifications"
-notification bell:
-  type: 'role'
-  value: 'button'
-  name: 'Notifications'
+Check for `data-testid` attributes if role-based matching fails:
+```js
+Array.from(document.querySelectorAll('[data-testid]'))
+  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
 ```
 
-#### When there is no accessible name
-
-Use a `locator` with a CSS attribute selector or ARIA role:
-
-```yaml
-search field:
-  type: 'locator'
-  value: '[role="searchbox"]'
-
-icon button:
-  type: 'locator'
-  value: '[aria-label="Close"]'
-```
+Common fixes:
+- Name mismatch → copy exact name from snapshot
+- Multiple matches → add `nth` or `exact: true`
+- No accessible name → use `testid` or `locator` (CSS)
+- Element in iframe → add `frame` field
+- Dynamic content → use `testid` or structural `role` + `nth`
 
 ---
 
-### Step 4: Handle Dynamic Content
+## Step 4: Table Selectors
 
-For elements whose text changes between test runs (list items, card data, user-generated content, timestamps):
-
-**Never use `type: text` with a specific value** — it breaks when data changes.
+For table patterns, add table selectors with `columns` config:
 
 ```yaml
-# BAD — specific text breaks when data changes
-card title:
-  type: 'text'
-  value: 'Some specific title'
-
-# GOOD — structural: first heading inside a card container
-card title:
+users:
   type: 'role'
-  value: 'heading'
-  nth: 1    # skip page-level headings, get first card heading
-
-# BEST — if the app has data-testid
-card title:
-  type: 'testid'
-  value: 'card-title'
+  value: 'table'
+  name: 'Users'
+  columns:
+    username:
+      index: 0
+      header: 'Username'
+    email:
+      index: 1
+      header: 'Email'
+    status:
+      index: 2
+      header: 'Status'
 ```
 
-To determine the correct `nth` offset, count how many matching elements appear before the target in the snapshot (e.g. how many headings come before the first card heading).
+**How to build `columns`**: count column headers in snapshot (left to right, 0-indexed). Map each `[Col] column` reference from feature file to its index.
 
 ---
 
-### Step 4b: Handle Detail Screens with Dynamic IDs
+## Step 5: Detail Screens with Dynamic IDs
 
-For screens like `/admin/users/:id` or `/products/:slug`:
-1. Navigate to the **list page** first via MCP browser to find a real record ID
-2. Use that ID in the page selector value
-3. Use `User is on [X] page` — sungen resolves the path from the selector
+For screens like `/admin/users/:id`:
+1. Navigate to list page via MCP to find a real record ID
+2. Hardcode the ID in page selector
 
 ```yaml
-# selectors.yaml — full path with real ID
 user detail:
   type: 'page'
   value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
 ```
 
-Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
-
----
-
-### Step 5: Handle SPA / Client-side Routing
-
-Many modern apps (Next.js, Nuxt, SvelteKit, etc.) return the same HTML shell for all URLs and route client-side. `domcontentloaded` fires on the shell before the target page renders.
-
-**Symptom**: Tests see a different page than expected (e.g. home page instead of `/dashboard`).
-
-**Fix in the feature file**: Add an explicit assertion after navigation to confirm the correct page has loaded before proceeding:
-
-```gherkin
-Scenario: VP-UI-001 Some test
-  Given User is on [Dashboard] page
-  Then User see [Dashboard Title] heading is visible   ← confirms page loaded
-  When User click [Some Button] button
-  ...
-```
-
-The "page loaded" check should use a **stable, always-visible element** on that specific page — typically the main page heading.
-
----
-
-### Step 6: Handle Multiple Matches (strict mode)
-
-When an element appears more than once (e.g. desktop + mobile nav, repeated list items), add `nth`:
-
-```yaml
-nav link:
-  type: 'role'
-  value: 'link'
-  name: 'Dashboard'
-  nth: 0    # first occurrence (desktop nav)
-```
-
-Use `nth: 0` for the first match of dynamic/repeated elements.
-
----
-
-### Auto-Infer (skip YAML entry)
-
-Many elements don't need a YAML entry — sungen auto-infers from the Gherkin label:
-
-| Gherkin | Auto-inferred locator |
-|---|---|
-| `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
-| `[Home] link` | `getByRole('link', { name: 'Home' })` |
-| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
-| `[Email] field` | `getByPlaceholder('Email')` |
-| `[Success] text` / `message` / `label` | `getByText('Success')` |
-| `[Terms] checkbox` | `getByRole('checkbox', { name: 'Terms' })` |
-| `[Global] search` | `getByRole('searchbox', { name: 'Global' })` |
-| `[Vietnam] option` | `getByRole('option', { name: 'Vietnam' })` |
-| `[Price] slider` | `getByRole('slider', { name: 'Price' })` |
-| `[Notification] toggle` | `getByRole('switch', { name: 'Notification' })` |
-| `[Profile] tab` | `getByRole('tab', { name: 'Profile' })` |
-| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
-
-**Only add a YAML entry when auto-infer won't work:**
-- The accessible name differs from the Gherkin label
-- Needs `nth` to disambiguate
-- Needs `testid` or CSS locator
-- Is dynamic content (needs structural selector)
-- Is a bare input with no label or placeholder
-
----
-
-### Proactive Selector Validation (before running tests)
-
-**Most failures are selector mismatches.** Validate selectors against the live page BEFORE running any test — this eliminates slow compile→run→read→fix cycles.
-
-After generating `selectors.yaml` (Step 3), verify each entry:
-
-#### How to validate
-
-Use `browser_evaluate` to check if each selector actually finds an element on the page:
-
-```js
-// Validate a role selector
-document.querySelectorAll('[role="button"]').length;
-// or check accessible name exists
-Array.from(document.querySelectorAll('button'))
-  .filter(el => el.textContent.includes('Submit') || el.getAttribute('aria-label')?.includes('Submit'))
-  .length;
-```
-
-Or use `browser_snapshot` and cross-check:
-1. Read all `[Reference]` entries from `selectors.yaml`
-2. Take a `browser_snapshot`
-3. For each entry, verify:
-   - **role + name**: does the snapshot contain `button "Submit"` or `link "Home"`?
-   - **testid**: does `browser_evaluate` find `[data-testid="xxx"]`?
-   - **placeholder**: does the snapshot contain a textbox with that placeholder?
-   - **locator**: does `browser_evaluate` find `document.querySelector('xxx')`?
-4. Fix mismatches immediately — no need to run tests
-
-#### What to check
-
-| Selector type | Validation method |
-|---|---|
-| `role` + `name` | Search snapshot for `role "name"` text |
-| `testid` | `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')` |
-| `placeholder` | Search snapshot for textbox with placeholder |
-| `locator` (CSS) | `browser_evaluate`: `document.querySelector('xxx')` |
-| `page` | Verify URL path exists (navigate and check) |
-
-#### Common proactive fixes
-
-- Name mismatch → copy exact name from snapshot
-- Element not found → check if element is inside iframe/dialog (needs `frame` or scope)
-- Multiple matches → add `nth: 0` or `exact: true`
-- No accessible name → switch to `testid` or `locator`
-
-**Target: fix 80%+ of selector issues before the first test run.**
-
 ---
 
-### Batched Test Execution
-
-After proactive validation, run tests in **batches of 20** for faster feedback:
-
-```
-1. COMPILE — sungen generate --screen <screen>
-
-2. BATCH RUN — run 20 tests at a time:
-     npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|...|VP-UI-020" --reporter=line
-
-3. IF FAILURES in batch:
-     a. Group failures by root cause (same selector, same error type)
-     b. Fix selectors.yaml or test-data.yaml
-     c. Recompile: sungen generate --screen <screen>
-     d. Re-run ONLY the failing tests from this batch
-     e. If fixed → move to next batch
-
-4. NEXT BATCH — repeat with next 20 tests (VP-UI-021...VP-UI-040)
-
-5. FINAL CONFIRMATION — after all batches pass, run ALL tests once:
-     npx playwright test <spec> --reporter=line
-     This catches regressions from selector changes.
-
-6. If still failing after 5 fix attempts per batch → ask user about direct .spec.ts fix
-```
-
-#### Building batch `--grep` patterns
-
-Extract scenario names and batch them:
-```bash
-# Batch 1: first 20
-npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|...|VP-UI-020" --reporter=line
-
-# Batch 2: next 20
-npx playwright test <spec> --grep "VP-VAL-001|VP-VAL-002|...|VP-VAL-020" --reporter=line
-```
-
-#### Grouping failures by root cause
-
-Common patterns where 1 fix resolves many failures:
-- **Same selector** — e.g., all `[Email Error]` tests fail → fix `email error` in selectors.yaml once
-- **Same error type** — e.g., all `strict mode violation` → add `exact: true` or `nth`
-- **Same assertion** — e.g., all `toHaveText` on inputs fail → change Gherkin pattern
-
-Fix the root cause first, verify with the batch, then move on.
-
----
+## Step 6: Fix Loop
 
-### Key Rules (from sungen-selector-keys)
+After fixing selectors:
+1. Recompile: `sungen generate --screen <screen>`
+2. Re-run only failing tests: `npx playwright test --grep "VP-XXX-001|VP-XXX-002" --reporter=line`
+3. If new failures → repeat (max 3 attempts)
+4. After all fixes → run ALL tests once for regression check
 
-- `[Reference]` → lowercase, keep Unicode: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
-- Keys use **spaces** (not dots) as word separators
-- Same label, different element types → add `--type` suffix
-- Same label, nth occurrence → add `--N` suffix
+If still failing after 3 attempts → ask user for guidance.