@sun-asterisk/sungen 2.0.3 → 2.1.1

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