@sun-asterisk/sungen 2.0.2 → 2.1.0

package/dist/orchestrator/templates/ai-instructions/copilot-skill-selector-keys.md

@@ -0,0 +1,94 @@
+---
+description: 'Rules for generating correct YAML selector keys from Gherkin [Reference] names. Referenced by other sungen prompts when creating or fixing selectors.yaml files.'
+mode: 'agent'
+tools: []
+---
+
+## Key Generation: `[Reference]` → YAML key
+
+Transform: Vietnamese/Japanese → ASCII → lowercase → remove special chars → spaces to dots.
+
+```
+[Submit]              → submit
+[Search Content]      → search.content
+[User's Profile]      → users.profile
+[Thời gian]           → thoi.gian
+[Địa điểm]            → dia.diem
+[ログイン]              → roguin
+[パスワード]            → pasuwaado
+[Page 2]              → page.2
+[Kudos Detail Modal]  → kudos.detail.modal
+```
+
+**Rules:**
+1. Remove Vietnamese diacritics: `ằắẳẵặ` → `a`, `đ` → `d`, etc.
+2. Convert Japanese Hiragana/Katakana to Romaji
+3. Lowercase everything
+4. `'s` → `s` (apostrophe-s becomes just s)
+5. Remove all special chars except spaces
+6. Trim, then spaces → dots
+7. **NEVER use spaces, underscores, or uppercase in YAML keys**
+
+## Type-Suffixed Keys
+
+When the same label is used for different element types, add `--type` suffix:
+
+```yaml
+# [Add Campaign] button AND [Add Campaign] text
+add.campaign--button:
+  type: 'role'
+  value: 'button'
+  name: 'Add Campaign'
+
+add.campaign--text:
+  type: 'text'
+  value: 'Add Campaign'
+```
+
+Type aliases (normalized automatically):
+| Gherkin type | Normalized suffix |
+|---|---|
+| title, label, caption, message | `text` |
+| heading, header | `heading` |
+| logo, image, icon | `img` |
+| btn | `button` |
+| input, textbox, textarea, editor | `field` |
+| column | `columnheader` |
+| list-item | `listitem` |
+
+## Nth-Suffixed Keys
+
+When targeting a specific occurrence by index, add `--N` suffix:
+
+```yaml
+# [Send Thank You] button 3
+hay.gui.loi.cam.on--3:
+  type: 'role'
+  value: 'button'
+  name: 'Send Thank You'
+```
+
+## Lookup Priority
+
+Resolver searches in this order:
+1. `key--N` (nth-suffixed)
+2. `key--type` (type-suffixed, normalized)
+3. `key` (base key)
+4. Auto-infer from element type if no YAML entry
+5. Any `key--*` (first suffixed match)
+
+## Auto-Infer (no YAML entry needed)
+
+If no YAML key exists, the resolver infers from the Gherkin element type:
+
+| Gherkin | Inferred locator |
+|---|---|
+| `[X] button` | `getByRole('button', { name: 'X' })` |
+| `[X] link` | `getByRole('link', { name: 'X' })` |
+| `[X] heading` | `getByRole('heading', { name: 'X' })` |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
+| `[X] field` | `getByPlaceholder('X')` |
+| `[X] text` | `getByText('X')` |
+| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
+
+**Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).

package/dist/orchestrator/templates/readme.md

@@ -19,8 +19,6 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 ├── specs/
 │   ├── generated/        # Auto-generated Playwright tests
 │   └── .auth/            # Auth storage states
-├── docs/
-│   └── gherkin-dictionary.md  # Full grammar & compiler rules
 ├── .github/
 │   └── copilot-instructions.md  # AI rules for GitHub Copilot
 └── CLAUDE.md                    # AI rules for Claude Code
@@ -28,55 +26,62 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 
 ## Workflow
 
