@sun-asterisk/sungen 2.2.1 → 2.2.3

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

@@ -1,4 +1,4 @@
-# Gherkin Standard - Core (v2)
+# Gherkin Standard - Core (v2.1)
 
 **Applies to: Manual Testing & Automation Testing**
 
@@ -15,28 +15,42 @@ Scenario: <Who> <Does What> <For What Result>
 ```
 
 ### Principles
-- **1 Scenario = 1 complete business behavior**
-- **Given**: Initial state / preconditions
-- **When**: Main action (trigger)
-- **Then**: Observable result (assertion)
+- **Independent**: 1 Scenario = 1 complete business behavior (no shared data between scenarios)
+- **Behavioral**: Describe "User does what" and "sees what" — focus on user behavior
+- **Objective**: Describe business outcomes. No technical details (CSS, XPath)
+
+### Flow
+**Past (Setup) → Present (Interaction) → Future (Result)**
 
-### Example
 ```gherkin
 Scenario: User logs in successfully with valid credentials
+  # 1. Setup
   Given User is on [Login] page
+  # 2. Interaction
   When User fill [Email] field with {{valid_email}}
   And User fill [Password] field with {{valid_password}}
   And User click [Submit] button
+  # 3. Result
   Then User see [Dashboard] page
+  And User see [Welcome] heading with {{username}}
+  And User see [Logout] button is enabled
 ```
 
+### Keyword Rules
+- **Given** → `is on` only (setup context)
+- **When / And** → `click`, `fill`, `select`, `press`, `clear`, `check`, `uncheck`, `hover`, `wait for`
+- **Then / And** → `see` only (assertions)
+- **And** → inherits from preceding keyword
+
+> Max 5–7 `Then/And` assertions per scenario. Split into separate scenarios if more needed.
+
 ---
 
 ## 2️⃣ Grammar (Step Level)
 
 ### Format
 ```
