@sun-asterisk/sungen 2.3.1 → 2.4.0

package/dist/orchestrator/templates/ai-instructions/claude-skill-error-mapping.md

@@ -1,69 +1,145 @@
 ---
 name: sungen-error-mapping
-description: 'Playwright and Sungen error to fix mapping. Auto-loaded when running or debugging tests.'
+description: 'Error diagnosis and fix strategy — systematic debugging flow, error patterns, fix priorities. Auto-loaded during run-test.'
 user-invocable: false
 ---
 
-## Playwright Errors → Fix
+## Diagnosis Flow (before fixing anything)
 
-| Error | Fix |
-|---|---|
-| strict mode violation | add `nth`, `exact: true`, or specific `name` in selectors.yaml |
-| Element is not an input | change `type` or `value` in selectors.yaml |
-| Timeout waiting for selector | fix `type`/`value`/`name` to match element in selectors.yaml |
-| toBeVisible Timeout | verify accessible name or use `testid` in selectors.yaml |
-| toHaveText mismatch | fix expected text in `test-data.yaml` — OR if element is an input (field/textarea/search/dropdown), change Gherkin type so compiler uses `toHaveValue` instead |
-| toHaveValue mismatch | fix expected value in `test-data.yaml` — this is for input elements (field, textarea, search, dropdown, slider, date-picker) |
-| toContainText mismatch | fix expected partial text in `test-data.yaml` |
-| Navigation failed | fix page `value` path in selectors.yaml |
-| not a select | set `variant: 'custom'` in selectors.yaml |
-| Frame not found | fix `frame` value in selectors.yaml |
-| dialog was dismissed | alert step is AFTER the trigger — move `click [OK] alert` BEFORE the button click that opens the dialog |
-| page.once('dialog') never fired | no browser dialog appeared — check if the action actually triggers a `window.alert/confirm/prompt`, not a CSS modal |
-
-### Assertion type mismatch (toHaveText vs toHaveValue)
-
-Sungen picks the assertion based on element type:
-- **Input types** (`field`, `textarea`, `search`, `dropdown`, `slider`, `date-picker`) → `toHaveValue()`
-- **Text types** (everything else: `message`, `header`, `label`, `row`, etc.) → `toHaveText()`
-- **Partial match** (uses `contains` keyword) → `toContainText()`
-
-If you see `toHaveText` failing on an input element, the Gherkin step has the wrong target type. Fix: change the target type in the `.feature` file (e.g., `see [Email] message with {{v}}` → `see [Email] field with {{v}}`).
-
-## Auth Errors → Fix
+**Step 1: Read the error** — extract: error type, element name, expected vs actual, file:line.
 