-### 1. Add a screen
-
-```bash
-sungen add --screen login --path /login
-# Add more features to an existing screen:
-sungen add --screen login --feature forgot-password
+```
+Step 1                Step 2                Step 3
+┌──────────┐         ┌──────────┐         ┌──────────┐
+│ /add-    │────────▶│ /make-tc │────────▶│ /make-   │
+│ screen   │         │          │         │ test     │
+└──────────┘         └──────────┘         └──────────┘
+ Scaffold              Design TCs           Compile &
+ directories           & generate           run tests
+                       3 files
 ```
 
-### 2. Set up auth (if needed)
+Use AI commands (Claude Code or GitHub Copilot) to drive the workflow:
 
-```bash
-sungen makeauth admin
-# Opens browser → login manually → saves specs/.auth/admin.json
-```
+### Step 1: Add a screen
 
-### 3. Generate Gherkin + selectors with AI
+| Claude Code | GitHub Copilot |
+|---|---|
+| `/sungen:add-screen login /login` | `@workspace /sungen-add-screen login /login` |
 
-Use your AI assistant (GitHub Copilot or Claude Code) to:
-1. Navigate to the page URL via MCP Playwright
-2. Take an accessibility snapshot
-3. Generate `.feature` + `selectors.yaml` + `test-data.yaml`
+Scaffolds `qa/screens/<name>/` with empty feature, selectors, and test-data files, then asks if you want to create test cases.
 
-The AI rules in `.github/copilot-instructions.md` and `CLAUDE.md` teach the AI
-how to write correct Gherkin syntax and selector YAML for sungen.
+### Step 2: Create test cases
 
-### 4. Compile to Playwright tests
+| Claude Code | GitHub Copilot |
+|---|---|
+| `/sungen:make-tc login` | `@workspace /sungen-make-tc login` |
 
-```bash
-sungen generate --screen login
-# or for all screens:
-sungen generate --all
-```
+AI acts as a **Senior QA Engineer**: explores the live page (via Playwright MCP) or analyzes static designs, gathers test viewpoints (UI/UX, Validation, Logic, Security), and generates the 3 files.
 
-### 5. Run tests
+### Step 3: Compile & run tests
+
+| Claude Code | GitHub Copilot |
+|---|---|
+| `/sungen:make-test login` | `@workspace /sungen-make-test login` |
+
+AI acts as a **Senior Developer**: compiles Gherkin → Playwright `.spec.ts`, runs tests, and auto-fixes selectors/test-data on failure (up to 5 attempts).
+
+### Auth setup (if needed)
+
+If any page requires authentication, run manually before Step 2:
 
 ```bash
-npx playwright test
-npx playwright test --ui   # interactive mode
+sungen makeauth admin --url <baseURL>
+# Opens browser → login manually → saves specs/.auth/admin.json
 ```
 
-### 6. Fix failures (AI Verify loop)
-
-When tests fail, use AI to read the error → fix `selectors.yaml` → recompile → re-run.
+### Manual CLI commands
 
-| Error | Fix in selectors.yaml |
-|---|---|
-| strict mode: resolved to N elements | Add `exact: true` or `scope` or `nth` |
-| element(s) not found | Fix `name`, `type`, or `value` |
-| getByText matched too many | Add `match: 'exact'` or `nth` |
+```bash
+sungen add --screen <name> --path <path>     # Scaffold screen
+sungen add --screen <name> --feature <name>  # Add feature to screen
+sungen generate --screen <name>              # Compile to .spec.ts
+sungen generate --all                        # Compile all screens
+npx playwright test                          # Run all tests
+npx playwright test --ui                     # Interactive mode
+```
 
 ---
 
@@ -180,7 +185,7 @@ submit.button:
   type: 'role'              # testid, role, text, label, placeholder, locator, page
   value: 'button'           # role name, testid value, CSS selector, etc.
   name: 'Submit'            # accessible name
-  nth: 0                    # element index (0=first, 1=.nth(0), 2=.nth(1))
+  nth: 0                    # element index, 0-indexed (omit for strict mode)
   exact: true               # exact name match (avoid "Submit" matching "Submit Form")
   scope: 'desktop navigation'  # scope to parent landmark
   match: 'exact'            # exact text match for getByText
@@ -192,6 +197,5 @@ Locator priority: `data-testid` > `role+name` > `label` > `text` > `CSS`
 
 ## Documentation
 
-- [Gherkin Dictionary](docs/gherkin-dictionary.md) — full grammar, all 17 patterns, compiler rules
 - [Sungen GitHub](https://github.com/sun-asterisk/sungen)
 - [Playwright Documentation](https://playwright.dev)

package/docs/gherkin standards/gherkin-core-standard.md

@@ -1,4 +1,4 @@
-# Gherkin Standard - Core (Final)
+# Gherkin Standard - Core (v2)
 
 **Applies to: Manual Testing & Automation Testing**
 
@@ -36,13 +36,14 @@ Scenario: User logs in successfully with valid credentials
 
 ### Format
 ```
