@sun-asterisk/sungen 2.4.0 → 2.4.2

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -1,6 +1,6 @@
 ---
 name: sungen-gherkin-syntax
-description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use this when writing or editing .feature, selectors.yaml, or test-data.yaml files.'
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-loaded when writing .feature, selectors.yaml, or test-data.yaml.'
 user-invocable: false
 ---
 
@@ -50,7 +50,7 @@ User check [T] radio                             # select radio
 User uncheck [T] checkbox                        # uncheck
 User uncheck [T] toggle                          # toggle off
 User select [T] dropdown with {{v}}              # select option
-User upload [T] uploader with {{f}}              # file upload
+User fill [T] uploader with {{f}}                # file upload
 ```
 
 ### Interaction
@@ -161,10 +161,17 @@ 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
+User see [Table] table match data:                              # exact table match (inline DataTable)
+    | Header1    | Header2    |
+    | {{value1}} | {{value2}} |
 ```
 
+**Priority**: Use row scope patterns for single-row verification + actions. Use `table match data` only when verifying multiple rows at once.
+
 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 })`.
 
+Table match data: `see [Table] table match data:` followed by a Cucumber DataTable. First row = headers, remaining rows = expected data. Uses **filter-based matching** — verifies rows containing expected values exist, resilient to data changes, extra rows, and row reordering. Use `{{variable}}` for cell values.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
@@ -240,3 +247,39 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
 | State as value | `with {{disabled}}` | `is disabled` |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
+| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
+
+## Background vs @steps/@extend
+
+**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+
+**Why:**
+- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
+- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
+- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+
+**Wrong:**
+```gherkin
+Background:
+  Given User is on [Kudos] page
+  When User click [Open] button
+  And User is on [Modal] dialog    ← keyword mismatch
+
+Scenario: VP-UI-001 Title visible
+  Then User see [Title] heading
+```
+
+**Correct:**
+```gherkin
+@steps:open_modal
+Scenario: Open modal
+  Given User is on [Kudos] page
+  When User click [Open] button
+  Then User see [Modal] dialog
+
+@extend:open_modal
+Scenario: VP-UI-001 Title visible
+  Given User is on [Modal] dialog
+  Then User see [Title] heading
+```

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

@@ -1,41 +1,51 @@
 ---
 name: sungen-selector-fix
-description: 'Selector generation and fixing strategy — explore live page, generate selectors.yaml, validate, auto-fix. Auto-loaded by run-test command.'
+description: 'Selector fixing strategy — diagnose failures, explore live page targeted, fix broken selectors. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## When to Generate
+## Strategy: Fix Only What Breaks
 
-Selectors are generated during `/sungen:run-test`, NOT during `/sungen:create-test`.
+Most selectors auto-infer from Gherkin element types (see `sungen-selector-keys` skill). Only add YAML entries for selectors that fail during test execution.
+
+**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 & Snapshot
+## Step 1: Diagnose Failures
 
-1. Read `baseURL` from `playwright.config.ts`
-2. `browser_navigate` to `baseURL`
-3. If redirected to login → ask user to log in manually via MCP browser
-4. Navigate to target page → `browser_snapshot`
+Parse Playwright error output to categorize failures:
 
-**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
+| 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.
+
+**Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
 ---
 
-## Step 2: Build Element Catalog
+## Step 2: Targeted MCP Exploration
 
-**Never guess names from Gherkin labels. Copy exact values from snapshot.**
+Only when `test-results/` screenshots are insufficient:
 
-Catalog all accessible elements from snapshot: buttons, links, headings, inputs, regions, images.
+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
 
-Then check for `data-testid` attributes:
-```js
-Array.from(document.querySelectorAll('[data-testid]'))
-  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
-```
+**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
 
 ---
 
-## Step 3: Map Gherkin Labels → Selectors
+## Step 3: Fix Broken Selectors
+
+For each failed selector, find the correct locator from the snapshot:
 
 Selector priority (use first applicable):
 
@@ -50,24 +60,24 @@ Selector priority (use first applicable):
 
 **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"]'
+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) }))
 ```
 
