@sun-asterisk/sungen 2.2.1 → 2.2.3

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

@@ -1,513 +1,399 @@
-# Tiêu Chuẩn Gherkin - Cốt Lõi v2
+# Tieu Chuan Gherkin - Cot Loi v2.1
 
-**Áp dụng cho: Kiểm thử thủ công & Kiểm thử tự động**
+**Ap dung cho: Kiem thu thu cong & Kiem thu tu dong**
 
 ---
 
-## 1️⃣ Định Dạng Scenario (Cấp độ Flow)
+## 1️⃣ Dinh Dang Scenario (Cap do Flow)
 
-### Định dạng
+### Dinh dang
 ```gherkin
-Scenario: <Ai> <Làm gì> <Để đạt kết quả gì>
+Scenario: <Ai> <Lam gi> <De dat ket qua gi>
   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)
+### 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)**
 
-### Ví dụ
 ```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️⃣ Ngữ Pháp (Cấp độ Step)
+## 2️⃣ Ngu Phap (Cap do Step)
 
-### Định dạng
+### Dinh dang
 ```
 [Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
 ```
 
-### 17 Mẫu Pattern
-
-| # | Mẫu | Ví dụ |
-|---|------|-------|
-| ① | Hành động đơn giản | `click [Submit] button` |
-| ② | Hành động với dữ liệu | `fill [Email] field with {{email}}` |
-| ③ | Xác nhận trạng thái | `see [Submit] button is disabled` |
-| ④ | Trạng thái với dữ liệu | `see [Panel] dialog with {{title}} is hidden` |
-| ⑤ | Hai đối tượng (kéo thả) | `drag [Card] to [Column]` |
-| ⑥ | Phím toàn cục | `press Enter key` |
-| ⑦ | Phím trên đối tượng | `press Enter on [Search] field` |
-| ⑧ | Chờ thời gian | `wait for 3 seconds` |
-| ⑨ | Chờ element | `wait for [Loader] spinner is hidden` |
-| ⑩ | Cuộn trang | `scroll to [Footer] section` |
-| ⑪ | Chuyển frame | `switch to [Payment] frame` |
-| ⑫ | Có (số lượng/thuộc tính) | `see [Avatar] image has {{src}}` |
-| ⑬ | Ô bảng theo chỉ số hàng | `see [Users] table row 1 [Name] cell {{name}}` |
-| ⑭ | Ô bảng theo bộ lọc hàng | `see [Users] table row {{filter}} [Status] cell {{status}}` |
-| ⑮ | Hành động trong hàng bảng | `click [Edit] button in [Users] table row {{filter}}` |
-| ⑯ | Điều hướng | `is on [Dashboard] page` / `navigate to [Settings] page` |
-| ⑰ | Xác nhận văn bản | `see [Title] heading contains {{text}}` |
-
-### Quy tắc
-- ✅ `Actor` + `Action` là **bắt buộc**
-- ✅ `Target` là **bắt buộc** với hầu hết action (trừ `wait for` timeout)
-- ✅ `with {{Value}}` chỉ dùng khi action cần dữ liệu
-- ✅ `is State` để xác nhận trạng thái element
-- ❌ 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}}` |
-| State | ⚠️ Khi cần | `is disabled` |
+### 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
 
-## 3️⃣ Actor (Tác nhân)
+| 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` |
 
-### 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
+## 3️⃣ Actor (Tac nhan)
 
-### Ví dụ
-```gherkin
-✅ User is on [Login] page
-✅ User click [Submit] button
-❌ System sends verification email
-❌ Backend validates password
-❌ API returns success response
-```
+### Actor duoc phep
+- ✅ **`User`** (duy nhat)
 