-<Actor> <Action> [<Target>] with {{<Value>}}
+[Keyword] User <Action> [<Target>] <Target Type> <with {{Value}}> <is State>
 ```
 
 ### Rules
 - ✅ `Actor` + `Action` are **mandatory**
-- ✅ `Target` is **required** for most actions (except `open` / `wait for`)
+- ✅ `Target` is **required** for most actions (except `wait for N seconds`)
 - ✅ `with {{Value}}` only used when action requires data
+- ✅ `is State` only used for assertions and wait conditions
 - ❌ No free-text variations
 - ❌ No synonyms
 
@@ -54,6 +55,7 @@ Scenario: User logs in successfully with valid credentials
 | Action | ✅ Always | `click`, `fill`, `see` |
 | Target | ✅ Most cases | `[Login] button` |
 | Value | ⚠️ When needed | `{{valid_email}}` |
+| State | ⚠️ Assertions only | `is disabled` |
 
 ---
 
@@ -82,31 +84,41 @@ Scenario: User logs in successfully with valid credentials
 
 ## 4️⃣ Action
 
-### Allowed Actions (7 only)
-
-| Action | Use Case | Example |
-|--------|----------|---------|
-| `is on` | Navigate to page (preferred) | `User is on [Login] page` |
-| `open` | Navigate to page/screen | `User open [Login] page` |
-| `click` | Click button/link/element | `User click [Submit] button` |
-| `fill` | Enter text in input field | `User fill [Email] field with {{email}}` |
-| `select` | Choose option from dropdown/radio | `User select [Country] dropdown with {{country}}` |
-| `wait for` | Wait for element/condition | `User wait for [Loader] icon` |
-| `see` | Verify element visibility | `User see [Error] message` |
-
-> **Note**: `is on` and `open` are interchangeable for navigation. `is on` is the preferred form for `Given` steps.
+### Allowed Actions
+
+| Group | Action | Use Case | Example |
+|-------|--------|----------|---------|
+| **Setup** | `is on` | Navigate to page/dialog | `User is on [Login] page` |
+| **Setup** | `navigate to` | Navigate with data | `User navigate to [Profile] page with {{user_id}}` |
+| **Interaction** | `click` | Click button/link/element | `User click [Submit] button` |
+| **Interaction** | `double click` | Double click element | `User double click [Cell] element` |
+| **Interaction** | `hover` | Hover over element | `User hover [Info] icon` |
+| **Interaction** | `drag` | Drag to destination | `User drag [Card] to [Column]` |
+| **Form** | `fill` | Enter text in field | `User fill [Email] field with {{email}}` |
+| **Form** | `clear` | Clear field content | `User clear [Search] field` |
+| **Form** | `select` | Choose from dropdown | `User select [Country] dropdown with {{country}}` |
+| **Form** | `check` | Check checkbox | `User check [Remember me] checkbox` |
+| **Form** | `uncheck` | Uncheck checkbox | `User uncheck [Newsletter] checkbox` |
+| **Form** | `toggle` | Toggle switch | `User toggle [Dark mode] switch` |
+| **Form** | `upload` | Upload file | `User upload [Avatar] file with {{path}}` |
+| **Keyboard** | `press` | Press key (global or on element) | `User press Enter on [Search] field` |
+| **Scroll** | `scroll to` | Scroll element into view | `User scroll to [Footer] section` |
+| **Frame** | `switch to` | Enter/exit iframe | `User switch to [Payment] frame` |
+| **Expand** | `expand` / `collapse` | Expand/collapse row | `User expand [Row 1] row` |
+| **Wait** | `wait for` | Wait for element/timeout | `User wait for [Loading] spinner is hidden` |
+| **Assertion** | `see` | Verify visibility/state/text | `User see [Error] message` |
 
 ### Rules
 - ✅ Use **exact verbs** from the list above
-- ❌ No synonyms: `type`, `enter`, `input`, `press`, `check`, `verify`, `expect`, etc.
+- ❌ No synonyms: `type`, `enter`, `input`, `verify`, `expect`, `open`, etc.
 - ❌ No compound actions: `click and wait`, `fill and submit`
 
 ### Anti-patterns
 ```gherkin
