@sun-asterisk/sungen 2.2.2 → 2.3.0

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

@@ -1,513 +0,0 @@
-# Tiêu Chuẩn Gherkin - Cốt Lõi v2
-
-**Á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 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️⃣ Ngữ Pháp (Cấp độ Step)
-
-### Định dạng
-```
-[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` |
-
----
-
-## 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 is on [Login] page
-✅ 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 (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)
-```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
-```
-
----
-
-## 5️⃣ Target (Đối tượng)
-
-### Định dạng
-```
-[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
-```
-
----
-
-## 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í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ụ |
-|------|-------|
-| Ô 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ụ
-```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
-```
-
----
-
-## 🏷️ Tags
-
-### Scenario Tags
-
-| Tag | Mô tả |
-|-----|-------|
-| `@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 |
-
-Tags có thể áp dụng ở **cấp Feature** (kế thừa cho tất cả scenario) hoặc **cấp Scenario** (ghi đè Feature).
-
-**Thứ tự ưu tiên Auth**: Scenario kế thừa `@auth` > Scenario gốc `@auth` > Feature `@auth`
-
-### Step tái sử dụng (@steps / @extend)
-
-Dùng `@steps:<name>` để định nghĩa khối tái sử dụng và `@extend:<name>` để kế thừa:
-
-```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}}
-  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
-```
-
-**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 |
-
----
-
-## 📋 Ví Dụ Hoàn Chỉnh
-
-```gherkin
-Feature: User Authentication
-  Path: /auth/login
-
-  @auth:admin
-  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}}
-
-  @no-auth
-  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 [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
-```
-
----
-
-## ✅ 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
-
----
-
-**Phiên bản**: 2.0
-**Trạng thái**: Final
-**Cập nhật lần cuối**: 19 tháng 3, 2026