@sun-asterisk/sungen 2.4.0 → 2.4.1

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`