@sun-asterisk/sungen 2.3.1 → 2.4.1

package/dist/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-    │────────▶│ /make-tc │────────▶│ /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:
@@ -63,7 +63,7 @@ Scaffolds `qa/screens/<name>/` with empty feature, selectors, test-data, and req
 
 | Claude Code | GitHub Copilot (VS Code) |
 |---|---|
-| `/sungen:make-tc login` | `/sungen-make-tc login` |
+| `/sungen:create-test login` | `/sungen-create-test login` |
 
 AI acts as a **Senior QA Engineer**:
 1. Reads `requirements/spec.md` for screen specs (fields, validation, business rules, states)
@@ -76,7 +76,7 @@ AI acts as a **Senior QA Engineer**:
 
 | Claude Code | GitHub Copilot (VS Code) |
 |---|---|
-| `/sungen:make-test login` | `/sungen-make-test login` |
+| `/sungen:run-test login` | `/sungen-run-test login` |
 
 AI acts as a **Senior Developer**:
 1. Navigates to live page, takes snapshot, verifies DOM properties
@@ -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` |
-| Table row | `User see [Users] table row with {{name}}` |
+| 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/index.ts

@@ -17,7 +17,7 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.3.1');
+    .version('2.4.1');
 
   // Global options
   program

package/src/generators/gherkin-parser/index.ts

@@ -5,6 +5,15 @@ import fs from 'fs';
 import path from 'path';
 import { SelectorResolver } from '../test-generator/utils/selector-resolver';
 
+export interface DataTableRow {
+  cells: string[]; // Cell values in order
+}
+
+export interface ParsedDataTable {
+  headers: string[]; // First row = column headers
+  rows: DataTableRow[]; // Remaining rows = data rows
+}
+
 export interface ParsedStep {
   keyword: string; // Given, When, Then, And, But
   text: string; // Original step text
@@ -16,6 +25,7 @@ export interface ParsedStep {
   featurePath?: string; // NEW: Feature path for page type (e.g., "/", "/dashboard")
   parentRef?: string; // Parent scope reference: "in [Parent Name] parentType" → parentRef = "Parent Name"
   parentType?: string; // Parent scope type: table, list, section, dialog, form
+  dataTable?: ParsedDataTable; // Inline data table (Cucumber DataTable syntax)
 }
 
 export interface ParsedScenario {
@@ -172,6 +182,18 @@ export class GherkinParser {
       nth = SelectorResolver.extractNthFromStep(afterElement);
     }
 
+    // Extract inline data table (Cucumber DataTable syntax)
+    let dataTable: ParsedDataTable | undefined;
+    if (step.dataTable && step.dataTable.rows && step.dataTable.rows.length >= 2) {
+      const rows = step.dataTable.rows;
+      dataTable = {
+        headers: rows[0].cells.map((cell: any) => cell.value),
+        rows: rows.slice(1).map((row: any) => ({
+          cells: row.cells.map((cell: any) => cell.value),
+        })),
+      };
+    }
+
     return {
       keyword: step.keyword.trim(),
       text: step.text, // Preserve original text (with parent scoping) for pattern matching
@@ -182,6 +204,7 @@ export class GherkinParser {
       nth,
       parentRef,
       parentType,
+      dataTable,
     };
   }
 

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/table-action-in-row.hbs

@@ -1,2 +1,2 @@
 { const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
-await tableRow.getByRole('button', { name: '{{escapeQuotes elementName}}' }).{{action}}(); }
+await tableRow.getByRole('{{elementRole}}', { name: '{{escapeQuotes elementName}}' }).{{action}}(); }

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-column-exists.hbs

@@ -1 +1,5 @@
-await expect({{> locator}}.getByRole('columnheader', { name: '{{escapeQuotes columnName}}' })).toBeVisible();
+{{~#if isGiven}}
+await {{> locator}}.getByRole('columnheader', { name: '{{escapeQuotes columnName}}' }).waitFor();
+{{~else}}
+await expect({{> locator}}.getByRole('columnheader', { name: '{{escapeQuotes columnName}}' })).toBeVisible();
+{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-match-data.hbs

@@ -0,0 +1,15 @@
+{{~#if isGiven~}}
+{
+  const rows = {{> locator}}.locator('tbody').getByRole('row');
+{{#each assertions}}
+  {{this}}
+{{/each~}}
+}
+{{~else~}}
+{
+  const rows = {{> locator}}.locator('tbody').getByRole('row');
+{{#each assertions}}
+  {{this}}
+{{/each~}}
+}
+{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-exists.hbs

@@ -1 +1,7 @@
-await expect({{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' })).toBeVisible();
+{{~#if isGiven}}
+const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
+await tableRow.waitFor();
+{{~else}}
+const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
+await expect(tableRow).toBeVisible();
+{{~/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-row-not-exists.hbs

@@ -1 +1,5 @@
-await expect({{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' })).toHaveCount(0);
+{{~#if isGiven}}
+await {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' }).waitFor({ state: 'hidden' });
+{{~else}}
+await expect({{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' })).toHaveCount(0);
+{{~/if}}

package/src/generators/test-generator/patterns/index.ts

@@ -74,7 +74,8 @@ export class PatternRegistry {
       const resolved = pattern.resolver(step, context);
 
       // Auto-inject parent scoping if step has parentRef
-      if (step.parentRef && step.parentType) {
+      // Skip for table-* patterns — they resolve the table name internally from step text
+      if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
         resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
           step.parentRef, step.parentType, context
         );