-| Symptom | Fix |
-|---|---|
-| Tests redirect to login page | `specs/.auth/<role>.json` missing or expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
-| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` to create auth state |
-| Most tests timeout on first step | Auth expired — re-run `sungen makeauth <role> --url <baseURL>` |
-| Page shows home/login instead of target | SPA routing + expired auth. Re-run `sungen makeauth`, add `wait for` step after navigation |
+**Step 2: Read error context** — check `test-results/` for the snapshot at failure time. This shows the exact page state when the test failed — more reliable than re-navigating with MCP.
+
+**Step 3: Compare** — match the failing selector against the snapshot. Ask:
+- Does the element exist on the page?
+- Does the accessible name match exactly?
+- Are there multiple matches (strict mode)?
+- Is the element inside an iframe or dialog?
+- Is the page in the expected state (correct URL, loaded)?
+
+Then choose the fix from the patterns below.
+
+---
+
+## Fix Priority (try in order)
+
+1. **Auth issue** — page redirected to login? Fix auth first, everything else is noise
+2. **Element not found** — wrong name/type/value in selectors.yaml. Re-snapshot, copy exact name
+3. **Multiple matches** — add `nth`, `exact: true`, or `scope` to narrow down
+4. **Wrong assertion** — `toHaveText` vs `toHaveValue` mismatch, wrong expected data
+5. **Timing** — SPA not loaded, async content. Add `wait for` step in .feature
+
+---
+
+## Playwright Errors
+
+### Selector errors → fix in `selectors.yaml`
+
+| Error | Diagnosis | Fix |
+|---|---|---|
+| strict mode violation | Multiple elements match | Add `nth: 0`, `exact: true`, or more specific `name` |
+| Timeout / not found | Element doesn't exist or name wrong | Re-snapshot → copy exact accessible name. Check iframe/dialog scope |
+| Element is not an input | Wrong element type targeted | Change `type` or `value` to match actual element |
+| not a select | Custom dropdown, not native `<select>` | Set `variant: 'custom'` |
+| Frame not found | iframe selector wrong or doesn't exist | Fix `frame` value, verify iframe in snapshot |
+
+### Assertion errors → fix in `test-data.yaml` or `.feature`
+
+| Error | Diagnosis | Fix |
+|---|---|---|
+| toHaveText mismatch | Expected text differs from actual | Fix value in test-data. If element is input type → change Gherkin type to `field`/`textarea` (triggers `toHaveValue` instead) |
+| toHaveValue mismatch | Expected value differs from actual | Fix value in test-data |
+| toContainText mismatch | Partial text not found | Fix expected partial text in test-data |
+| toBeVisible timeout | Element exists but hidden, or name wrong | Check: is element conditionally visible? Wrong name? Inside dialog? |
+| toHaveCount mismatch | Row count differs | Fix expected count in test-data. Verify: is table loaded? Filtered? |
 
-**Never run `sungen makeauth` yourself.** Always tell the user to run it manually.
+### Assertion type rule
 
-## Performance Errors → Fix (specs/base.ts)
+Sungen picks assertion based on element type:
+- **Input** (`field`, `textarea`, `search`, `dropdown`, `slider`) → `toHaveValue()`
+- **Text** (everything else: `message`, `heading`, `label`, `row`) → `toHaveText()`
+- **Partial** (`contains` keyword) → `toContainText()`
 
-All generated `.spec.ts` files import from `specs/base.ts`. This shared file handles context caching, navigation skip, and overlay cleanup.
+If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fix: change type in `.feature`.
 
-| Symptom | Fix in `specs/base.ts` |
+---
+
+## Table-Specific Errors
+
+| Error | Diagnosis | Fix |
+|---|---|---|
+| `tableRow is not defined` | Column assertion without preceding row scope step | Add `User see [Ref] row in [Table] table with {{v}}` before `User see [Col] column with {{v}}` |
+| `toHaveText` on cell fails (with columns) | Wrong column index in `columns` config | Re-count columns in snapshot (0-indexed). Fix `index` in selectors.yaml |
+| `toBeVisible` on cell fails (no columns) | `filter({ hasText })` didn't match | Check exact cell text in snapshot. Fix value in test-data |
+| Row filter matches 0 rows | Filter text doesn't match any row content | Re-snapshot → find actual row text. Fix filter value in test-data |
+| Row filter matches multiple rows | Filter text is too generic (matches multiple rows) | Use more specific filter text (unique identifier like email, ID) |
+| Table not found | Wrong table name or table not rendered | Re-snapshot → copy exact table accessible name |
+
+---
+
+## Auth Errors
+
+| Symptom | Fix |
 |---|---|
-| Server returns 429 (rate limited) | Context caching broken — check `contextCache` Map reuses sessions per `storageState` |
-| Tests slow even with `--workers=1` | Navigation skip not working — check `goto` patch compares `currentPath === url` |
-| Previous test's modal blocks next test | Overlay cleanup insufficient — improve Escape/click dismiss logic |
-| All tests fail on first navigation | `page.url()` is `about:blank` — check try/catch in goto patch |
-| Multiple session invalidation errors | Too many contexts created — ensure `contextCache.get(cacheKey)` returns existing context |
+| Redirect to login page | Auth expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
+| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` |
+| Most tests timeout on first step | Auth expired — re-run makeauth |
+| Page shows home instead of target | SPA + expired auth. Re-run makeauth + add `wait for` step |
 