-> **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.
+### 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 (Hành động)
-
-### Các Action được phép (20 loại)
-
-| Action | Trường hợp sử dụng | Ví dụ |
-|--------|----------|---------|
-| `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 | `User select [Country] dropdown with {{country}}` |
-| `check` | Đánh dấu checkbox | `User check [Remember me] checkbox` |
-| `uncheck` | Bỏ đánh dấu checkbox | `User uncheck [Newsletter] checkbox` |
-| `toggle` | Bật/tắt switch | `User toggle [Dark mode] switch` |
-| `upload` | Tải file lên | `User upload [Avatar] file with {{avatar_path}}` |
-| `hover` | Di chuột lên element | `User hover [Info] icon` |
-| `drag` | Kéo thả element | `User drag [Card] to [Column]` |
-| `clear` | Xóa nội dung input | `User clear [Search] field` |
-| `see` | Verify hiển thị / trạng thái | `User see [Error] message` |
-| `press` | Nhấn phím bàn phím | `User press Enter key` |
-| `expand` | Mở rộng element | `User expand [Details] row` |
-| `collapse` | Thu gọn element | `User collapse [Details] row` |
-| `double click` | Double click element | `User double click [Cell] cell` |
-| `scroll to` | Cuộn đến element | `User scroll to [Footer] section` |
-| `switch to` | Chuyển sang frame | `User switch to [Payment] frame` |
-| `wait for` | Đợi element/điều kiện | `User wait for [Loader] spinner` |
-| `is on` | Xác nhận đang ở trang | `User is on [Login] page` |
-| `navigate to` | Điều hướng đến trang | `User navigate to [Settings] page` |
-
-> **Ghi chú**: `is on` và `navigate to` đều dùng cho điều hướng. `is on` là dạng ưu tiên cho step `Given`.
-
-### 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`, `verify`, `expect`, v.v.
-- ❌ Không dùng action kết hợp: `click and wait`, `fill and submit`
-
-### Anti-patterns (Mẫu sai)
+## 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     → Dùng: User fill [Password] field with {{password}}
-❌ User presses [Enter] key                          → Dùng: User press Enter key
-❌ User checks [Terms] checkbox                      → Dùng: User check [Terms] checkbox
-❌ User verifies [Success] message appears            → Dùng: User see [Success] message
+❌ 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 (Đối tượng)
+## 5️⃣ Target (Doi tuong)
 
-### Định dạng
+### Dinh dang
 ```
 [name] <element type>
 ```
 
