@sun-asterisk/sungen 2.2.2 → 2.3.0

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

@@ -1,428 +0,0 @@
-# Gherkin Standard - Core (v2)
-
-**Applies to: Manual Testing & Automation Testing**
-
----
-
-## 1️⃣ Scenario Format (Flow Level)
-
-### Format
-```gherkin
-Scenario: <Who> <Does What> <For What Result>
-  Given ...
-  When ...
-  Then ...
-```
-
-### Principles
-- **1 Scenario = 1 complete business behavior**
-- **Given**: Initial state / preconditions
-- **When**: Main action (trigger)
-- **Then**: Observable result (assertion)
-
-### Example
-```gherkin
-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 [Submit] button
-  Then User see [Dashboard] page
-```
-
----
-
-## 2️⃣ Grammar (Step Level)
-
-### Format
-```
-[Keyword] User <Action> [<Target>] <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
-❌ 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` |
-
-### 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"
-```
-
----
-
-## 5️⃣ Target
-
-### Format
-```
-[name] <element type>
-```
-
-### 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` |
-
-### Rules
-- ✅ Use **business/UI meaningful names**, not technical selectors
-- ✅ Keep names **simple and descriptive**
-- ❌ No CSS selectors: `#email`, `.btn-primary`
-- ❌ No XPath: `//input[@id='email']`
-- ❌ No IDs: `email-input`, `submit-btn-123`
-
-### 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)
-- ❌ No environment-specific values (URLs, API keys)
-
-### Examples
-
-| ✅ Good | ❌ Bad |
-|--------|-------|
-| `{{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
-
-### 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
-```
-
-### Assertion Patterns
-
-| 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}}` |
-
-### State Modifiers
-
-| 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}}` |
-
----
-
-## 🏷️ Tags
-
-### Scenario 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)
-
-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}}
-  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
-```
-
-**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>]`
-
-### Step-Level Annotations (comment syntax)
-
-| Annotation | Effect |
-|-----------|--------|
-| `# @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: 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 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**
-
-### 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`)
-
----
-
-## 🎯 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 |
-
----
-
-## 📚 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)
-
----
-
-**Version**: 2.0
-**Status**: Final
-**Last Updated**: March 19, 2026