-❌ User types {{password}} into [Password] field
-❌ User presses [Enter] key
-❌ User checks [Terms] checkbox
-❌ User verifies [Success] message appears
+❌ User types {{password}} into [Password] field     → use "fill"
+❌ User opens [Home] page                            → use "is on"
+❌ User checks [Terms] checkbox                      → use "check" (no "s")
+❌ User verifies [Success] message appears            → use "see"
 ```
 
 ---
@@ -122,16 +134,32 @@ Scenario: User logs in successfully with valid credentials
 
 | Element Type | When to Use | Example |
 |--------------|-------------|---------|
-| `field` | Text input, textarea | `[Email] field`, `[Password] field` |
-| `button` | Clickable button | `[Submit] button`, `[Cancel] button` |
+| `page` | Entire screen/page | `[Login] page` |
+| `button` | Clickable button | `[Submit] button` |
+| `link` | Hyperlink | `[Forgot password] link` |
+| `field` | Text input | `[Email] field` |
+| `textarea` | Text area / rich editor | `[Message] textarea` |
+| `heading` | Heading element | `[Welcome] heading` |
+| `text` | Text content | `[Price] text` |
 | `checkbox` | Checkbox input | `[Remember me] checkbox` |
-| `dropdown` | Select element | `[Country] dropdown` |
 | `radio` | Radio button | `[Payment method] radio` |
-| `link` | Hyperlink | `[Forgot password] link` |
-| `message` | Alert/notification | `[Error] message`, `[Success] message` |
-| `page` | Entire screen/page | `[Login] page`, `[Dashboard] page` |
-| `icon` | Visual icon/image | `[Loader] icon`, `[Close] icon` |
-| `label` | Text label | `[Username] label` |
+| `switch` | Toggle switch | `[Dark mode] switch` |
+| `dropdown` | Select / combobox | `[Country] dropdown` |
+| `dialog` / `modal` | Modal / dialog overlay | `[Confirm] dialog` |
+| `menu` / `menuitem` | Menu elements | `[Write Kudos] menuitem` |
+| `tab` / `tabpanel` | Tab elements | `[Settings] tab` |
+| `table` / `row` / `cell` | Table elements | `[Users] table` |
+| `list` / `listitem` | List elements | `[Results] list` |
+| `icon` / `image` | Visual icon/image | `[Close] icon` |
+| `alert` | Alert/notification | `[Error] alert` |
+| `spinner` / `progressbar` | Loading indicators | `[Loading] spinner` |
+| `section` / `region` / `nav` | Layout landmarks | `[Footer] section` |
+| `frame` / `iframe` | Iframe elements | `[Payment] frame` |
+| `uploader` / `file` | File upload | `[Avatar] uploader` |
+| `columnheader` | Table column header | `[Name] columnheader` |
+| `tooltip` | Tooltip | `[Help] tooltip` |
+| `slider` | Slider/range | `[Volume] slider` |
+| `tree` / `treeitem` | Tree elements | `[Folder] treeitem` |
 
 ### Rules
 - ✅ Use **business/UI meaningful names**, not technical selectors
@@ -144,8 +172,8 @@ Scenario: User logs in successfully with valid credentials
 ```gherkin
 ✅ User click [Login] button
 ✅ User fill [Email address] field with {{email}}
