@sun-asterisk/sungen 2.2.2 → 2.3.0

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

@@ -4,13 +4,35 @@ description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use t
 user-invocable: false
 ---
 
-## Step Patterns (65 patterns)
+## Standard Syntax
+
+```
+[Keyword] User <Action> [Target Name] <Target Type> <in [Parent Name] <Parent Type>> <with {{Value}}> <is State>
+```
+
+- **Actor**: Always `User`, always active voice.
+- **Value**: `with {{snake_case}}` — never hardcode static data.
+- **State**: `is <keyword>` — never use `{{}}` for states.
+- **Parent scope**: `in [Parent] parentType` — optional, only when page has 2+ similar blocks needing disambiguation.
+
+## Keyword → Action Rules
+
+```
+GIVEN  →  is on
+WHEN   →  click · fill · select · press · clear · check · uncheck · hover
+         [⚠️ wait for — only for Spinner/Modal, minimize usage]
+THEN   →  see
+AND    →  inherits from preceding keyword
+```
+
+## Step Patterns (70 patterns)
 
 ### Setup
 
 ```
 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
 ```
 
@@ -18,31 +40,57 @@ User is logged in | is not logged in              # auth state
 
 ```
 User fill [T] field with {{v}}                   # text input
+User fill [T] textarea with {{v}}                # multiline input
+User fill [T] search with {{v}}                  # search input
+User fill [T] slider with {{v}}                  # set slider value
+User fill [T] date picker with {{v}}             # date input
 User clear [T] field                             # clear input
 User check [T] checkbox                          # check
+User check [T] toggle                            # toggle on (same as check)
+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 toggle [T] switch                           # toggle switch/checkbox
-User upload [T] file with {{f}}                  # file upload
+User upload [T] uploader with {{f}}              # file upload
 ```
 
 ### Interaction
 
 ```
-User click [T] button                            # click
-User click [T] button with {{v}}                 # click with text match
+User click [T] button                            # click (static element, no value)
+User click [T] row with {{v}}                    # click dynamic list item (row/item/card/option)
+User click [T] tab                               # switch tab
+User click [T] column                            # sort column
+User click [T] breadcrumb                        # navigate breadcrumb
 User double click [T] element                    # double click
-User hover [T] icon                              # hover
+User hover [T] icon                              # hover (must have see/click after)
+User hover [T] row                               # hover row for hidden actions
 User drag [T] to [T2]                            # drag and drop
 User expand [T] row                              # expand (aria-expanded)
 User collapse [T] row                            # collapse (aria-expanded)
 ```
 
+#### click + with {{Value}} rule
+
+- **NO value** for static elements: `button`, `link`, `icon`, `tab`, `toggle`
+- **WITH value** only for dynamic lists: `row`, `item`, `card`, `option`
+
+### Browser Alert (system dialog)
+
+```
+User click [OK] alert                            # accept (OK/Accept/Yes/Confirm)
+User click [Cancel] alert                        # dismiss (Cancel/Dismiss/No)
+User fill [T] alert with {{v}}                   # fill prompt + accept
+User see [message text] alert                    # assert dialog message
+```
+
+> Alert steps must appear BEFORE the action that triggers the dialog.
+
 ### Keyboard
 
 ```
-User press Escape key                            # global key press
-User press Enter on [T] field                    # key on element
+User press [Escape] key                          # global key press
+User press [Enter] on [T] field                  # key on element
 ```
 
 ### Wait
@@ -53,53 +101,129 @@ User wait for [T] dialog                         # wait for element
 User wait for [T] dialog is STATE                # wait for state
 User wait for [T] dialog with {{v}}              # wait for element with text
 User wait for [T] page                           # wait for navigation
+User wait for [T] message                        # wait for toast/feedback
+User wait for [T] button                         # wait for button to appear
 ```
 
 ### Scroll & Frame
 
 ```
 User scroll to [T] section                       # scroll into view
-User switch to [T] frame                         # enter/exit iframe
+User switch to [T] frame                         # enter iframe
+User switch to [main] frame                      # exit iframe
 ```
 
-### Assertions
+### Assertions (8 verify patterns)
 
 ```
-User see [T] page                                # URL assertion
-User see [T] heading                             # visibility
-User see [T] heading with {{v}}                  # visibility + text
+# 1. Visibility
+User see [T] message                             # visible (default — NEVER add "is visible")
+User see [T] modal is hidden                     # hidden
+
+# 2. Text Content (exact full match — toHaveText)
+User see [T] message with {{v}}                  # exact text match
+User see [T] header with {{v}}                   # heading text
+User see [T] label with {{v}}                    # label text
+
+# 3. Partial Text Match (toContainText)
 User see [T] text contains {{v}}                 # partial text match
-User see [T] text has text {{v}}                 # exact text match
-User see [T] button is STATE                     # state assertion
-User see [T] dialog with {{v}} is STATE          # text + state
-User see {{v}}                                   # see data text
+
+# 4. Input Value (toHaveValue)
+User see [T] field with {{v}}                    # input value
+User see [T] dropdown with {{v}}                 # selected value
+User see [T] date picker with {{v}}              # date value
+User see [T] search with {{v}}                   # search input value
+User see [T] slider with {{v}}                   # slider value
+
+# 5. Component State
+User see [T] button is disabled                  # state assertion
+User see [T] checkbox is checked                 # checked state
+User see [T] toggle is unchecked                 # unchecked state
+User see [T] dialog with {{v}} is hidden         # text + state combined
+
+# 6. Attribute (toHaveAttribute — when selector YAML has `attribute` field)
+User see [T] image with {{v}}                    # image src
+User see [T] link with {{v}}                     # link href
+
+# 7. Count
+User see [T] row with {{count}}                  # element count
+
+# 8. Page Context
+User see [T] page                                # URL assertion
 ```
 
 ### Table
 
 ```