-**Rules:**
-- `base.ts` changes affect ALL tests — edit carefully
-- Small project-specific tweaks are OK (e.g., custom overlay dismiss, timeout tuning, extra wait logic)
-- Do NOT move individual selector/data fixes into `base.ts` — those belong in `selectors.yaml` / `test-data.yaml`
-- If unsure whether a fix belongs in `base.ts` or selectors, ask the user
+**Never run `sungen makeauth` yourself.** Tell the user.
 
-## Sungen Errors → Fix
+---
+
+## Sungen Compile Errors
 
 | Error | Fix |
 |---|---|
-| Unknown step pattern | rewrite `.feature` step to match supported pattern |
-| Missing selector | add key to `selectors.yaml` |
-| Missing variable | add key to `test-data.yaml` |
-| Invalid selector type | use: role/testid/placeholder/label/text/locator/page/upload/frame |
+| Unknown step pattern | Rewrite step to match `sungen-gherkin-syntax` patterns |
+| Missing selector | Add key to `selectors.yaml` |
+| Missing variable | Add key to `test-data.yaml` |
+| Invalid selector type | Use: role/testid/placeholder/label/text/locator/page/upload/frame |
+
+---
+
+## Performance & Infrastructure Errors → Fix in `specs/base.ts`
+
+All generated `.spec.ts` import from `specs/base.ts` — shared context caching, navigation, overlay cleanup. AI **can and should** tune `base.ts` to match the project.
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| Server 429 (rate limited) | Too many browser contexts | Fix `contextCache` to reuse sessions per `storageState` |
+| Tests slow with `--workers=1` | Redundant navigation | Fix goto patch: skip if `currentPath === url` |
+| Previous test's modal blocks next | Overlay not cleaned up | Add/improve Escape + backdrop click in cleanup hook |
+| All tests fail on first navigation | `page.url()` is `about:blank` | Add try/catch in goto patch |
+| Flaky timeouts on SPA pages | Default timeout too short for app | Increase `actionTimeout` / `navigationTimeout` |
+| Tests pass individually but fail in batch | Shared state leaking between tests | Isolate context per test or reset state in `beforeEach` |
+
+### What AI CAN fix in `base.ts`
+
+- Timeout tuning (increase for slow APIs, decrease for fast apps)
+- Custom overlay/modal dismiss logic (project has unique close patterns)
+- Navigation wait strategy (`networkidle` vs `domcontentloaded` vs custom)
+- Context caching strategy (per-role, per-session)
+- Cookie/localStorage cleanup between tests
+
+### What AI should NOT move into `base.ts`
+
+- Individual selector fixes → belong in `selectors.yaml`
+- Test data values → belong in `test-data.yaml`
+- Single-test workarounds → belong in the `.spec.ts` directly
+
+---
+
+## Smart Fix Strategy
+
+### When multiple tests fail on the same element
+Fix the **root cause once** — don't fix each test individually. Group by selector key, fix selectors.yaml, recompile, re-run batch.
+
+### When you're unsure about the fix
+**Re-snapshot** — `browser_navigate` to the failing page, take `browser_snapshot`, compare the live state against what the test expects. This is faster than guessing.
+
+### When the fix might break other tests
+After fixing selectors.yaml, run ALL tests (not just the failing one) to catch regressions from renamed/changed selectors.
+
+### When nothing works after 3 attempts
+Ask the user. The issue might be: dynamic content, race condition, environment-specific state, or a real application bug.

package/dist/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -33,7 +33,6 @@ AND    →  inherits from preceding keyword
 User is on [T] page                              # navigate to page
 User is on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
 User is on [T] dialog                            # enter dialog scope
-User is logged in | is not logged in              # auth state
 ```
 
 ### Form
@@ -155,29 +154,16 @@ User see [T] page                                # URL assertion
 ### Table
 
 ```