-✅ User select [United States] dropdown
-✅ User see [Welcome back] message
+✅ User select [Country] dropdown with {{country}}
+✅ User see [Welcome back] heading
 
 ❌ User click [#submit-btn] button
 ❌ User fill [input.email-field] field
@@ -209,8 +237,8 @@ expired_otp: "000000"
 ```gherkin
 ✅ Then User see [Error] message
 ✅ And User see [Dashboard] page
-✅ And User see [Welcome] text
-✅ And User see [Logout] button
+✅ And User see [Welcome] heading with {{username}}
+✅ And User see [Submit] button is disabled
 
 ❌ Then User verifies [Error] message
 ❌ Then System displays [Dashboard] page
@@ -222,55 +250,41 @@ expired_otp: "000000"
 | Pattern | Use Case | Example |
 |---------|----------|---------|
 | Simple visibility | Element is visible | `User see [Login] button` |
-| Visibility with value | Element contains specific text | `User see [Welcome] text with {{username}}` |
-| Hidden state | Element is hidden | `User see [panel] dialog with {{title}} is hidden` |
-| Hidden (no value) | Element is hidden | `User see [Modal] dialog is hidden` |
-| Page/state verification | Confirm navigation | `User see [Dashboard] page` |
-| Message verification | Confirm feedback | `User see [Error] message` |
-| Wait for hidden | Wait until element disappears | `User wait for dialog with {{title}} is hidden` |
+| Visibility with value | Element has specific text | `User see [Welcome] heading with {{username}}` |
+| State assertion | Element state | `User see [Submit] button is disabled` |
+| State with value | Element with text + state | `User see [Panel] dialog with {{title}} is hidden` |
+| Text contains | Partial text match | `User see [Message] text contains {{partial}}` |
+| Text has text | Exact text match | `User see [Counter] text has text {{count}}` |
+| Has attribute | Attribute check | `User see [Avatar] image has {{avatar_url}}` |
 
 ### State Modifiers
 
-Append `is hidden` to any `see` or `wait for` step to assert/wait for an element to be hidden:
-
-```gherkin
-✅ Then User see [panel] dialog with {{title}} is hidden
-✅ And User wait for dialog with {{title}} is hidden
-```
-
----
-
-## 📋 Complete Example
-
-```gherkin
-Feature: User Authentication
-  Path: /auth/login
-
-  Scenario: User logs in successfully with valid credentials
-    Given User is on [Login] page
-    When User fill [Email] field with {{valid_email}}
-    And User fill [Password] field with {{valid_password}}
-    And User click [Remember me] checkbox
-    And User click [Submit] button
-    Then User see [Dashboard] page
-    And User see [Welcome] message with {{username}}
-
-  Scenario: User fails to login with invalid credentials
-    Given User is on [Login] page
-    When User fill [Email] field with {{invalid_email}}
-    And User fill [Password] field with {{invalid_password}}
-    And User click [Submit] button
-    Then User see [Error] message
-    And User see [Login] page
-
-  Scenario: User selects preferred language during registration
-    Given User is on [Registration] page
-    When User fill [Email] field with {{new_email}}
-    And User fill [Password] field with {{new_password}}
-    And User select [Language] dropdown with {{preferred_language}}
-    And User click [Sign up] button
-    Then User see [Verification] page
-```
+| State | Assertion |
+|-------|-----------|
+| `hidden` | Element is not visible |
+| `visible` | Element is visible |
+| `disabled` | Element is disabled |
+| `enabled` | Element is enabled |
+| `checked` | Checkbox/radio is checked |
+| `unchecked` | Checkbox/radio is unchecked |
+| `focused` | Element has focus |
+| `empty` | Element has no text |
+| `loading` | Loading indicator is visible |
+| `selected` | Element is selected |
+| `sorted ascending` | Column sorted ascending |
+| `sorted descending` | Column sorted descending |
+
+### Table Assertions
+
+| Pattern | Example |
+|---------|---------|
+| Row exists | `User see [Users] table row with {{name}} has [Status] with {{status}}` |
+| No row | `User see [Users] table has no row with {{name}}` |
+| Row count | `User see [Users] table has {{count}} rows` |
+| Column exists | `User see [Users] table has [Email] column` |
+| Cell by index | `User see [Users] table row 1 [Name] cell with {{name}}` |
+| Empty table | `User see [Users] table is empty` |
+| Action in row | `User click [Edit] in [Users] table row with {{name}}` |
 
 ---
 
@@ -309,10 +323,8 @@ Scenario: User sends a thank you message
   And User fill [Search] field with {{teammate_name}}
   And User click [teammate] row with {{teammate_name}}
   And User fill [Title] field with {{teammate_title}}
-  And User fill [Message] textarea 2 with {{teammate_message}}
-  And User click [Hashtag] tag with {{hashtag_1}}
   And User click [Send] button
-  And User wait for dialog with {{kudo_title}} is hidden
+  And User wait for [panel] dialog with {{kudo_title}} is hidden
   Then User see [panel] modal with {{kudo_title}} is hidden
 ```
 
@@ -332,13 +344,51 @@ Scenario: User sends a thank you message
 
 ---
 
+## 📋 Complete Example
+
+```gherkin
+@auth:user
+Feature: User Authentication
+  Path: /auth/login
+
+  Scenario: User logs in successfully with valid credentials
+    Given User is on [Login] page
+    When User fill [Email] field with {{valid_email}}
+    And User fill [Password] field with {{valid_password}}
+    And User check [Remember me] checkbox
+    And User click [Submit] button
+    Then User see [Dashboard] page
+    And User see [Welcome] heading with {{username}}
+
+  Scenario: User fails to login with invalid credentials
+    Given User is on [Login] page
+    When User fill [Email] field with {{invalid_email}}
+    And User fill [Password] field with {{invalid_password}}
+    And User click [Submit] button
+    Then User see [Error] alert
+    And User see [Login] page
+    And User see [Submit] button is enabled
+
+  Scenario: User selects preferred language during registration
+    Given User is on [Registration] page
+    When User fill [Email] field with {{new_email}}
+    And User fill [Password] field with {{new_password}}
+    And User select [Language] dropdown with {{preferred_language}}
+    And User check [Terms] checkbox
+    And User click [Sign up] button
+    Then User see [Verification] page
+```
+
+---
+
 ## ✅ Quick Reference
 
 ### Do's ✅
-- Use **standard 6 actions**: open, click, fill, select, wait for, see
+- Use **standard actions** from section 4
 - Use **`User`** as the only actor
 - Use **`[Target] <element type>`** format
 - Use **`{{snake_case}}`** for values
+- Use **`is <state>`** for state assertions
 - **1 Scenario = 1 business flow**
 - **1 Step = 1 action or assertion**
 
@@ -349,6 +399,7 @@ Scenario: User sends a thank you message
 - No hard-coded data in steps
 - No compound actions
 - No `verify`/`check`/`expect` (use `see`)
+- No `open` (use `is on`)
 
 ---
 
@@ -359,19 +410,19 @@ Scenario: User sends a thank you message
 | **Consistency** | Same patterns across all test cases |
 | **Readability** | Non-technical stakeholders can understand |
 | **Maintainability** | Easy to update when UI changes |
-| **Automation-Ready** | Direct mapping to code patterns |
+| **Automation-Ready** | Direct mapping to Playwright code via 17 pattern shapes |
 | **No Ambiguity** | Single interpretation per step |
-| **Tool Support** | Compatible with Sungen framework |
+| **Tool Support** | Compatible with Sungen v2 compiler |
 
 ---
 
 ## 📚 Related Documentation
-- [Selector Override Guide](selector-override.md) - Customize element selectors
-- [Validation Guide](validate.md) - Validate Gherkin files
-- [Auth Setup](makeauth.md) - Configure authentication states
+- [Gherkin Dictionary](../gherkin-dictionary.md) — Full grammar, all 17 patterns, compiler rules
+- [Sungen GitHub](https://github.com/sun-asterisk/sungen)
+- [Playwright Documentation](https://playwright.dev)
 
 ---
 
-**Version**: 1.1
+**Version**: 2.0
 **Status**: Final
-**Last Updated**: March 11, 2026
+**Last Updated**: March 19, 2026