-[Keyword] User <Action> [<Target>] <Target Type> <with {{Value}}> <is State>
+[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
 ```
 
 ### Rules
@@ -75,38 +89,36 @@ Scenario: User logs in successfully with valid credentials
 ✅ User click [Submit] button
 ❌ System sends verification email
 ❌ Backend validates password
-❌ API returns success response
 ```
 
-> **Rationale**: System behavior is an *outcome* to verify, not an actor performing steps.
-
 ---
 
 ## 4️⃣ Action
 
-### 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` |
+### Action Matrix
+
+| Group | Action | `with {{Value}}` | `is State` | Target Types |
+|-------|--------|:-:|:-:|---|
+| **Setup** | `is on` | ❌ | ❌ | `page`, `dialog`, `modal`, `tab` |
+| **Interaction** | `click` | Only dynamic lists ✱ | ❌ | All interactive elements |
+| **Interaction** | `double click` | ❌ | ❌ | Any element |
+| **Interaction** | `hover` | ❌ | ❌ | `icon`, `image`, `row`, `card`, `menuitem` |
+| **Interaction** | `drag` | ❌ | ❌ | Any to any |
+| **Interaction** | `expand` / `collapse` | ❌ | ❌ | `row`, `section` |
+| **Form** | `fill` | ✅ | ❌ | `field`, `textarea`, `search`, `uploader`, `slider`, `date-picker` |
+| **Form** | `select` | ✅ | ❌ | `dropdown`, `select`, `option` |
+| **Form** | `clear` | ❌ | ❌ | `field`, `textarea` |
+| **Form** | `check` | ❌ | ❌ | `checkbox`, `toggle`, `radio` |
+| **Form** | `uncheck` | ❌ | ❌ | `checkbox`, `toggle` (NOT radio) |
+| **Keyboard** | `press` | ❌ | ❌ | `key` (mandatory) |
+| **Scroll** | `scroll to` | ❌ | ❌ | `section`, any element |
+| **Frame** | `switch to` | ❌ | ❌ | `frame` |
+| **Wait** | `wait for` | ⚠️ Optional | ⚠️ Optional | `page`, `dialog`, `modal`, `message`, any element |
+| **Assertion** | `see` | ✅ | ✅ | All types |
+| **Alert** | `click` | ❌ | ❌ | `alert` (OK/Cancel) |
+| **Alert** | `fill` | ✅ | ❌ | `alert` (prompt) |
+
+> ✱ **`click` + `with {{Value}}`**: Only for dynamic lists (`row`, `item`, `card`, `option`). Never for static elements (`button`, `link`, `icon`, `tab`).
 
 ### Rules
 - ✅ Use **exact verbs** from the list above
@@ -119,6 +131,8 @@ Scenario: User logs in successfully with valid credentials
 ❌ User opens [Home] page                            → use "is on"
 ❌ User checks [Terms] checkbox                      → use "check" (no "s")
 ❌ User verifies [Success] message appears            → use "see"
+❌ User click [Terms] checkbox                       → use "check", not "click"
+❌ User uncheck [Male] radio                         → radio cannot uncheck, use "check [Female] radio"
 ```
 
 ---
@@ -132,41 +146,23 @@ Scenario: User logs in successfully with valid credentials
 
 ### Element Types
 
-| Element Type | When to Use | Example |
-|--------------|-------------|---------|
-| `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` |
-| `radio` | Radio button | `[Payment method] radio` |
-| `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` |
+| Group | Types | Example |
+|---|---|---|
+| **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` | `[Login] page`, `[Confirm] dialog` |
+| **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` | `[Email] field`, `[Global] search` |
+| **Trigger** | `button` `link` `icon` `menuitem` `tag` | `[Submit] button`, `[Close] icon` |
+| **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` | `[Users] table`, `[Order] row` |
+| **Feedback** | `message` `header` `label` `text` `tooltip` `badge` `breadcrumb` `image` | `[Error] message`, `[Total] label` |
+| **System** | `key` `frame` `spinner` `progressbar` | `[Enter] key`, `[Payment] frame` |
 
-### Rules
+### Naming Rules
 - ✅ Use **business/UI meaningful names**, not technical selectors
-- ✅ Keep names **simple and descriptive**
+- ✅ Visible text → use exact UI label: `[Đăng nhập] button`
+- ✅ No visible text → short descriptive noun: `[close] icon`
+- ✅ Name > 30 chars → shorten to 1–3 meaningful words
 - ❌ No CSS selectors: `#email`, `.btn-primary`
 - ❌ No XPath: `//input[@id='email']`
-- ❌ No IDs: `email-input`, `submit-btn-123`
+- ❌ No element type in brackets: `[login button]` → `[login] button`
 
 ### Examples
 ```gherkin
@@ -198,7 +194,6 @@ Scenario: User logs in successfully with valid credentials
 - ✅ Name reflects **data purpose**, not data content
 - ❌ No hard-coded data in steps
 - ❌ No real data (emails, passwords, tokens)
-- ❌ No environment-specific values (URLs, API keys)
 
 ### Examples
 
@@ -207,18 +202,8 @@ Scenario: User logs in successfully with valid credentials
 | `{{valid_email}}` | `{{user@example.com}}` |
 | `{{invalid_password}}` | `{{123456}}` |
 | `{{expired_otp}}` | `{{999999}}` |
-| `{{admin_username}}` | `{{admin}}` |
 | `{{product_name}}` | `{{iPhone 15 Pro}}` |
 
-### Data Organization
-```yaml
-# test-data/login.yaml
-valid_email: "user@example.com"
-valid_password: "SecurePass123!"
-invalid_email: "not-an-email"
-expired_otp: "000000"
-```
-
 ---
 
 ## 7️⃣ Assertion
@@ -226,36 +211,19 @@ expired_otp: "000000"
 ### Verb
 - **Only**: `see`
 
-### Rules
-- ✅ Assertions **only appear in `Then`** steps
-- ✅ Verify **system state / output**
-- ✅ Each step = **1 assertion**
-- ❌ Do not describe user actions
-- ❌ No synonyms: `verify`, `expect`, `check`, `observe`, `validate`
-
-### Examples
-```gherkin
-✅ Then User see [Error] message
-✅ And User see [Dashboard] page
-✅ And User see [Welcome] heading with {{username}}
-✅ And User see [Submit] button is disabled
-
-❌ Then User verifies [Error] message
-❌ Then System displays [Dashboard] page
-❌ Then [Success] message appears
-```
+### 7 Verify Patterns
 
-### Assertion Patterns
+| # | Pattern | Assertion | Example |
+|---|---------|-----------|---------|
+| 1 | **Visibility** | `toBeVisible()` / `toBeHidden()` | `see [Success] message` / `see [Ads] modal is hidden` |
+| 2 | **Text Content** | `toHaveText()` (exact match) | `see [Error] message with {{err_msg}}` |
+| 3 | **Partial Text** | `toContainText()` | `see [Title] heading contains {{text}}` |
+| 4 | **Input Value** | `toHaveValue()` | `see [Email] field with {{user_email}}` |
+| 5 | **Component State** | `toBeDisabled()` / `toBeChecked()` etc. | `see [Submit] button is disabled` |
+| 6 | **Count** | `toHaveCount()` | `see [Result] row with {{result_count}}` |
+| 7 | **Page Context** | `toHaveURL()` | `see [Dashboard] page` |
 
-| Pattern | Use Case | Example |
-|---------|----------|---------|
-| Simple visibility | Element is visible | `User see [Login] button` |
-| 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}}` |
+> **Key distinction**: `see [T] <input type> with {{v}}` → `toHaveValue()` for inputs (field, textarea, search, dropdown, slider, date-picker). `see [T] <other type> with {{v}}` → `toHaveText()` for everything else.
 
 ### State Modifiers
 
@@ -265,74 +233,108 @@ expired_otp: "000000"
 | `visible` | Element is visible |
 | `disabled` | Element is disabled |
 | `enabled` | Element is enabled |
-| `checked` | Checkbox/radio is checked |
-| `unchecked` | Checkbox/radio is unchecked |
+| `checked` | Checkbox/radio/toggle is checked |
+| `unchecked` | Checkbox/radio/toggle is unchecked |
 | `focused` | Element has focus |
-| `empty` | Element has no text |
+| `empty` | Element has no text/value |
 | `loading` | Loading indicator is visible |
 | `selected` | Element is selected |
 | `sorted ascending` | Column sorted ascending |
 | `sorted descending` | Column sorted descending |
 
+### Combined Value + State
+```gherkin
+# Value and state can be combined:
+Then User see [Ads] modal with {{promo_title}} is hidden
+```
+
 ### Table Assertions
 
 | Pattern | Example |
 |---------|---------|
-| Row exists | `User see [Users] table row with {{name}} has [Status] with {{status}}` |
+| Row exists | `User see [Users] table has row with {{name}}` |
 | 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` |
+| Cell by filter | `User see [Users] table row with {{filter}} has [Status] with {{status}}` |
+| Cell by index | `User see [Users] table row 1 [Name] cell with {{name}}` |
 | Action in row | `User click [Edit] in [Users] table row with {{name}}` |
 
+### Rules
+- ✅ Assertions **only appear in `Then`** steps
+- ✅ Verify **system state / output**
+- ✅ Each step = **1 assertion**
+- ❌ No synonyms: `verify`, `expect`, `check`, `observe`, `validate`
+
+---
+
+## 8️⃣ Browser Alert (System Dialog)
+
+For native browser dialogs (`window.alert`, `window.confirm`, `window.prompt`):
+
+```gherkin
+# Alert steps must appear BEFORE the action that triggers the dialog
+When User click [OK] alert              # accept (OK/Accept/Yes/Confirm)
+And User click [Delete] button           # this triggers the alert
+
+When User click [Cancel] alert           # dismiss (Cancel/Dismiss/No)
+And User click [Delete] button
+
+When User fill [Name] alert with {{v}}   # fill prompt + accept
+And User click [Rename] button
+```
+
+> **Important**: Register the dialog handler BEFORE the triggering action. Sungen generates `page.once('dialog', ...)` for these steps.
+
 ---
 
 ## 🏷️ Tags
 
-### Scenario Tags
+### Classification Tags
+
+| Tag | Description |
+|-----|-------------|
+| `@auto` | Standard scenario, ready for automation |
+| `@manual` | Skip scenario from generation |
+| `@smoke` | Smoke test suite |
+| `@regression` | Regression test suite |
+
+### Authentication Tags
 
 | Tag | Description |
 |-----|-------------|
 | `@auth:<role>` | Use Playwright auth storage state for the given role |
 | `@no-auth` | Disable inherited authentication |
-| `@steps:<name>` | Mark scenario as a reusable step block |
-| `@extend:<name>` | Prepend steps from a `@steps` block before own steps |
-| `@manual` | Skip scenario from generation |
 
 Tags can be applied at **feature level** (inherited by all scenarios) or **scenario level** (overrides feature).
 
 **Auth precedence**: Extending scenario `@auth` > Base scenario `@auth` > Feature `@auth`
 
-### Reusable Steps (@steps / @extend)
+### Inheritance Tags (@steps / @extend)
 
 Use `@steps:<name>` to define a reusable block and `@extend:<name>` to inherit those steps:
 
 ```gherkin
-@auth:user @steps:open-dialog
-Scenario: Open kudos dialog
-  Given User is on [kudo] page
-  When User click [Notifications] button
-  And User click [Write Kudos] menuitem
-  Then User see [panel] dialog with {{kudo_title}}
-
-@auth:user @extend:open-dialog
-Scenario: User sends a thank you message
-  Given User is on [panel] dialog with {{kudo_title}}
-  When User click [Search] button
-  And User fill [Search] field with {{teammate_name}}
-  And User click [teammate] row with {{teammate_name}}
-  And User fill [Title] field with {{teammate_title}}
+@auto @auth:user @steps:kudos__open_modal
+Scenario: Setup for opening Kudos modal
+  Given User is on [Home] page
+  When User click [Today you want...] button
+  Then User see [Send thanks] dialog    # ← skipped when @extend calls
+
+@auto @auth:user @extend:kudos__open_modal
+Scenario: User successfully sends a thank you message
+  Given User is on [Send thanks] dialog  # ← required: verify state after extend
+  When User fill [Search teammate] field with {{teammate_name}}
   And User click [Send] button
-  And User wait for [panel] dialog with {{kudo_title}} is hidden
-  Then User see [panel] modal with {{kudo_title}} is hidden
+  Then User see [Success] message with {{msg_success}}
 ```
 
 **Behavior:**
-- `@steps` scenarios generate their own test AND register steps for reuse
-- `@extend` scenarios get base steps prepended inline — fully self-contained test
-- Multiple scenarios can extend the same `@steps` block
-- Generated code includes section comments: `// [from @steps:<name>]`
+- `@extend` executes **only Given→When** of `@steps` scenario (skips Then)
+- The `Given` in `@extend` scenario is the **entry assertion** — confirms state after base steps ran
+- If `@steps` scenario **fails**, `@extend` scenario is **automatically skipped**
+- Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`, `@steps:cart__add_item`
 
 ### Step-Level Annotations (comment syntax)
 
@@ -340,17 +342,18 @@ Scenario: User sends a thank you message
 |-----------|--------|
 | `# @ignore` | Skip this step in generation |
 | `# @ignore-testcase` | Skip entire scenario in generation |
-| `# @skip-production` | Skip step in production environment |
 
 ---
 
 ## 📋 Complete Example
 
 ```gherkin
-@auth:user
+@feature_auth
 Feature: User Authentication
   Path: /auth/login
 
+  # Happy Path
+  @auto @smoke @regression
   Scenario: User logs in successfully with valid credentials
     Given User is on [Login] page
     When User fill [Email] field with {{valid_email}}
@@ -359,17 +362,22 @@ Feature: User Authentication
     And User click [Submit] button
     Then User see [Dashboard] page
     And User see [Welcome] heading with {{username}}
+    And User see [Logout] button is enabled
 
-  Scenario: User fails to login with invalid credentials
+  # Error Path
+  @auto @regression
+  Scenario: Login fails 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
+    Then User see [Login] page
+    And User see [Login error] message with {{err_invalid_credentials}}
     And User see [Submit] button is enabled
 
-  Scenario: User selects preferred language during registration
+  # Registration with form controls
+  @auto @regression
+  Scenario: User registers with preferred language
     Given User is on [Registration] page
     When User fill [Email] field with {{new_email}}
     And User fill [Password] field with {{new_password}}
@@ -384,11 +392,12 @@ Feature: User Authentication
 ## ✅ Quick Reference
 
 ### Do's ✅
-- Use **standard actions** from section 4
+- Use **standard actions** from the action matrix
 - Use **`User`** as the only actor
 - Use **`[Target] <element type>`** format
 - Use **`{{snake_case}}`** for values
 - Use **`is <state>`** for state assertions
+- Use **tags** (`@auth`, `@steps`, `@extend`) for scenario management
 - **1 Scenario = 1 business flow**
 - **1 Step = 1 action or assertion**
 
@@ -400,29 +409,23 @@ Feature: User Authentication
 - No compound actions
 - No `verify`/`check`/`expect` (use `see`)
 - No `open` (use `is on`)
+- No `click` on checkbox/toggle (use `check`/`uncheck`)
+- No `uncheck` on radio (use `check` on another option)
 
----
-
-## 🎯 Benefits
-
-| Benefit | Description |
-|---------|-------------|
-| **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 Playwright code via 17 pattern shapes |
-| **No Ambiguity** | Single interpretation per step |
-| **Tool Support** | Compatible with Sungen v2 compiler |
-
----
+### Common Errors
 
-## 📚 Related Documentation
-- [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)
+| ❌ Wrong | ✅ Correct | Reason |
+|---|---|---|
+| `Given User click [Login] button` | `When User click [Login] button` | `click` belongs to WHEN |
+| `When User click [Terms] checkbox` | `When User check [Terms] checkbox` | Use `check` for checkbox |
+| `When User press [Submit] button` | `When User press [Enter] key` | `press` only with `key` |
+| `When User uncheck [Male] radio` | `When User check [Female] radio` | Radio cannot uncheck |
+| `fill [email] with {{admin@mail}}` | `fill [email] field with {{admin_email}}` | No hardcode + missing type |
+| `see [msg] with {{text}} hidden` | `see [msg] with {{text}} is hidden` | Missing `is` keyword |
+| `see [btn] button with {{disabled}}` | `see [btn] button is disabled` | State uses `is`, not `{{}}` |
 
 ---
 
-**Version**: 2.0
+**Version**: 2.1
 **Status**: Final
-**Last Updated**: March 19, 2026
+**Last Updated**: March 31, 2026