-### Các loại Element (40+)
-
-#### Tương tác cơ bản
-
-| Loại Element | Khi nào dùng | Ví dụ |
-|--------------|-------------|---------|
-| `button` | Nút có thể click | `[Submit] button` |
-| `link` | Hyperlink | `[Forgot password] link` |
-| `field` | Text input | `[Email] field` |
-| `textarea` | Text area nhiều dòng | `[Message] textarea` |
-| `heading` | Tiêu đề (h1-h6) | `[Welcome] heading` |
-| `text` | Nội dung text | `[Price] text` |
-| `image` | Hình ảnh | `[Avatar] image` |
-| `icon` | Icon/hình ảnh nhỏ | `[Close] icon` |
-
-#### Form controls
-
-| Loại Element | Khi nào dùng | Ví dụ |
-|--------------|-------------|---------|
-| `checkbox` | Checkbox input | `[Remember me] checkbox` |
-| `radio` | Radio button | `[Payment method] radio` |
-| `switch` | Toggle switch | `[Dark mode] switch` |
-| `dropdown` | Select/combobox | `[Country] dropdown` |
-| `option` | Option trong dropdown | `[Vietnam] option` |
-| `slider` | Thanh trượt | `[Volume] slider` |
-| `uploader` | Vùng upload file | `[Document] uploader` |
-| `file` | File input | `[Avatar] file` |
-
-#### Overlay & navigation
-
-| Loại Element | Khi nào dùng | Ví dụ |
-|--------------|-------------|---------|
-| `dialog` | Hộp thoại | `[Confirm] dialog` |
-| `modal` | Modal overlay | `[Edit] modal` |
-| `menu` | Menu dropdown | `[Actions] menu` |
-| `menuitem` | Mục trong menu | `[Delete] menuitem` |
-| `tab` | Tab header | `[Settings] tab` |
-| `tabpanel` | Nội dung tab | `[General] tabpanel` |
-| `tooltip` | Tooltip | `[Help] tooltip` |
-| `alert` | Thông báo | `[Error] alert` |
-
-#### Cấu trúc & layout
-
-| Loại Element | Khi nào dùng | Ví dụ |
-|--------------|-------------|---------|
-| `list` | Danh sách | `[Results] list` |
-| `listitem` | Mục trong danh sách | `[Item 1] listitem` |
-| `table` | Bảng dữ liệu | `[Users] table` |
-| `row` | Hàng trong bảng | `[Row 1] row` |
-| `cell` | Ô trong bảng | `[Name] cell` |
-| `column` | Cột | `[Status] column` |
-| `columnheader` | Tiêu đề cột | `[Name] columnheader` |
-| `region` | Vùng landmark | `[Main] region` |
-| `section` | Section | `[Footer] section` |
-| `nav` | Thanh navigation | `[Main] nav` |
-| `banner` | Banner | `[Top] banner` |
-| `header` | Header | `[Page] header` |
-| `footer` | Footer | `[Page] footer` |
-
-#### Đặc biệt
-
-| Loại Element | Khi nào dùng | Ví dụ |
-|--------------|-------------|---------|
-| `page` | Toàn bộ trang | `[Login] page` |
-| `spinner` | Loading indicator | `[Loader] spinner` |
-| `progressbar` | Thanh tiến trình | `[Upload] progressbar` |
-| `tree` | Cấu trúc cây | `[Files] tree` |
-| `treeitem` | Mục trong cây | `[Folder] treeitem` |
-| `frame` | Iframe | `[Payment] frame` |
-| `iframe` | Iframe (tương đương frame) | `[Embed] iframe` |
-
-### 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 check [Remember me] checkbox
-✅ User toggle [Dark mode] switch
-✅ User see [Welcome back] heading
-
-❌ User click [#submit-btn] button
-❌ User fill [input.email-field] field
-❌ User see [div.alert-success] message
-```
+### 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 (Giá trị)
+## 6️⃣ Value (Gia tri)
 
-### Định dạng
+### Dinh dang
 ```
 {{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 uoc
+- **snake_case** (chu thuong voi dau gach duoi)
+- Mo ta ro rang va theo ngu canh
 
-### 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)
+### 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)
 
-### Ví dụ
+### Vi du
 
-| ✅ Đúng | ❌ Sai |
+| ✅ Dung | ❌ 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 (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)
 
-## 7️⃣ Assertion (Xác nhận)
-
-### Động từ
-- **Chính**: `see` (xác nhận hiển thị / trạng thái)
-
-### States (Trạng thái)
-
-Thêm `is <state>` vào cuối step `see` hoặc `wait for` để xác nhận trạng thái:
-
-| State | Mô tả | Ví dụ |
-|-------|--------|-------|
-| `hidden` | Element bị ẩn | `User see [Modal] dialog is hidden` |
-| `visible` | Element hiển thị | `User see [Banner] section is visible` |
-| `disabled` | Element bị vô hiệu | `User see [Submit] button is disabled` |
-| `enabled` | Element có thể tương tác | `User see [Submit] button is enabled` |
-| `checked` | Checkbox/radio được chọn | `User see [Terms] checkbox is checked` |
-| `unchecked` | Checkbox/radio chưa chọn | `User see [Terms] checkbox is unchecked` |
-| `focused` | Element đang được focus | `User see [Email] field is focused` |
-| `empty` | Element rỗng | `User see [Search] field is empty` |
-| `loading` | Element đang tải | `User see [Content] section is loading` |
-| `selected` | Element được chọn | `User see [Tab 1] tab is selected` |
-| `sorted ascending` | Sắp xếp tăng dần | `User see [Name] columnheader is sorted ascending` |
-| `sorted descending` | Sắp xếp giảm dần | `User see [Name] columnheader is sorted descending` |
-
-### 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`
-
-### 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] heading with {{username}}` |
-| Xác nhận trạng thái | Element ở trạng thái nhất định | `User see [Submit] button is disabled` |
-| Trạng thái với giá trị | Element có giá trị và trạng thái | `User see [Panel] dialog with {{title}} is hidden` |
-| Chứa text | Element chứa text | `User see [Title] heading contains {{text}}` |
-| Có thuộc tính | Element có thuộc tính/giá trị | `User see [Avatar] image has {{src}}` |
-| Verify page | Xác nhận điều hướng | `User is on [Dashboard] page` |
-| Chờ ẩn | Đợi element biến mất | `User wait for [Loader] spinner is hidden` |
-
-### Xác nhận bảng (Table Assertions)
-
-| Mẫu | Ví dụ |
+| Mau | Vi du |
 |------|-------|
-| Ô theo chỉ số hàng | `User see [Users] table row 1 [Name] cell {{name}}` |
-| Ô theo bộ lọc hàng | `User see [Users] table row {{filter}} [Status] cell {{status}}` |
-| Hành động trong hàng | `User click [Edit] button in [Users] table row {{filter}}` |
-| Đếm số hàng | `User see [Users] table has {{count}} rows` |
-| Bảng rỗng | `User see [Users] table is empty` |
-| Có cột | `User see [Users] table has [Email] column` |
-
-### Ví dụ
+| 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
-✅ Then User see [Error] alert
-✅ And User see [Dashboard] page
-✅ And User see [Welcome] heading with {{username}}
-✅ And User see [Submit] button is disabled
-✅ And User see [Terms] checkbox is checked
-✅ And User see [Users] table row 1 [Name] cell {{name}}
-
-❌ Then User verifies [Error] message
-❌ Then System displays [Dashboard] page
-❌ Then [Success] message appears
+# 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
 
-### Scenario Tags
+### Tags phan loai
 
-| Tag | Mô tả |
+| Tag | Mo ta |
 |-----|-------|
-| `@auth:<role>` | Sử dụng trạng thái auth Playwright cho role đã cho |
-| `@no-auth` | Tắt authentication kế thừa |
-| `@steps:<name>` | Đánh dấu scenario là khối step tái sử dụng |
-| `@extend:<name>` | Chèn step từ khối `@steps` trước step hiện tại |
-| `@manual` | Bỏ qua scenario khi sinh code |
+| `@auto` | Scenario tu dong, san sang chay |
+| `@manual` | Bo qua khi sinh code |
+| `@smoke` | Tap kiem thu Smoke |
+| `@regression` | Tap kiem thu Regression |
 
-Tags có thể áp dụng ở **cấp Feature** (kế thừa cho tất cả scenario) hoặc **cấp Scenario** (ghi đè Feature).
+### Tags xac thuc
 
-**Thứ tự ưu tiên Auth**: Scenario kế thừa `@auth` > Scenario gốc `@auth` > Feature `@auth`
+| Tag | Mo ta |
+|-----|-------|
+| `@auth:<role>` | Su dung trang thai auth Playwright cho role |
+| `@no-auth` | Tat authentication ke thua |
 
-### Step tái sử dụng (@steps / @extend)
+**Thu tu uu tien Auth**: Scenario ke thua `@auth` > Scenario goc `@auth` > Feature `@auth`
 
-Dùng `@steps:<name>` để định nghĩa khối tái sử dụng và `@extend:<name>` để kế thừa:
+### Tags ke thua (@steps / @extend)
 
 ```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 with {{teammate_message}}
-  And User click [Hashtag] button with {{hashtag_1}}
+@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
-  And User wait for [Panel] dialog with {{kudo_title}} is hidden
-  Then User see [Panel] modal with {{kudo_title}} is hidden
+  Then User see [Success] message with {{msg_success}}
 ```
 
-**Hành vi:**
-- Scenario `@steps` sinh test riêng VÀ đăng ký step để tái sử dụng
-- Scenario `@extend` nhận step gốc chèn vào đầu — test hoàn toàn độc lập
-- Nhiều scenario có thể extend cùng một khối `@steps`
-- Code sinh ra có comment phân đoạn: `// [from @steps:<name>]`
-
-### Annotation cấp Step (cú pháp comment)
-
-| Annotation | Hiệu lực |
-|-----------|--------|
-| `# @ignore` | Bỏ qua step này khi sinh code |
-| `# @ignore-testcase` | Bỏ qua toàn bộ scenario khi sinh code |
-| `# @skip-production` | Bỏ qua step trong môi trường production |
+**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`
 
 ---
 
-## 📋 Ví Dụ Hoàn Chỉnh
+## 📋 Vi du hoan chinh
 
 ```gherkin
-Feature: User Authentication
+@feature_auth
+Feature: Xac thuc nguoi dung
   Path: /auth/login
 
-  @auth:admin
+  # 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
+    And User click [Login] button
     Then User see [Dashboard] page
-    And User see [Welcome] heading with {{username}}
+    And User see [Welcome] message with {{user_fullname}}
+    And User see [Logout] button is enabled
 
-  @no-auth
-  Scenario: User fails to login with invalid credentials
+  # 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 [Error] alert
-    And User see [Submit] button is enabled
-    And User see [Login] page
-
-  @no-auth
-  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
-
-  Scenario: User manages settings with various controls
-    Given User is on [Settings] page
-    When User toggle [Dark mode] switch
-    And User select [Timezone] dropdown with {{timezone}}
-    And User upload [Avatar] file with {{avatar_path}}
-    And User press Enter key
-    And User scroll to [Save] section
-    And User click [Save] button
-    And User wait for [Loader] spinner is hidden
-    Then User see [Success] alert
-    And User see [Dark mode] switch is checked
+    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 Khảo Nhanh
-
-### Nên làm ✅
-- Dùng **20 action chuẩn** từ danh sách action
-- Dùng **`User`** là actor duy nhất
-- Dùng định dạng **`[Target] <element type>`**
-- Dùng **`{{snake_case}}`** cho giá trị
-- Dùng **`is <state>`** cho xác nhận trạng thái
-- Dùng **tags** (`@auth`, `@steps`, `@extend`) để quản lý scenario
-- **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` thay cho `see`
-
----
-
-## 🎯 Lợi Ích
-
-| Lợi ích | Mô tả |
-|---------|-------------|
-| **Nhất quán** | Cùng 17 mẫu pattern 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 Playwright code |
-| **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 v2 |
-| **Tái sử dụng** | `@steps` / `@extend` giúp tái sử dụng flow |
-
----
-
-## 📚 Tài Liệu Liên Quan
-- [Từ điển Gherkin](../gherkin-dictionary.md) — Ngữ pháp đầy đủ, 17 mẫu pattern, quy tắc compiler
+## ✅ 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 `{{}}` |
 
 ---
 
-**Phiên bản**: 2.0
-**Trạng thái**: Final
-**Cập nhật lần cuối**: 19 tháng 3, 2026
+**Phien ban**: 2.1
+**Trang thai**: Final
+**Cap nhat lan cuoi**: 31 thang 3, 2026