-User see [Table] table has row with {{f}}        # row exists
+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 has {{count}} rows        # row count
-User see [Table] table has [Col] column          # column 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
 ```
 
+### 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 })`
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
 
 ### Element Types
 
-`page` `button` `link` `field` `textarea` `heading` `text` `checkbox` `radio` `switch` `dropdown` `dialog` `modal` `menu` `menuitem` `tab` `tabpanel` `table` `row` `cell` `list` `listitem` `icon` `image` `alert` `spinner` `progressbar` `section` `region` `nav` `frame` `uploader` `file` `columnheader` `tooltip` `slider` `treeitem`
+| 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` |
+
+### 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' })` |
 
 ## YAML Keys
 
 `[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
+- Target Name > 30 chars → shorten to 1–3 meaningful words
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -120,8 +244,30 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@auto` | Standard scenario, ready for automation |
+| `@manual` | Skip in generation |
+| `@smoke` / `@regression` | Test suite grouping |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
-| `@steps:name` | Define reusable step block |
-| `@extend:name` | Prepend steps from @steps block |
-| `@manual` | Skip in generation |
+| `@steps:name` | Define reusable step block (base scenario) |
+| `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+
+### @extend behavior
+
+- Tool executes **only Given→When** of `@steps` scenario (skips Then)
+- The `Given` in `@extend` scenario is the **entry assertion** (confirms state after base steps)
+- If `@steps` scenario fails, `@extend` scenario is **skipped**
+- Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`
+
+## Common Syntax Errors
+
+| Error | Wrong | Correct |
+|---|---|---|
+| Wrong keyword | `Given User click [T] button` | `When User click [T] button` |
+| Wrong action for type | `When User click [T] checkbox` | `When User check [T] checkbox` |
+| press wrong target | `When User press [Submit] button` | `When User press [Enter] key` |
+| uncheck radio | `When User uncheck [Male] radio` | `When User check [Female] radio` |
+| Hardcode data | `with {{admin@mail.com}}` | `with {{invalid_email}}` |
+| 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}}` |

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

@@ -124,6 +124,24 @@ To determine the correct `nth` offset, count how many matching elements appear b
 
 ---
 
+### Step 4b: Handle 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
+
+```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.
@@ -168,9 +186,16 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 |---|---|
 | `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
 | `[Home] link` | `getByRole('link', { name: 'Home' })` |
-| `[Welcome] heading` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
 | `[Email] field` | `getByPlaceholder('Email')` |
-| `[Success] text` | `getByText('Success')` |
+| `[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
@@ -181,20 +206,76 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 
 ---
 
-### Fix Loop on Test Failure
+### 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
+Array.from(document.querySelectorAll('button'))
+  .filter(el => el.textContent.includes('Submit') || el.getAttribute('aria-label')?.includes('Submit'))
+  .length;
 ```
-attempt = 0
-while attempt < 5:
-    compile → run test
-    if pass → done
-    read error-context.md in test-results/ → check exact snapshot state at failure time
-    fix selectors.yaml or test-data.yaml
-    recompile → attempt++
-if still failing → ask user about direct .spec.ts fix
+
+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.**
+
+---
+
+### 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, 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
+```
+
+#### 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
 
-**Always read the error context snapshot first** — it shows the exact page state when the test failed, which is more reliable than re-navigating with MCP.
+Fix the root cause first, verify with the batch, then move on.
 
 ---
 

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

@@ -51,6 +51,10 @@ Type aliases (normalized automatically):
 | logo, image, icon | `img` |
 | btn | `button` |
 | input, textbox, textarea, editor | `field` |
+| search | `searchbox` |
+| toggle | `switch` |
+| alert | `alertdialog` |
+| modal, drawer | `dialog` |
 | column | `columnheader` |
 | list-item | `listitem` |
 
@@ -83,10 +87,20 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 |---|---|
 | `[X] button` | `getByRole('button', { name: 'X' })` |
 | `[X] link` | `getByRole('link', { name: 'X' })` |
-| `[X] heading` | `getByRole('heading', { name: 'X' })` |
+| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` |
 | `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
+| `[X] radio` | `getByRole('radio', { name: 'X' })` |
 | `[X] field` | `getByPlaceholder('X')` |
-| `[X] text` | `getByText('X')` |
+| `[X] text` / `message` / `label` | `getByText('X')` |
 | `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
+| `[X] search` | `getByRole('searchbox', { name: 'X' })` |
+| `[X] option` | `getByRole('option', { name: 'X' })` |
+| `[X] slider` | `getByRole('slider', { name: 'X' })` |
+| `[X] toggle` | `getByRole('switch', { name: 'X' })` |
+| `[X] tab` | `getByRole('tab', { name: 'X' })` |
+| `[X] table` | `getByRole('table', { name: 'X' })` |
+| `[X] list` | `getByRole('list', { name: 'X' })` |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` |
+| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
 
 **Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).