@sun-asterisk/sungen 2.3.1 → 2.4.0

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

@@ -1,287 +1,140 @@
 ---
 name: sungen-selector-fix
-description: 'Selector generation and fixing strategy for make-test — explores live page, generates selectors.yaml, auto-fixes on test failure. Use this when generating selectors.yaml from a live page or fixing failing selectors.'
+description: 'Selector generation and fixing strategy — explore live page, generate selectors.yaml, validate, auto-fix. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## Selector Generation & Fix Strategy
+## When to Generate
 
-### When to Generate Selectors
-
-Selectors are generated during `/sungen:make-test`, NOT during `/sungen:make-tc`. This ensures selectors are always validated against the live page.
+Selectors are generated during `/sungen:run-test`, NOT during `/sungen:create-test`.
 
 ---
 
-### Step 1: Authenticate
+## Step 1: Authenticate & Snapshot
 
 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`
+3. If redirected to login → ask user to log in manually via MCP browser
+4. Navigate to target page → `browser_snapshot`
 
-**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).
+**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
 
 ---
 
-### Step 2: Build an Element Catalog from the Snapshot
-
-**Never guess or infer selector names from Gherkin labels. Always copy exact values from the snapshot.**
+## Step 2: Build Element Catalog
 
-After taking the snapshot, mentally catalog ALL accessible elements:
+**Never guess names from Gherkin labels. Copy exact values from snapshot.**
 
-- **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)
+Catalog all accessible elements from snapshot: buttons, links, headings, inputs, regions, images.
 
-Then check for `data-testid` attributes (more stable than accessible names):
+Then check for `data-testid` attributes:
 ```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) }))
 ```
 
 ---
 
-### Step 3: Map Gherkin Labels → Selectors
+## Step 3: Map Gherkin Labels → Selectors
 
-For each `[Reference]` in the `.feature` file, find the best match in the element catalog.
+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.
-
-```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'
-```
-
-#### When there is no accessible name
-
-Use a `locator` with a CSS attribute selector or ARIA role:
+**Exact name rule**: copy name character-for-character from snapshot. Never infer from Gherkin label.
 
+**No accessible name**: use `locator` with CSS/ARIA attribute:
 ```yaml
 search field:
   type: 'locator'
   value: '[role="searchbox"]'
-
-icon button:
-  type: 'locator'
-  value: '[aria-label="Close"]'
 ```
 
----
-
-### Step 4: Handle Dynamic Content
-
-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.
-
-```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:
-  type: 'role'
-  value: 'heading'
-  nth: 1    # skip page-level headings, get first card heading
+**Dynamic content**: never use `type: text` with specific value. Use `testid` or structural `role` + `nth`.
 
-# BEST — if the app has data-testid
-card title:
-  type: 'testid'
-  value: 'card-title'
-```
+**Multiple matches**: add `nth: 0` for first occurrence.
 
-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).
+Auto-infer rules and lookup priority → see `sungen-selector-keys` skill.
 
 ---
 
-### Step 4b: Handle Detail Screens with Dynamic IDs
+## Step 4: Table Selectors
 
-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 table patterns using the v2.3 syntax, generate table selectors with `columns` config:
 
 ```yaml
-# selectors.yaml — full path with real ID
-user detail:
-  type: 'page'
-  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
+users:
+  type: 'role'
+  value: 'table'
+  name: 'Users'
+  columns:
+    username:
+      index: 0
+      header: 'Username'
+    email:
+      index: 1
+      header: 'Email'
+    status:
+      index: 2
+      header: 'Status'
 ```
 
-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
+**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.
 
-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:
+**Why**: enables exact cell assertion via `cell.nth(index).toHaveText(value)` instead of approximate `cell.filter({ hasText })`.
 
+**Row scope Gherkin** — these patterns use the table selector:
 ```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
-  ...
+Then User see [Username] row in [Users] table with {{user_name}}
+Then User see [Status] column with {{expected_status}}
+When User click [Edit] button in [Users] table with {{user_name}}
 ```
 
-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)
+## Step 5: Detail Screens with Dynamic IDs
 
-When an element appears more than once (e.g. desktop + mobile nav, repeated list items), add `nth`:
+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
-nav link:
-  type: 'role'
-  value: 'link'
-  name: 'Dashboard'
-  nth: 0    # first occurrence (desktop nav)
+user detail:
+  type: 'page'
+  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
 ```
 
-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
+## Step 6: Validate Before Running
 
----
-
-### 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:
+**Fix 80%+ of selector issues before first test run.**
 
-#### How to validate
+After generating `selectors.yaml`, verify each entry against the live snapshot:
+- `role` + `name` → search snapshot for `role "name"`
+- `testid` → `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')`
+- `placeholder` → search snapshot for textbox with placeholder
+- `page` → verify URL path exists
 
-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
-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 the element exists in the snapshot
-4. Fix mismatches immediately — no test run needed
-
-#### 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')` |
-
-**Target: fix 80%+ of selector issues before the first test run.**
+Common fixes: name mismatch → copy from snapshot, element in iframe → add `frame`, multiple matches → add `nth` or `exact: true`.
 
 ---
 
-### Batched Test Execution
+## Step 7: Run & Fix Loop
 
-After proactive validation, run tests in **batches of 20** for faster feedback:
+Run tests in batches of 20. Group failures by root cause (same selector, same error type). Fix once, verify batch, move to next.
 
 ```
-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, re-run only failing tests from this batch
-     d. If fixed → move to next batch
-
-4. NEXT BATCH — repeat with next 20 tests
-
-5. FINAL CONFIRMATION — run ALL tests once:
-     npx playwright test <spec> --reporter=line
-
-6. If still failing after 5 fix attempts per batch → ask user about direct .spec.ts fix
+compile → batch run 20 → fix root cause → recompile → re-run failures → next batch
 ```
 
-#### Grouping failures by root cause
-
-Common patterns where 1 fix resolves many failures:
-- **Same selector** — e.g., all `[Email Error]` tests fail → fix 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.
-
----
-
-### Key Rules (from sungen-selector-keys)
+After all batches pass → 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 5 attempts per batch → ask user about direct `.spec.ts` fix.