-User see [Col] column in [Table] table           # column exists (parent scoping)
-User see [Table] table row with {{f}}            # row exists
-User see [Table] table has no row with {{f}}     # row not exists
-User see [Table] table with {{count}} rows       # row count
-User see [Table] table is empty                  # empty table
-User see [Table] table row with {{f}} has [Col] with {{v}}  # cell by filter
-User see [Table] table row 1 [Col] cell with {{v}}          # cell by index
-User click [Act] in [Table] table row with {{f}}             # action in row
+User see [Col] column in [Table] table                          # column exists
+User see [Ref] row in [Table] table with {{v}}                  # row exists (enters row scope)
+User see [Ref] row in [Table] table with {{v}} is hidden        # row hidden
+User see [Table] table with {{count}}                           # row count
+User see [Table] table is empty                                 # empty table
+User see [Col] column with {{v}}                                # cell value (row scoped)
+User click [Act] button in [Table] table with {{v}}             # action in row
 ```
 
-### Parent Scoping (disambiguation)
-
-```
-User click [Submit] button in [User Info] form           # button inside specific form
-User fill [Email] field in [Registration] form with {{v}} # field inside specific form
-User see [Total] text in [Summary] section with {{v}}    # text inside specific section
-User click [Delete] button in [Active Users] table       # button inside specific table
-```
-
-- **Optional** — only use when page has 2+ similar UI blocks
-- **Valid parent types**: `table`, `list`, `section`, `dialog`, `form`
-- **Max 2 levels**: `[Target] in [Parent]`. **NEVER** nest 3 levels: `[A] in [B] in [C]`
-- Parent resolves from selectors YAML first, falls back to auto-infer `getByRole(parentType, { name })`
+Row scope: `see [Ref] row in [Table] table with {{v}}` defines `tableRow`. Subsequent `see [Col] column with {{v}}` checks the cell in that row. With `columns` config → exact `nth(index)`, without → `filter({ hasText })`.
 
 ### States
 
@@ -196,24 +182,7 @@ User click [Delete] button in [Active Users] table       # button inside specifi
 
 ### Auto-infer (no YAML entry needed)
 
-| Gherkin | Playwright 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' })` |
-| `[Male] radio` | `getByRole('radio', { name: 'Male' })` |
-| `[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' })` |
-| `[Orders] table` | `getByRole('table', { name: 'Orders' })` |
-| `[Products] list` | `getByRole('list', { name: 'Products' })` |
-| `[Name] column` | `getByRole('columnheader', { name: 'Name' })` |
-| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
+Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label' })`. Only add YAML when the accessible name differs, needs `nth`, or needs `testid`. Full auto-infer table → see `sungen-selector-keys` skill.
 
 ## YAML Keys
 

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

@@ -1,312 +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. Auto-loaded by make-test command.'
+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
-
-For each `[Reference]` in the `.feature` file, find the best match in the element catalog.
+## Step 3: Map Gherkin Labels → Selectors
 
-#### 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 |
+| 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 |
 
-#### The exact name rule
-
-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
+**Dynamic content**: never use `type: text` with specific value. Use `testid` or structural `role` + `nth`.
 
-For elements whose text changes between test runs (list items, card data, user-generated content, timestamps):
+**Multiple matches**: add `nth: 0` for first occurrence.
 
-**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
-
-# BEST — if the app has data-testid
-card title:
-  type: 'testid'
-  value: 'card-title'
-```
-
-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
-
-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.
+**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.
 
-**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
-
 ---
 
-### 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
+## Step 6: Validate Before Running
 
-#### What to check
+**Fix 80%+ of selector issues before first test run.**
 
-| 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) |
+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
 
-#### 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.**
+Common fixes: name mismatch → copy from snapshot, element in iframe → add `frame`, multiple matches → add `nth` or `exact: true`.
 
 ---
 
-### 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)
+## Step 7: Run & Fix Loop
 
-5. FINAL CONFIRMATION — after all batches pass, run ALL tests once:
-     npx playwright test <spec> --reporter=line
-     This catches regressions from selector changes.
+Run tests in batches of 20. Group failures by root cause (same selector, same error type). Fix once, verify batch, move to next.
 
-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
+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 `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.
-
----
-
-### 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.