-**Dynamic content**: never use `type: text` with specific value. Use `testid` or structural `role` + `nth`.
-
-**Multiple matches**: add `nth: 0` for first occurrence.
-
-Auto-infer rules and lookup priority → see `sungen-selector-keys` skill.
+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: Table Selectors
 
-For table patterns using the v2.3 syntax, generate table selectors with `columns` config:
+For table patterns, add table selectors with `columns` config:
 
 ```yaml
 users:
@@ -88,15 +98,6 @@ users:
 
 **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.
 
-**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
-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}}
-```
-
 ---
 
 ## Step 5: Detail Screens with Dynamic IDs
@@ -113,28 +114,12 @@ user detail:
 
 ---
 
-## Step 6: Validate Before Running
-
-**Fix 80%+ of selector issues before first test run.**
-
-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 fixes: name mismatch → copy from snapshot, element in iframe → add `frame`, multiple matches → add `nth` or `exact: true`.
-
----
-
-## Step 7: Run & Fix Loop
-
-Run tests in batches of 20. Group failures by root cause (same selector, same error type). Fix once, verify batch, move to next.
-
-```
-compile → batch run 20 → fix root cause → recompile → re-run failures → next batch
-```
+## Step 6: Fix Loop
 
-After all batches pass → run ALL tests once for regression check.
+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
 
-If still failing after 5 attempts per batch → ask user about direct `.spec.ts` fix.
+If still failing after 3 attempts → ask user for guidance.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -68,25 +68,38 @@ And User wait for [Page Title] heading is visible
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
+**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+
 ```gherkin
 @auth:role
 Feature: <Screen> Screen
 
+  # Shared setup — use @steps, not Background
+  @steps:open_form
+  Scenario: Open form
+    Given User is on [Screen] page
+    And User wait for [Screen Title] heading is visible
+    When User click [Create] button
+    Then User see [Form] dialog
+
   # ============================================================
   # Section: Create User Form
   # ============================================================
 
   # --- UI/UX ---
 
+  @extend:open_form
   Scenario: VP-UI-001 Form displays all fields with correct defaults
-    Given User is on [Create User] page
+    Given User is on [Form] dialog
     Then User see [Name] field
     And User see [Email] field
     And User see [Submit] button is disabled
 
   # --- Validation ---
 
+  @extend:open_form
   Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Form] dialog
     When User click [Submit] button
     Then User see [Name error] message with {{name_required_error}}
 
@@ -100,8 +113,28 @@ Feature: <Screen> Screen
     Then User see [Name] column in [Users] table
     And User see [Email] column in [Users] table
     And User see [Status] column in [Users] table
+
+  # --- Data & Validate ---
+
+  Scenario: VP-VAL-010 Table displays correct data
+    Then User see [Users] table match data:
+      | Name         | Email          | Status       |
+      | {{name_1}}   | {{email_1}}    | {{status_1}} |
+      | {{name_2}}   | {{email_2}}    | {{status_2}} |
+
+  Scenario: VP-VAL-011 Edit button targets correct row
+    Given User see [Target] row in [Users] table with {{name_1}}
+    When User click [Edit] button in [Users] table with {{name_1}}
+    Then User see [Name] field with {{name_1}}
 ```
 
+### When to use DataTable vs Row Scope
+
+| Pattern | Use when |
+|---|---|
+| `table match data:` + DataTable | Verifying **multiple rows** exist with expected values |
+| `row in [Table] table with {{v}}` + `column with {{v}}` | Checking **single row** details or **acting** on a row (click, edit) |
+
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix.
 
 **Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-viewpoint.md

@@ -52,6 +52,8 @@ user-invocable: false
 - Consistency: total record count on UI matches server data
 - Row Limit: displayed rows never exceed page size/limit
 - Cell Integrity: cell data matches database, correct format (date, currency, status)
