@sun-asterisk/sungen 2.0.0 → 2.0.2

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

@@ -0,0 +1,377 @@
+# Gherkin Standard - Core (Final)
+
+**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
+```
+<Actor> <Action> [<Target>] with {{<Value>}}
+```
+
+### Rules
+- ✅ `Actor` + `Action` are **mandatory**
+- ✅ `Target` is **required** for most actions (except `open` / `wait for`)
+- ✅ `with {{Value}}` only used when action requires data
+- ❌ 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}}` |
+
+---
+
+## 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 (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.
+
+### Rules
+- ✅ Use **exact verbs** from the list above
+- ❌ No synonyms: `type`, `enter`, `input`, `press`, `check`, `verify`, `expect`, 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
+```
+
+---
+
+## 5️⃣ Target
+
+### Format
+```
+[name] <element type>
+```
+
+### Element Types
+
+| Element Type | When to Use | Example |
+|--------------|-------------|---------|
+| `field` | Text input, textarea | `[Email] field`, `[Password] field` |
+| `button` | Clickable button | `[Submit] button`, `[Cancel] button` |
+| `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` |
+
+### 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 [United States] dropdown
+✅ User see [Welcome back] message
+
+❌ 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] text
+✅ And User see [Logout] button
+
+❌ 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 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` |
+
+### 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
+```
+
+---
+
+## 🏷️ 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 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
+  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 |
+
+---
+
+## ✅ Quick Reference
+
+### Do's ✅
+- Use **standard 6 actions**: open, click, fill, select, wait for, see
+- Use **`User`** as the only actor
+- Use **`[Target] <element type>`** format
+- Use **`{{snake_case}}`** for values
+- **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`)
+
+---
+
+## 🎯 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 code patterns |
+| **No Ambiguity** | Single interpretation per step |
+| **Tool Support** | Compatible with Sungen framework |
+
+---
+
+## 📚 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
+
+---
+
+**Version**: 1.1
+**Status**: Final
+**Last Updated**: March 11, 2026

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

@@ -0,0 +1,303 @@
+# Tiêu Chuẩn Gherkin - Cốt Lõi (Phiên Bản Cuối)
+
+**Áp dụng cho: Kiểm thử thủ công & Kiểm thử tự động**
+
+---
+
+## 1️⃣ Định Dạng Scenario (Cấp độ Flow)
+
+### Định dạng
+```gherkin
+Scenario: <Ai> <Làm gì> <Để đạt kết quả gì>
+  Given ...
+  When ...
+  Then ...
+```
+
+### Nguyên tắc
+- **1 Scenario = 1 hành vi nghiệp vụ hoàn chỉnh**
+- **Given**: Trạng thái / điều kiện ban đầu
+- **When**: Hành động chính (trigger)
+- **Then**: Kết quả quan sát được (assertion)
+
+### Ví dụ
+```gherkin
+Scenario: User logs in successfully with valid credentials
+  Given User open [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️⃣ Ngữ Pháp (Cấp độ Step)
+
+### Định dạng
+```
+<Actor> <Action> [<Target>] with {{<Value>}}
+```
+
+### Quy tắc
+- ✅ `Actor` + `Action` là **bắt buộc**
+- ✅ `Target` là **bắt buộc** với hầu hết action (trừ `open` / `wait for`)
+- ✅ `with {{Value}}` chỉ dùng khi action cần dữ liệu
+- ❌ Không viết tự do (free-text)
+- ❌ Không dùng từ đồng nghĩa
+
+### Cấu trúc chi tiết
+
+| Thành phần | Bắt buộc | Ví dụ |
+|-----------|----------|---------|
+| Actor | ✅ Luôn luôn | `User` |
+| Action | ✅ Luôn luôn | `click`, `fill`, `see` |
+| Target | ✅ Hầu hết | `[Login] button` |
+| Value | ⚠️ Khi cần | `{{valid_email}}` |
+
+---
+
+## 3️⃣ Actor (Tác nhân)
+
+### Actor được phép
+- ✅ **`User`** (duy nhất)
+
+### Quy tắc
+- **Chỉ dùng**: `User`
+- **KHÔNG dùng**: `System`, `Backend`, `API`, `App`
+- Hành vi của hệ thống được verify bằng `Then`, không phải Actor
+
+### Ví dụ
+```gherkin
+✅ User click [Submit] button
+❌ System sends verification email
+❌ Backend validates password
+❌ API returns success response
+```
+
+> **Lý do**: Hành vi hệ thống là *kết quả* cần verify, không phải là actor thực hiện bước.
+
+---
+
+## 4️⃣ Action (Hành động)
+
+### Các Action được phép (chỉ 6 loại)
+
+| Action | Trường hợp sử dụng | Ví dụ |
+|--------|----------|---------|
+| `open` | Điều hướng đến page/screen | `User open [Login] page` |
+| `click` | Click button/link/element | `User click [Submit] button` |
+| `fill` | Nhập text vào input field | `User fill [Email] field with {{email}}` |
+| `select` | Chọn option từ dropdown/radio | `User select [Country] dropdown with {{country}}` |
+| `wait for` | Đợi element/điều kiện | `User wait for [Loader] icon` |
+| `see` | Verify khả năng hiển thị element | `User see [Error] message` |
+
+### Quy tắc
+- ✅ Sử dụng **động từ chính xác** từ danh sách trên
+- ❌ Không dùng từ đồng nghĩa: `type`, `enter`, `input`, `press`, `check`, `verify`, `expect`, v.v.
+- ❌ Không dùng action kết hợp: `click and wait`, `fill and submit`
+
+### Anti-patterns (Mẫu sai)
+```gherkin
+❌ User types {{password}} into [Password] field
+❌ User presses [Enter] key
+❌ User checks [Terms] checkbox
+❌ User verifies [Success] message appears
+```
+
+---
+
+## 5️⃣ Target (Đối tượng)
+
+### Định dạng
+```
+[name] <element type>
+```
+
+### Các loại Element
+
+| Loại Element | Khi nào dùng | Ví dụ |
+|--------------|-------------|---------|
+| `field` | Text input, textarea | `[Email] field`, `[Password] field` |
+| `button` | Button có thể click | `[Submit] button`, `[Cancel] button` |
+| `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` | Toàn bộ màn hình/page | `[Login] page`, `[Dashboard] page` |
+| `icon` | Icon/hình ảnh hiển thị | `[Loader] icon`, `[Close] icon` |
+| `label` | Text label | `[Username] label` |
+
+### Quy tắc
+- ✅ Dùng **tên có nghĩa nghiệp vụ/UI**, không dùng selector kỹ thuật
+- ✅ Giữ tên **đơn giản và mô tả rõ**
+- ❌ Không dùng CSS selector: `#email`, `.btn-primary`
+- ❌ Không dùng XPath: `//input[@id='email']`
+- ❌ Không dùng ID: `email-input`, `submit-btn-123`
+
+### Ví dụ
+```gherkin
+✅ User click [Login] button
+✅ User fill [Email address] field with {{email}}
+✅ User select [United States] dropdown
+✅ User see [Welcome back] message
+
+❌ User click [#submit-btn] button
+❌ User fill [input.email-field] field
+❌ User see [div.alert-success] message
+```
+
+---
+
+## 6️⃣ Value (Giá trị)
+
+### Định dạng
+```
+{{value}}
+```
+
+### Quy ước đặt tên
+- **snake_case** (chữ thường với dấu gạch dưới)
+- Mô tả rõ ràng và theo ngữ cảnh
+
+### Quy tắc
+- ✅ Sử dụng cú pháp `{{variable}}`
+- ✅ Tên phản ánh **mục đích của dữ liệu**, không phải nội dung
+- ❌ Không hard-code dữ liệu trong step
+- ❌ Không chứa dữ liệu thật (email, password, token)
+- ❌ Không chứa giá trị theo môi trường (URL, API key)
+
+### Ví dụ
+
+| ✅ Đúng | ❌ Sai |
+|--------|-------|
+| `{{valid_email}}` | `{{user@example.com}}` |
+| `{{invalid_password}}` | `{{123456}}` |
+| `{{expired_otp}}` | `{{999999}}` |
+| `{{admin_username}}` | `{{admin}}` |
+| `{{product_name}}` | `{{iPhone 15 Pro}}` |
+
+### Tổ chức dữ liệu
+```yaml
+# test-data/login.yaml
+valid_email: "user@example.com"
+valid_password: "SecurePass123!"
+invalid_email: "not-an-email"
+expired_otp: "000000"
+```
+
+---
+
+## 7️⃣ Assertion (Xác nhận)
+
+### Động từ
+- **Chỉ dùng**: `see`
+
+### Quy tắc
+- ✅ Assertion **chỉ xuất hiện trong `Then`**
+- ✅ Verify **trạng thái hệ thống / output**
+- ✅ Mỗi step = **1 assertion**
+- ❌ Không mô tả hành động của user
+- ❌ Không dùng từ đồng nghĩa: `verify`, `expect`, `check`, `observe`, `validate`
+
+### Ví dụ
+```gherkin
+✅ Then User see [Error] message
+✅ And User see [Dashboard] page
+✅ And User see [Welcome] text
+✅ And User see [Logout] button
+
+❌ Then User verifies [Error] message
+❌ Then System displays [Dashboard] page
+❌ Then [Success] message appears
+```
+
+### Các mẫu Assertion
+
+| Mẫu | Trường hợp sử dụng | Ví dụ |
+|---------|----------|---------|
+| Hiển thị đơn giản | Element có thể nhìn thấy | `User see [Login] button` |
+| Hiển thị với giá trị | Element chứa text cụ thể | `User see [Welcome] text with {{username}}` |
+| Verify page/trạng thái | Xác nhận điều hướng | `User see [Dashboard] page` |
+| Verify message | Xác nhận phản hồi | `User see [Error] message` |
+
+---
+
+## 📋 Ví Dụ Hoàn Chỉnh
+
+```gherkin
+Feature: User Authentication
+  Path: /auth/login
+
+  Scenario: User logs in successfully with valid credentials
+    Given User open [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 open [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 open [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
+```
+
+---
+
+## ✅ Tham Khảo Nhanh
+
+### Nên làm ✅
+- Dùng **6 action chuẩn**: open, click, fill, select, wait for, see
+- Dùng **`User`** là actor duy nhất
+- Dùng định dạng **`[Target] <element type>`**
+- Dùng **`{{snake_case}}`** cho giá trị
+- **1 Scenario = 1 flow nghiệp vụ**
+- **1 Step = 1 action hoặc assertion**
+
+### Không nên làm ❌
+- Không dùng từ đồng nghĩa hoặc viết tự do
+- Không dùng system/backend/API làm actor
+- Không dùng selector kỹ thuật (CSS/XPath/ID)
+- Không hard-code dữ liệu trong step
+- Không dùng action kết hợp
+- Không dùng `verify`/`check`/`expect` (dùng `see`)
+
+---
+
+## 🎯 Lợi Ích
+
+| Lợi ích | Mô tả |
+|---------|-------------|
+| **Nhất quán** | Cùng một mẫu cho tất cả test case |
+| **Dễ đọc** | Người không kỹ thuật cũng hiểu được |
+| **Dễ bảo trì** | Dễ cập nhật khi UI thay đổi |
+| **Sẵn sàng tự động** | Ánh xạ trực tiếp sang code pattern |
+| **Không mơ hồ** | Mỗi step chỉ có một cách hiểu |
+| **Hỗ trợ công cụ** | Tương thích với framework Sungen |
+
+---
+
+## 📚 Tài Liệu Liên Quan
+- [Hướng dẫn Selector Override](selector-override.md) - Tùy chỉnh selector element
+- [Hướng dẫn Validation](validate.md) - Validate file Gherkin
+- [Thiết lập Auth](makeauth.md) - Cấu hình trạng thái authentication
+
+---
+
+**Phiên bản**: 1.0  
+**Trạng thái**: Final  
+**Cập nhật lần cuối**: 11 tháng 2, 2026