@sun-asterisk/sungen 2.2.3 → 2.3.0

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

@@ -1,431 +0,0 @@
-# Gherkin Standard - Core (v2.1)
-
-**Applies to: Manual Testing & Automation Testing**
-
----
-
-## 1️⃣ Scenario Format (Flow Level)
-
-### Format
-```gherkin
-Scenario: <Who> <Does What> <For What Result>
-  Given ...
-  When ...
-  Then ...
-```
-
-### Principles
-- **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)**
-
-```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 Name] <Target Type> <with {{Value}}> <is State>
-```
-
-### Rules
-- ✅ `Actor` + `Action` are **mandatory**
-- ✅ `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
-
-### Structure Breakdown
-
-| Component | Required | Example |
-|-----------|----------|---------|
-| Actor | ✅ Always | `User` |
-| Action | ✅ Always | `click`, `fill`, `see` |
-| Target | ✅ Most cases | `[Login] button` |
-| Value | ⚠️ When needed | `{{valid_email}}` |
-| State | ⚠️ Assertions only | `is disabled` |
-
----
-
-## 3️⃣ Actor
-
-### Allowed Actor
-- ✅ **`User`** (only)
-
-### Rules
-- **Only use**: `User`
-- **Do NOT use**: `System`, `Backend`, `API`, `App`
-- System behavior is verified using `Then`, not as an Actor
-
-### Examples
-```gherkin
-✅ User is on [Login] page
-✅ User click [Submit] button
-❌ System sends verification email
-❌ Backend validates password
-```
-
----
-
-## 4️⃣ Action
-
-### 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
-- ❌ 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     → use "fill"
-❌ 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"
-```
-
----
-
-## 5️⃣ Target
-
-### Format
-```
-[name] <element type>
-```
-
-### Element Types
-
-| 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` |
-
-### Naming Rules
-- ✅ Use **business/UI meaningful names**, not technical selectors
-- ✅ 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 element type in brackets: `[login button]` → `[login] button`
-
-### Examples
-```gherkin
-✅ User click [Login] button
-✅ User fill [Email address] field with {{email}}
-✅ User select [Country] dropdown with {{country}}
-✅ User see [Welcome back] heading
-
-❌ User click [#submit-btn] button
-❌ User fill [input.email-field] field
-❌ User see [div.alert-success] message
-```
-
----
-
-## 6️⃣ Value
-
-### Format
-```
-{{value}}
-```
-
-### Naming Convention
-- **snake_case** (lowercase with underscores)
-- Descriptive and context-aware
-
-### Rules
-- ✅ Use `{{variable}}` syntax
-- ✅ Name reflects **data purpose**, not data content
-- ❌ No hard-coded data in steps
-- ❌ No real data (emails, passwords, tokens)
-
-### Examples
-
-| ✅ Good | ❌ Bad |
-|--------|-------|
-| `{{valid_email}}` | `{{user@example.com}}` |
-| `{{invalid_password}}` | `{{123456}}` |
-| `{{expired_otp}}` | `{{999999}}` |
-| `{{product_name}}` | `{{iPhone 15 Pro}}` |
-
----
-
-## 7️⃣ Assertion
-
-### Verb
-- **Only**: `see`
-
-### 7 Verify 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` |
-
-> **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
-
-| State | Assertion |
-|-------|-----------|
-| `hidden` | Element is not visible |
-| `visible` | Element is visible |
-| `disabled` | Element is disabled |
-| `enabled` | Element is enabled |
-| `checked` | Checkbox/radio/toggle is checked |
-| `unchecked` | Checkbox/radio/toggle is unchecked |
-| `focused` | Element has focus |
-| `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 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` |
-| 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
-
-### 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 |
-
-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`
-
-### Inheritance Tags (@steps / @extend)
-
-Use `@steps:<name>` to define a reusable block and `@extend:<name>` to inherit those steps:
-
-```gherkin
-@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
-  Then User see [Success] message with {{msg_success}}
-```
-
-**Behavior:**
-- `@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)
-
-| Annotation | Effect |
-|-----------|--------|
-| `# @ignore` | Skip this step in generation |
-| `# @ignore-testcase` | Skip entire scenario in generation |
-
----
-
-## 📋 Complete Example
-
-```gherkin
-@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}}
-    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}}
-    And User see [Logout] button is enabled
-
-  # 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 [Login] page
-    And User see [Login error] message with {{err_invalid_credentials}}
-    And User see [Submit] button is enabled
-
-  # 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}}
-    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 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**
-
-### Don'ts ❌
-- No synonyms or free-text variations
-- No system/backend/API as actors
-- No technical selectors (CSS/XPath/ID)
-- No hard-coded data in steps
-- 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)
-
-### Common Errors
-
-| ❌ 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.1
-**Status**: Final
-**Last Updated**: March 31, 2026