@sun-asterisk/sungen 2.2.3 → 2.3.0

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

@@ -1,399 +0,0 @@
-# Tieu Chuan Gherkin - Cot Loi v2.1
-
-**Ap dung cho: Kiem thu thu cong & Kiem thu tu dong**
-
----
-
-## 1️⃣ Dinh Dang Scenario (Cap do Flow)
-
-### Dinh dang
-```gherkin
-Scenario: <Ai> <Lam gi> <De dat ket qua gi>
-  Given ...
-  When ...
-  Then ...
-```
-
-### Nguyen tac
-- **Doc lap**: 1 Scenario = 1 hanh vi nghiep vu hoan chinh (khong dung chung du lieu giua cac scenario)
-- **Hanh vi**: Mo ta "User lam gi" va "Thay gi" — tap trung vao hanh vi nguoi dung
-- **Khach quan**: Mo ta ket qua nghiep vu. Khong chua chi tiet ky thuat (CSS, XPath)
-
-### Luong
-**Qua khu (Setup) → Hien tai (Tuong tac) → Tuong lai (Ket qua)**
-
-```gherkin
-Scenario: User logs in successfully with valid credentials
-  # 1. Thiet lap
-  Given User is on [Login] page
-  # 2. Tuong tac
-  When User fill [Email] field with {{valid_email}}
-  And User fill [Password] field with {{valid_password}}
-  And User click [Submit] button
-  # 3. Ket qua
-  Then User see [Dashboard] page
-  And User see [Welcome] heading with {{username}}
-  And User see [Logout] button is enabled
-```
-
-### Quy tac tu khoa
-- **Given** → chi `is on` (thiet lap ngu canh)
-- **When / And** → `click`, `fill`, `select`, `press`, `clear`, `check`, `uncheck`, `hover`, `wait for`
-- **Then / And** → chi `see` (xac nhan)
-- **And** → ke thua tu khoa truoc do
-
-> Toi da 5-7 buoc `Then/And` moi scenario. Tach thanh scenario rieng neu can nhieu hon.
-
----
-
-## 2️⃣ Ngu Phap (Cap do Step)
-
-### Dinh dang
-```
-[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
-```
-
-### Quy tac
-- ✅ `Actor` + `Action` la **bat buoc**
-- ✅ `Target` la **bat buoc** voi hau het action (tru `wait for` timeout)
-- ✅ `with {{Value}}` chi dung khi action can du lieu
-- ✅ `is State` chi dung cho assertion va wait
-- ❌ Khong viet tu do (free-text)
-- ❌ Khong dung tu dong nghia
-
-### Cau truc chi tiet
-
-| Thanh phan | Bat buoc | Vi du |
-|-----------|----------|---------|
-| Actor | ✅ Luon luon | `User` |
-| Action | ✅ Luon luon | `click`, `fill`, `see` |
-| Target | ✅ Hau het | `[Login] button` |
-| Value | ⚠️ Khi can | `{{valid_email}}` |
-| State | ⚠️ Khi can | `is disabled` |
-
----
-
-## 3️⃣ Actor (Tac nhan)
-
-### Actor duoc phep
-- ✅ **`User`** (duy nhat)
-
-### Quy tac
-- **Chi dung**: `User`
-- **KHONG dung**: `System`, `Backend`, `API`, `App`
-- Hanh vi cua he thong duoc verify bang `Then`, khong phai Actor
-
----
-
-## 4️⃣ Action (Hanh dong)
-
-### Ma tran Action
-
-| Nhom | Action | `with {{Value}}` | `is State` | Target Types |
-|------|--------|:-:|:-:|---|
-| **Setup** | `is on` | ❌ | ❌ | `page`, `dialog`, `modal`, `tab` |
-| **Tuong tac** | `click` | Chi list dong ✱ | ❌ | Moi phan tu tuong tac |
-| **Tuong tac** | `double click` | ❌ | ❌ | Bat ky |
-| **Tuong tac** | `hover` | ❌ | ❌ | `icon`, `image`, `row`, `card`, `menuitem` |
-| **Tuong tac** | `drag` | ❌ | ❌ | Bat ky |
-| **Tuong tac** | `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` (KHONG cho radio) |
-| **Phim** | `press` | ❌ | ❌ | `key` (bat buoc) |
-| **Cuon** | `scroll to` | ❌ | ❌ | `section`, bat ky |
-| **Frame** | `switch to` | ❌ | ❌ | `frame` |
-| **Cho** | `wait for` | ⚠️ | ⚠️ | `page`, `dialog`, `modal`, `message`, bat ky |
-| **Xac nhan** | `see` | ✅ | ✅ | Tat ca |
-| **Alert** | `click` | ❌ | ❌ | `alert` (OK/Cancel) |
-| **Alert** | `fill` | ✅ | ❌ | `alert` (prompt) |
-
-> ✱ **`click` + `with {{Value}}`**: Chi cho list dong (`row`, `item`, `card`, `option`). Khong dung cho phan tu tinh (`button`, `link`, `icon`, `tab`).
-
-### Quy tac
-- ✅ Dung **dong tu chinh xac** tu danh sach
-- ❌ Khong dung tu dong nghia: `type`, `enter`, `input`, `verify`, `expect`, v.v.
-- ❌ Khong dung action ket hop: `click and wait`, `fill and submit`
-
-### Anti-patterns (Mau sai)
-```gherkin
-❌ User types {{password}} into [Password] field     → Dung: User fill [Password] field with {{password}}
-❌ User opens [Home] page                            → Dung: User is on [Home] page
-❌ User click [Terms] checkbox                       → Dung: User check [Terms] checkbox
-❌ User uncheck [Male] radio                         → Radio khong the uncheck, dung: User check [Female] radio
-❌ User verifies [Success] message                   → Dung: User see [Success] message
-```
-
----
-
-## 5️⃣ Target (Doi tuong)
-
-### Dinh dang
-```
-[name] <element type>
-```
-
-### Cac loai Element
-
-| Nhom | Types | Vi du |
-|---|---|---|
-| **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` |
-
-### Quy tac dat ten
-- ✅ Dung **ten co nghia nghiep vu/UI**, khong dung selector ky thuat
-- ✅ Co visible text → dung dung nhan UI: `[Dang nhap] button`
-- ✅ Khong co visible text → danh tu ngan gon: `[close] icon`
-- ✅ Ten > 30 ky tu → rut gon 1-3 tu co nghia
-- ❌ Khong dung CSS: `#email`, `.btn-primary`
-- ❌ Khong gop element type vao ngoac vuong: `[login button]` → `[login] button`
-
----
-
-## 6️⃣ Value (Gia tri)
-
-### Dinh dang
-```
-{{value}}
-```
-
-### Quy uoc
-- **snake_case** (chu thuong voi dau gach duoi)
-- Mo ta ro rang va theo ngu canh
-
-### Quy tac
-- ✅ Su dung cu phap `{{variable}}`
-- ✅ Ten phan anh **muc dich cua du lieu**, khong phai noi dung
-- ❌ Khong hard-code du lieu trong step
-- ❌ Khong chua du lieu that (email, password, token)
-
-### Vi du
-
-| ✅ Dung | ❌ Sai |
-|--------|-------|
-| `{{valid_email}}` | `{{user@example.com}}` |
-| `{{invalid_password}}` | `{{123456}}` |
-| `{{product_name}}` | `{{iPhone 15 Pro}}` |
-
----
-
-## 7️⃣ Assertion (Xac nhan)
-
-### Dong tu
-- **Duy nhat**: `see`
-
-### 7 Pattern Verify
-
-| # | Pattern | Assertion | Vi du |
-|---|---------|-----------|-------|
-| 1 | **Hien thi** | `toBeVisible()` / `toBeHidden()` | `see [Success] message` / `see [Ads] modal is hidden` |
-| 2 | **Noi dung text** | `toHaveText()` (khop chinh xac) | `see [Error] message with {{err_msg}}` |
-| 3 | **Text mot phan** | `toContainText()` | `see [Title] heading contains {{text}}` |
-| 4 | **Gia tri input** | `toHaveValue()` | `see [Email] field with {{user_email}}` |
-| 5 | **Trang thai** | `toBeDisabled()` / `toBeChecked()` v.v. | `see [Submit] button is disabled` |
-| 6 | **So luong** | `toHaveCount()` | `see [Result] row with {{result_count}}` |
-| 7 | **Dieu huong** | `toHaveURL()` | `see [Dashboard] page` |
-
-> **Phan biet quan trong**: `see [T] <input type> with {{v}}` → `toHaveValue()` cho input (field, textarea, search, dropdown, slider, date-picker). `see [T] <other type> with {{v}}` → `toHaveText()` cho tat ca con lai.
-
-### States (Trang thai)
-
-| State | Mo ta |
-|-------|-------|
-| `hidden` | Element bi an |
-| `visible` | Element hien thi |
-| `disabled` | Element bi vo hieu |
-| `enabled` | Element co the tuong tac |
-| `checked` | Checkbox/radio/toggle duoc chon |
-| `unchecked` | Checkbox/radio/toggle chua chon |
-| `focused` | Element dang duoc focus |
-| `empty` | Element rong |
-| `loading` | Dang tai |
-| `selected` | Duoc chon |
-| `sorted ascending` | Sap xep tang dan |
-| `sorted descending` | Sap xep giam dan |
-
-### Ket hop Value + State
-```gherkin
-Then User see [Ads] modal with {{promo_title}} is hidden
-```
-
-### Xac nhan bang (Table)
-
-| Mau | Vi du |
-|------|-------|
-| Dong ton tai | `User see [Users] table has row with {{name}}` |
-| Khong co dong | `User see [Users] table has no row with {{name}}` |
-| Dem dong | `User see [Users] table has {{count}} rows` |
-| Cot ton tai | `User see [Users] table has [Email] column` |
-| Bang rong | `User see [Users] table is empty` |
-| O theo bo loc | `User see [Users] table row with {{filter}} has [Status] with {{status}}` |
-| O theo chi so | `User see [Users] table row 1 [Name] cell with {{name}}` |
-| Hanh dong trong dong | `User click [Edit] in [Users] table row with {{name}}` |
-
-### Quy tac
-- ✅ Assertion **chi xuat hien trong `Then`**
-- ✅ Moi step = **1 assertion**
-- ❌ Khong dung tu dong nghia: `verify`, `expect`, `check`, `validate`
-
----
-
-## 8️⃣ Browser Alert (System Dialog)
-
-Cho dialog he thong (`window.alert`, `window.confirm`, `window.prompt`):
-
-```gherkin
-# Buoc alert phai dat TRUOC hanh dong kich hoat dialog
-When User click [OK] alert              # chap nhan (OK/Accept/Yes/Confirm)
-And User click [Delete] button           # hanh dong kich hoat alert
-
-When User click [Cancel] alert           # tu choi (Cancel/Dismiss/No)
-And User click [Delete] button
-
-When User fill [Name] alert with {{v}}   # nhap prompt + chap nhan
-And User click [Rename] button
-```
-
-> **Quan trong**: Dang ky dialog handler TRUOC hanh dong kich hoat. Sungen sinh `page.once('dialog', ...)`.
-
----
-
-## 🏷️ Tags
-
-### Tags phan loai
-
-| Tag | Mo ta |
-|-----|-------|
-| `@auto` | Scenario tu dong, san sang chay |
-| `@manual` | Bo qua khi sinh code |
-| `@smoke` | Tap kiem thu Smoke |
-| `@regression` | Tap kiem thu Regression |
-
-### Tags xac thuc
-
-| Tag | Mo ta |
-|-----|-------|
-| `@auth:<role>` | Su dung trang thai auth Playwright cho role |
-| `@no-auth` | Tat authentication ke thua |
-
-**Thu tu uu tien Auth**: Scenario ke thua `@auth` > Scenario goc `@auth` > Feature `@auth`
-
-### Tags ke thua (@steps / @extend)
-
-```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    # ← bo qua khi @extend goi
-
-@auto @auth:user @extend:kudos__open_modal
-Scenario: User successfully sends a thank you message
-  Given User is on [Send thanks] dialog  # ← bat buoc: xac nhan trang thai sau extend
-  When User fill [Search teammate] field with {{teammate_name}}
-  And User click [Send] button
-  Then User see [Success] message with {{msg_success}}
-```
-
-**Hanh vi:**
-- `@extend` thuc thi **chi Given→When** cua `@steps` (bo qua Then)
-- `Given` trong `@extend` la **assertion xac nhan trang thai** sau khi base steps chay
-- Neu `@steps` **fail**, `@extend` se **tu dong bo qua (skip)**
-- Dinh dang ten: `snake_case` hoac `kebab-case` voi prefix module: `@steps:kudos__open_modal`
-
----
-
-## 📋 Vi du hoan chinh
-
-```gherkin
-@feature_auth
-Feature: Xac thuc nguoi dung
-  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 [Login] button
-    Then User see [Dashboard] page
-    And User see [Welcome] message with {{user_fullname}}
-    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 [Login] button
-    Then User see [Login] page
-    And User see [Login error] message with {{err_invalid_credentials}}
-    And User see [Login] button is enabled
-
-  # Dung @extend
-  @auto @auth:user @steps:navigate_to_profile
-  Scenario: Setup — Navigate to Profile page
-    Given User is on [Dashboard] page
-    When User click [Avatar] icon
-    And User click [My account] menuitem
-    Then User see [Profile] page     # ← @extend bo qua buoc nay
-
-  @auto @auth:user @extend:navigate_to_profile
-  Scenario: User updates display name successfully
-    Given User is on [Profile] page           # ← Xac nhan trang thai sau extend
-    When User fill [Display name] field with {{new_display_name}}
-    And User click [Save changes] button
-    Then User see [Success] message with {{msg_save_success}}
-    And User see [Display name] field with {{new_display_name}}
-```
-
----
-
-## ✅ Tham Khao Nhanh
-
-### Nen lam ✅
-- Dung **action chuan** tu ma tran action
-- Dung **`User`** la actor duy nhat
-- Dung dinh dang **`[Target] <element type>`**
-- Dung **`{{snake_case}}`** cho gia tri
-- Dung **`is <state>`** cho xac nhan trang thai
-- Dung **tags** (`@auth`, `@steps`, `@extend`) de quan ly scenario
-- **1 Scenario = 1 flow nghiep vu**
-- **1 Step = 1 action hoac assertion**
-
-### Khong nen lam ❌
-- Khong dung tu dong nghia hoac viet tu do
-- Khong dung system/backend/API lam actor
-- Khong dung selector ky thuat (CSS/XPath/ID)
-- Khong hard-code du lieu trong step
-- Khong dung action ket hop
-- Khong dung `verify`/`check`/`expect` thay cho `see`
-- Khong `click` checkbox/toggle (dung `check`/`uncheck`)
-- Khong `uncheck` radio (dung `check` option khac)
-
-### Loi thuong gap
-
-| ❌ Sai | ✅ Dung | Ly do |
-|---|---|---|
-| `Given User click [Login] button` | `When User click [Login] button` | `click` thuoc WHEN |
-| `When User click [Terms] checkbox` | `When User check [Terms] checkbox` | Dung `check` cho checkbox |
-| `When User press [Submit] button` | `When User press [Enter] key` | `press` chi di voi `key` |
-| `When User uncheck [Male] radio` | `When User check [Female] radio` | Radio khong the uncheck |
-| `fill [email] with {{admin@mail}}` | `fill [email] field with {{admin_email}}` | Khong hardcode + thieu type |
-| `see [msg] with {{text}} hidden` | `see [msg] with {{text}} is hidden` | Thieu tu noi `is` |
-| `see [btn] button with {{disabled}}` | `see [btn] button is disabled` | State dung `is`, khong dung `{{}}` |
-
----
-
-**Phien ban**: 2.1
-**Trang thai**: Final
-**Cap nhat lan cuoi**: 31 thang 3, 2026