+- **Use `table match data:` with inline DataTable** for multi-row content verification (filter-based, resilient to data changes)
+- Use row scope (`row in [Table] table with {{v}}` + `column with {{v}}`) for single-row detail checks or when you need actions on a row
 
 **Logic**
 - Sorting: column sort refreshes data with correct order, updates header icon
@@ -82,7 +84,7 @@ user-invocable: false
 
 **Security**
 - Injection: XSS/SQL encoded as plain text, never executed
-- Wildcards: %, _, * treated as normal text (escaped)
+- Wildcards: `%, _, *` treated as normal text (escaped)
 
 ---
 

package/src/orchestrator/templates/readme.md

@@ -1,6 +1,6 @@
 # Sungen Test Automation
 
-This project uses [Sungen v2](https://github.com/sun-asterisk/sungen) — a deterministic E2E test compiler.
+This project uses [Sungen v2.4.1](https://github.com/sun-asterisk/sungen) — a deterministic E2E test compiler.
 
 ## How it works
 
@@ -37,16 +37,16 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 ## Workflow
 
 ```
-Step 1                Step 2                Step 3
-┌──────────┐         ┌──────────┐         ┌──────────┐
-│ /add-    │────────▶│ /create-test │────────▶│ /make-   │
-│ screen   │         │          │         │ test     │
-└──────────┘         └──────────┘         └──────────┘
- Scaffold              Pick sections        Generate
- directories           → design TCs         selectors
-                       → generate           → compile
-                       .feature +           → run tests
-                       test-data            → auto-fix
+Step 1                Step 2                Step 3                Step 4
+┌──────────┐         ┌──────────┐         ┌──────────┐         ┌──────────┐
+│ /add-    │────────▶│ /create- │────────▶│ /run-    │────────▶│ /review  │
+│ screen   │         │ test     │         │ test     │         │          │
+└──────────┘         └──────────┘         └──────────┘         └──────────┘
+ Scaffold              Pick sections        Generate             Review
+ directories           → design TCs         selectors            syntax &
+                       → generate           → compile            coverage
+                       .feature +           → run tests          → score &
+                       test-data            → auto-fix           auto-fix
 ```
 
 Use AI commands (Claude Code or GitHub Copilot) to drive the workflow:
@@ -84,6 +84,17 @@ AI acts as a **Senior Developer**:
 3. Compiles Gherkin → Playwright `.spec.ts`
 4. Runs tests, auto-fixes selectors on failure (up to 5 attempts)
 
+### Step 4: Review test cases
+
+| Claude Code | GitHub Copilot (VS Code) |
+|---|---|
+| `/sungen:review login` | `/sungen-review login` |
+
+AI acts as a **Senior QA Reviewer**:
+1. Validates syntax against all Gherkin rules
+2. Scores coverage across viewpoint categories
+3. Can auto-fix issues when `--fix` flag is used
+
 ### Auth setup
 
 If any page requires authentication, the AI will ask you to **log in manually via the MCP browser** during Step 2 or Step 3. No separate auth command needed.
@@ -123,38 +134,85 @@ Add to `.vscode/settings.json` to auto-load Gherkin syntax when editing `.featur
 ### Syntax
 
 ```
-User <action> [<Target>] <type> with {{<Value>}}
+[Keyword] User <action> [Target] <type> <in [Parent] parentType> <with {{value}}> <is state>
 ```
 
 - `[Target]` → selector reference → lookup in `selectors/*.yaml`
-- `{{Value}}` → test data reference → lookup in `test-data/*.yaml`
-- `<type>` → element type: button, link, field, heading, text, etc.
+- `{{value}}` → test data reference → lookup in `test-data/*.yaml`
+- `<type>` → element type: button, link, field, heading, text, table, etc.
+- `in [Parent] parentType` → optional parent scope for disambiguation
 
 ### Key Patterns
 
 | Pattern | Example |
 |---|---|
 | Navigate | `User is on [login] page` |
+| Navigate with data | `User is on [user detail] page with {{user_id}}` |
 | Click | `User click [Submit] button` |
 | Fill | `User fill [Email] field with {{email}}` |
-| Assert visible | `User see [Welcome] heading is visible` |
+| Select | `User select [Country] dropdown with {{country}}` |
+| Check | `User check [Remember me] checkbox` |
+| Upload | `User fill [Avatar] uploader with {{file}}` |
+| Clear | `User clear [Search] field` |
+| Hover | `User hover [Info] icon` |
+| Keyboard | `User press Enter on [Search] field` |
+| Scroll | `User scroll to [Footer] section` |
+| Assert visible | `User see [Welcome] heading` |
+| Assert hidden | `User see [Error] message is hidden` |
 | Assert text | `User see [Title] heading with {{title}}` |
+| Assert value | `User see [Email] field with {{email}}` |
 | Assert state | `User see [Submit] button is disabled` |
-| Wait for | `User wait for [Modal] dialog is visible` |
+| Contains text | `User see [Message] text contains {{partial}}` |
+| Wait for | `User wait for [Modal] dialog` |
 | Table row | `User see [Username] row in [Users] table with {{name}}` |
+| Table cell | `User see [Status] column with {{status}}` (row scoped) |
 | Table column | `User see [Email] column in [Users] table` |
+| Table count | `User see [Users] table with {{count}}` |
+| Table empty | `User see [Users] table is empty` |
+| Table action | `User click [Edit] button in [Users] table with {{name}}` |
+| Table match | `User see [Users] table match data:` + inline DataTable |
+| Alert | `User click [OK] alert` |
+| Frame | `User switch to [Payment] frame` |
+
+### Table Match Data
+
+Verify multiple rows exist using filter-based matching (resilient to data changes and row reordering):
+
+```gherkin
+Then User see [Users] table match data:
+    | ID       | Name       | Status       |
+    | {{id_1}} | {{name_1}} | {{status_1}} |
+    | {{id_2}} | {{name_2}} | {{status_2}} |
+```
+
+First row = headers, remaining rows = expected data. For single-row verification + actions, use row scope patterns instead.
 
-States: `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected`
+### States
+
+`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
+
+### Element Types
+
+| Group | Types |
+|---|---|
+| **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` |
+| **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` |
+| **Trigger** | `button` `link` `icon` `menuitem` `tag` |
+| **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` |
+| **Feedback** | `message` `header` `label` `text` `tooltip` `badge` `breadcrumb` `image` |
+| **System** | `key` `frame` `spinner` `progressbar` |
 
 ### Tags
 
 | Tag | Purpose |
 |---|---|
+| `@auto` | Standard scenario, ready for automation |
+| `@manual` | Skip scenario in generation |
+| `@smoke` / `@regression` | Test suite grouping |
 | `@auth:role` | Use Playwright storage state for auth |
 | `@no-auth` | Disable inherited auth for this scenario |
 | `@steps:name` | Define reusable step group |
 | `@extend:name` | Inherit steps from another scenario |
-| `@manual` | Skip scenario in generation |
 
 ### YAML Selector Keys
 
@@ -167,10 +225,15 @@ Keys are **lowercase with spaces**, Unicode preserved:
 
 ```yaml
 search:
-  type: 'placeholder'        # testid, role, placeholder, label, text, locator, page
+  type: 'placeholder'        # testid, role, placeholder, label, text, locator, page, upload, frame
   value: 'Search users'      # placeholder text, role name, CSS selector, etc.
   name: 'Search'             # accessible name (for role type)
   nth: 0                     # element index (for multiple matches)
+  exact: true                # exact name matching
+  columns:                   # table column config (for table type)
+    status:
+      index: 2
+      header: Status
 ```
 
 Priority: `data-testid` > `role+name` > `placeholder` > `label` > `text` > `CSS locator`