spec-lite 1.6.0 → 1.7.1

package/templates/test-executions/test-exec-e2e-auto-template.md

@@ -0,0 +1,300 @@
+---
+id: test-exec-e2e-auto-{F-XXX}-{NNN}-{slug}
+type: test-exec-e2e-auto
+status: draft
+method: automation
+owner: "{SE}"
+feature_id: "{F-XXX}"
+test_design_ref: "main/feature/{F-XXX}-{slug}/test-design.md"
+alt_harness_manual: "./test-exec-e2e-manual.md"
+platform: web
+runner: playwright
+pom_path: "{e2e-root}/pages/{slug}.page.ts"
+spec_path: "{e2e-root}/{slug}.spec.ts"
+fixtures_path: "{e2e-root}/fixtures/"
+referenced_by:
+  - conventions.md > Test Execution Artifacts > test-exec-e2e-auto.md
+  - terms/003-test-exec-buckets.md
+---
+
+<!--
+Canonical format cho .specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/test-exec-e2e-auto.md.
+EXECUTION layer — ephemeral per test cycle. Harness "Playwright / browser automation", owner SE.
+Cover Feature Acceptance Criteria (FAC) end-to-end — journey / consistency / integrity. Xem terms/003.
+
+E2E = SCOPE (FAC qua integration boundary), KHÔNG phải "Playwright". File này là bản render
+AUTOMATION của scope đó; bản render MANUAL (QC walk tay) ở ./test-exec-e2e-manual.md.
+  - e2e-auto và e2e-manual là HAI HARNESS THAY THẾ cho CÙNG một scope — team chọn MỘT theo
+    kỹ năng / độ trưởng thành (manual-only → manual; có automation → auto). KHÔNG chạy song song
+    để đối chiếu → KHÔNG có test-exec-e2e-report. (frontmatter dùng alt_harness_*.)
+  - Cả hai share cùng spine 8-slot + cùng TC-F* để dễ maintain / dễ chuyển harness.
+  - KHÁC func: manual & auto e2e THAY THẾ NHAU HOÀN TOÀN (cùng outcome, cùng cách) — chọn bên nào
+    cũng không mất gì. (func thì auto-only lọt exploratory/visual — xem terms/004.)
+
+KHÔNG versioned: không template_version / migrations, ngoài scope /artifact-audit + /artifact-migrate.
+Derived từ test-design.md → test-design đổi thì REGENERATE.
+
+Source of truth: test-design.md > E2E Test Cases.
+  - ID artifact = TC-F{NNN}-{seq} inherit từ test-design (Covers FAC-F*). KHÔNG tạo ID mới.
+  - {PREFIX}_E2E_F{NNN}_{TYPE}_{seq} (nếu dùng) CHỈ là title test.describe trong *.spec.ts (code).
+  - Coverage master = test-design.md > Traceability Matrix.
+
+E2E phải verify BUSINESS OUTCOME qua integration boundary (UI→API→DB), không chỉ UI state.
+  UI State:         "Success toast visible"                              ← chưa đủ
+  Business Outcome: "Record tồn tại trong DB, hiện trên list, count = N" ← bắt buộc [verify-db]/[verify-api]
+
+Kết quả = CI run. Cột Status (CI) ở §5 phản ánh CI run gần nhất — KHÔNG điền tay.
+-->
+
+# E2E Test Specification (Automation): {Feature Name}
+
+**Feature**: {F-XXX} | **Owner**: {owner} | **Reviewer**: {reviewer} | **Status**: {status}
+
+---
+
+## 1. Context
+
+| **Field** | **Detail** |
+|---|---|
+| **Feature Summary** | {2–3 câu từ frd.md Overview} |
+| **FAC covered** | {FAC IDs — `FAC-F{NNN}-001`, ...} |
+| **E2E Purpose** | Verify business outcome + integration point — không chỉ UI behavior |
+| **Method** | automation — Playwright, Page Object Model, real seeded backend (no API mocking) |
+| **NOT in E2E Scope** | Validation format/length đơn lẻ (→ test-exec-func) · NFR (→ test-exec-nfr) · DM (→ test-exec-dm) |
+| **Source** | [test-design.md](../../../main/feature/{F-XXX}-{slug}/test-design.md) — TC IDs (E2E Test Cases) + Traceability Matrix |
+| **Testid source** | [selector-contract.md](../../../main/feature/{F-XXX}-{slug}/selector-contract.md) — nguồn `data-testid` chung (code gắn + POM dùng cùng nguồn) |
+| **Alt harness** | [test-exec-e2e-manual.md](./test-exec-e2e-manual.md) — bản manual (team chọn 1, không chạy song song) |
+
+---
+
+## 2. Environment & Setup
+
+### 2.1 Authentication
+
+| **Field** | **Value** |
+|---|---|
+| Auth Setup File | `{e2e-root}/auth.setup.ts` |
+| Primary Storage State | `{e2e-root}/.auth/{role}.json` |
+| Env Var (alt) | `E2E_{ROLE}_STORAGE_STATE` / `E2E_{ROLE}_LOGIN_URL` |
+| Cross-scope test | Storage state thứ hai: `E2E_OTHER_STORAGE_STATE` (out-of-scope user) |
+| Auth Strategy | `storageState` reuse — không re-login mỗi test |
+
+### 2.2 Playwright Config
+
+| **Field** | **Value** |
+|---|---|
+| Base URL | `process.env.E2E_BASE_URL` |
+| Default / Expect Timeout | 30 000 ms / 10 000 ms |
+| Async Job Timeout | 60 000 ms (background processing) |
+| Retries (CI) / Workers | 2 / {N} (tránh DB contention) |
+| Video | `on-first-retry` |
+
+### 2.3 Environment Tiers
+
+| **Env** | **Purpose** | **Data** | **Notes** |
+|---|---|---|---|
+| dev | Primary E2E run | Seeded DB | Main E2E environment |
+| stag | Pre-release regression | Anonymized prod data | Gate trước deploy |
+
+### 2.4 Seed Data Requirements
+
+> Phải tồn tại trong DB trước khi E2E chạy. SE cung cấp seed script / fixture.
+
+| **Seed Item** | **Description** | **Required by (TC)** |
+|---|---|---|
+| {seed-1} | {vd: Admin user scope A full permission} | All scenarios |
+| {seed-2} | {vd: Out-of-scope user cho guard scenario} | `TC-F{NNN}-0XX` |
+
+### 2.5 Platform & Viewport Matrix
+
+| **Platform / View** | **Viewport** | **Priority** | **Auth** | **Scenarios** |
+|---|---|---|---|---|
+| Web Desktop | 1440px | P0 | `storageState` | All |
+| Web Tablet | 768px | P1 | `storageState` | journey only |
+| Web Mobile | 375px | P1 | `storageState` | journey only (nếu frd NFR có mobile) |
+
+> frd.md không có mobile NFR → skip Tablet/Mobile.
+
+---
+
+## 3. Coverage
+
+> FAC → E2E TC mapping. Mỗi `TC-F*` phải xuất hiện ở test-design > Traceability Matrix. Design driver = **FAC**.
+
+| **FAC ID** | **Shape** | **Business Outcome cần verify** | **E2E TC** | **Code title (*.spec.ts)** | **Priority** |
+|---|---|---|---|---|---|
+| `FAC-F{NNN}-001` | journey | {vd "Record persisted trong DB"} | `TC-F{NNN}-040` | `{PREFIX}_E2E_F{NNN}_HP_001` | 🔴 P0 |
+| `FAC-F{NNN}-002` | consistency | {vd "Message đồng nhất 3 màn"} | `TC-F{NNN}-041` | `{PREFIX}_E2E_F{NNN}_HP_002` | 🟡 P1 |
+| `FAC-F{NNN}-003` | integrity | {vd "Xóa account → cascade xóa order"} | `TC-F{NNN}-042` | `{PREFIX}_E2E_F{NNN}_SEC_001` | 🔴 P0 |
+
+**Excluded TCs (→ manual-only):** {TC ranges + lý do — vd Autoable=NO visual, hoặc validation đơn lẻ → test-exec-func}
+
+| **Metric** | **Value** |
+|---|---|
+| FAC covered by E2E | {n} / {total} ({%}) |
+| E2E TC automated | {n} / {total} ({%}) |
+
+---
+
+## 4. Integration Points & Data Flow
+
+> E2E verify **mọi integration boundary** trong business flow, không chỉ UI feedback.
+
+### 4.1 Integration Map
+
+```mermaid
+flowchart TD
+    U([User / Browser]) -->|HTTP| FE[Frontend]
+    FE -->|REST| API[Backend API]
+    API -->|ORM| DB[(Database)]
+    API -.->|async job| Q[Job Queue / Worker]
+    Q --> DB
+    API -.->|optional| EXT[External Service]
+```
+
+### 4.2 Integration Points Table
+
+| **ID** | **Integration Point** | **From → To** | **Trigger** | **Playwright Verification** | **Failure Expected** |
+|---|---|---|---|---|---|
+| `INT-01` | {request accepted} | Browser → API | {method + endpoint} | `[assert]` HTTP 2xx via `page.waitForResponse()` | HTTP 4xx → error shown |
+| `INT-02` | {async job completes} | API Queue → DB | background | `[wait]` result element visible (60s) | timeout → job failed |
+| `INT-03` | {data persisted} | DB → API → FE | subsequent GET | `[verify-db]` navigate list → count đúng | missing → data loss |
+| `INT-04` | {scope guard} | Browser → API middleware | cross-scope request | `[assert]` HTTP 403 / redirect | bypassed → security bug |
+
+### 4.3 Data Flow Validation
+
+| **Data Point** | **Source** | **Expected Value** | **Verification** |
+|---|---|---|---|
+| {records} | DB | {N records, status=X} | navigate list → count = N |
+| {scope isolation} | DB | {out-scope user thấy 0} | login out-scope → list empty / 403 |
+
+---
+
+## 5. Test Cases
+
+> **TC ID:** inherit từ test-design (E2E Test Cases) — `TC-F{NNN}-{seq}`, stable. KHÔNG tạo ID mới.
+>
+> **Step prefix:** `[goto]` navigate | `[action]` interact | `[wait]` async state | `[assert]` UI check | `[verify-db]` navigate+confirm DB | `[verify-api]` HTTP status/body | `[download]` file | `[teardown]` afterEach hook ONLY.
+>
+> **Quy tắc `[verify-db]`:** navigate RA KHỎI trang hiện tại → trang khác → assert data tồn tại. Toast/success message KHÔNG đủ (hiện trước khi async job xong).
+> **Quy tắc `[verify-api]`:** dùng `page.request` (không phải `fetch`) để kế thừa auth cookie từ `storageState`.
+>
+> **Status (CI):** `—` (chưa viết) | `🟢 green` | `🔴 red` | `⏭ skipped` | `🟡 flaky`. **Không điền tay** — phản ánh CI run gần nhất.
+
+### 5.1 Journey / Happy Path
+
+> Verify complete business flow đến outcome cuối. ≥ 1 `[verify-db]` step mỗi scenario.
+
+| **E2E TC** | **FAC** | **Persona** | **Pre-Conditions** | **Playwright Steps** | **Business Outcome** | **Status (CI)** | **Priority** |
+|---|---|---|---|---|---|---|---|
+| `TC-F{NNN}-040` | `FAC-F{NNN}-001` | {persona} | 1. {precondition}<br>2. {seed exists} | 1. [goto] `pom.goto{Page}()`<br>2. [action] `pom.{action}({arg})`<br>3. [wait] `pom.{wait}()`<br>4. [assert] `expect(pom.{loc}()).toBeVisible()`<br>5. [action] `pom.{confirm}().click()`<br>6. [verify-db] `pom.goto{List}()` → `expect(pom.{count}()).toContainText('{N}')` | • {N} records persisted<br>• Hiện trên {page} đúng status<br>• State persist qua refresh | — | 🔴 P0 |
+
+### 5.2 Consistency (đa màn)
+
+> So khớp UI/behavior nhiều màn. Verify identical (text/style/rule) — không cần journey tuần tự.
+
+| **E2E TC** | **FAC** | **Pre-Conditions** | **Playwright Steps** | **Expected** | **Status (CI)** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-041` | `FAC-F{NNN}-002` | {N màn accessible} | 1. [action] trigger {behavior} ở màn A<br>2. [action] … ở màn B<br>3. [action] … ở màn C<br>4. [assert] so 3 kết quả | • {behavior} identical across màn A/B/C | — | 🟡 P1 |
+
+### 5.3 Integrity (bất biến liên story, không tuần tự)
+
+> Assert business invariant sau khi kết hợp nhiều story. Verify trạng thái nhất quán cuối + **no side effect** ngoài invariant.
+
+| **E2E TC** | **FAC** | **Pre-Conditions** | **Playwright Steps** | **Expected (invariant)** | **Status (CI)** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-042` | `FAC-F{NNN}-003` | {baseline state} | 1. [verify-db] baseline count/state<br>2. [action] thao tác story X<br>3. [action] thao tác story Y<br>4. [verify-db] assert invariant | • {vd: xóa account → 0 order còn sót ở mọi module}<br>• Tổng/đối soát khớp | — | 🔴 P0 |
+
+### 5.4 Negative / Guard *(nếu FAC có)*
+
+> Verify guard tại integration boundary — confirm error **VÀ** no side effect (no DB write).
+> Pattern: `[verify-db]` baseline → trigger error → `[assert]` error+guard → `[verify-db]` count = baseline.
+
+| **E2E TC** | **FAC** | **Pre-Conditions** | **Playwright Steps** | **Expected** | **Status (CI)** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-0XX` | `FAC-F{NNN}-00N` | {invalid condition} | 1. [verify-db] baseline N<br>2. [action] {invalid}<br>3. [assert] error + guard disabled<br>4. [verify-db] count còn = N | • Error hiển thị<br>• **No new record** (count = N) | — | 🔴 P0 |
+
+---
+
+## 6. Fixtures & Test Data
+
+> Provisioning tự động — fixture file / factory. File tại `{fixtures_path}`. SE tạo trước khi viết test.
+
+| **File / Factory** | **Type** | **Content** | **Used by (TC)** |
+|---|---|---|---|
+| `{file-1}` | {Excel/JSON/factory} | {vd: 5 valid rows, no dup} | `TC-F{NNN}-040` |
+| `{file-2}` | {…} | {vd: header mismatch} | `TC-F{NNN}-0XX` |
+
+---
+
+## 7. Execution
+
+### 7.1 Page Object Index
+
+> POM class implement locators/methods dùng ở §5. File: `{pom_path}`
+
+#### Class: `{PageObjectClassName}`
+
+| **Area** | **Method** | **Returns** | **Description** |
+|---|---|---|---|
+| Navigation | `goto{Page}(): Promise<void>` | void | navigate + `waitForLoadState('networkidle')` |
+| {UI Area} | `{locator}(): Locator` | Locator | {element} |
+| {UI Area} | `{action}(arg): Promise<void>` | void | {action} |
+
+> **Selector Strategy** (thứ tự ưu tiên): `getByTestId` → `getByRole` → `getByLabel` → `locator([data-attr])`.
+> **Testid lấy từ `selector-contract.md`** của feature — nguồn CHUNG: code gắn + test dùng cùng một nguồn nên không lệch (xem `conventions.md` §3.3). Element cần testid mà contract chưa có → **bổ sung vào selector-contract** rồi để FE gắn, KHÔNG tự đặt testid rời ở đây. (Biểu thức `getByTestId(...)` sống trong POM `.ts`; file này chỉ index method.)
+
+### 7.2 Automation Artifacts
+
+| **File** | **Type** | **Description** |
+|---|---|---|
+| `{spec_path}` | Test spec | `test.describe(...)` blocks |
+| `{pom_path}` | Page Object | locators + actions |
+| `{fixtures_path}{files}` | Test data | xem §6 |
+
+### 7.3 Commands
+
+```bash
+npx playwright test {slug}.spec.ts                 # full suite
+npx playwright test {slug}.spec.ts --grep "HP"     # journey only
+npx playwright test {slug}.spec.ts --headed        # debug
+npx playwright show-report
+```
+
+### 7.4 CI Gate
+
+| **Trigger** | **Scope** | **Gate** |
+|---|---|---|
+| PR → develop | journey P0 smoke | block merge nếu fail |
+| Merge → develop | full suite | alert nếu fail |
+| Deploy → staging | full suite on stag | block release nếu P0 fail |
+| Nightly | full + edge | report only |
+
+### 7.5 Success Criteria & Exit
+
+**Must Have — P0 (block deploy nếu fail):**
+- [ ] Mọi journey scenario pass — business outcome verified (không chỉ UI)
+- [ ] Mọi guard scenario pass — boundary enforced tại API layer
+- [ ] `[verify-db]` steps pass — data thực sự persisted
+- [ ] Không integrity invariant nào vi phạm
+
+**Should Have — P1:** consistency pass · negative graceful · no flaky (3/3 runs) · journey pass trên Tablet
+**Nice to Have — P2:** journey pass trên Mobile · suite < 5 phút
+
+### 7.6 Risk & Mitigation
+
+| **Risk** | **Impact** | **Mitigation** |
+|---|---|---|
+| Flaky: async job timing | High | `waitFor({ state:'visible', timeout })` — không `sleep` |
+| `[verify-db]` false positive (stale cache) | High | navigate + `page.reload()` trước assert |
+| Test data contamination | High | `[teardown]` cleanup mỗi test tạo record |
+| Auth storage state expired | Medium | `auth.setup.ts` chạy trước suite |
+| Locators fragile khi UI refactor | Medium | ưu tiên `data-testid` |
+
+---
+
+## 8. Change Log
+
+| **Date** | **Cycle** | **Changes** | **Author** |
+|---|---|---|---|
+| {YYYY-MM-DD} | {cycle/release} | Initial E2E automation spec (derive từ test-design.md E2E Test Cases) | {Author} |

package/templates/test-executions/test-exec-e2e-manual-template.md

@@ -0,0 +1,231 @@
+---
+id: test-exec-e2e-manual-{F-XXX}-{NNN}-{slug}
+type: test-exec-e2e-manual
+status: draft
+method: manual
+owner: "{QC}"
+feature_id: "{F-XXX}"
+test_design_ref: "main/feature/{F-XXX}-{slug}/test-design.md"
+alt_harness_auto: "./test-exec-e2e-auto.md"
+platform: web
+referenced_by:
+  - conventions.md > Test Execution Artifacts > test-exec-e2e-manual.md
+  - terms/003-test-exec-buckets.md
+---
+
+<!--
+Canonical format cho .specs/test-executions/{F-XXX}-{slug}/{NNN}-{cycle-slug}/test-exec-e2e-manual.md.
+EXECUTION layer — ephemeral per test cycle. Harness "GUI walk tay (QC) — verify outcome qua điều hướng sản phẩm", owner QC.
+Cover Feature Acceptance Criteria (FAC) end-to-end — journey / consistency / integrity. Xem terms/003.
+
+E2E = SCOPE (FAC qua integration boundary), KHÔNG phải "Playwright". File này là bản render
+MANUAL của scope đó; bản render AUTOMATION (SE Playwright) ở ./test-exec-e2e-auto.md.
+  - e2e-manual và e2e-auto là HAI HARNESS THAY THẾ cho CÙNG một scope — team chọn MỘT theo
+    kỹ năng / độ trưởng thành. KHÔNG chạy song song để đối chiếu → KHÔNG có
+    test-exec-e2e-report. (frontmatter dùng alt_harness_*.)
+  - Cả hai share cùng spine 8-slot + cùng TC-F* để dễ maintain / dễ chuyển harness.
+  - KHÁC func: manual & auto e2e THAY THẾ NHAU HOÀN TOÀN — chọn bên nào cũng không mất gì.
+    (func thì auto-only lọt exploratory/visual.)
+
+QC verify business outcome KHÔNG bằng code/DB query, mà bằng ĐIỀU HƯỚNG QUA SẢN PHẨM:
+  tạo data → RỜI màn hiện tại → sang màn list/detail/admin → xác nhận data thật (count/status).
+  Toast/success message KHÔNG đủ làm bằng chứng (hiện trước khi job xong) — đây là [verify-screen] bằng tay.
+  3 thứ QC không soi trực tiếp được — raw DB row/checksum · HTTP status/body · queue-level job —
+    → hạ xuống "quan sát qua product", hoặc tab Network của devtools (nhẹ), hoặc nhờ DEV kiểm hộ. Ghi rõ ở Note.
+
+KHÔNG versioned: không template_version / migrations, ngoài scope /artifact-audit + /artifact-migrate.
+Derived từ test-design.md → test-design đổi thì REGENERATE (archive cycle cũ trước nếu đã có Test Result).
+
+Source of truth: test-design.md > E2E Test Cases.
+  - ID = TC-F{NNN}-{seq} inherit từ test-design (Covers FAC-F*). KHÔNG tạo ID mới.
+  - Coverage master = test-design.md > Traceability Matrix.
+
+Test Result column là nơi DUY NHẤT QC cập nhật trạng thái thực thi (manual).
+-->
+
+# E2E Test Specification (Manual): {Feature Name}
+
+**Feature**: {F-XXX} | **Owner**: {owner} | **Reviewer**: {reviewer} | **Status**: {status}
+
+---
+
+## 1. Context
+
+| **Field** | **Detail** |
+|---|---|
+| **Feature Summary** | {2–3 câu từ frd.md Overview} |
+| **FAC covered** | {FAC IDs — `FAC-F{NNN}-001`, ...} |
+| **E2E Purpose** | Verify business outcome + integration point — không chỉ UI behavior |
+| **Method** | manual — QC walk journey trên GUI, verify outcome bằng điều hướng qua sản phẩm |
+| **NOT in E2E Scope** | Validation format/length đơn lẻ (→ test-exec-func-manual) · NFR (→ test-exec-nfr) · DM (→ test-exec-dm) |
+| **Source** | [test-design.md](../../../main/feature/{F-XXX}-{slug}/test-design.md) — TC IDs (E2E Test Cases) + Traceability Matrix |
+| **Alt harness** | [test-exec-e2e-auto.md](./test-exec-e2e-auto.md) — bản automation (team chọn 1, không chạy song song) |
+
+---
+
+## 2. Environment & Setup
+
+### 2.1 Test Account & Role Matrix
+
+> QC login tay bằng các tài khoản dưới đây. Xóa role không dùng.
+
+| **Role** | **Username** | **Password** | **Scope / Access** | **Dùng cho** |
+|---|---|---|---|---|
+| {Admin scope A} | {admin@test} | {TBD} | Full trong scope A | journey + integrity |
+| {Out-of-scope user} | {other@test} | {TBD} | Ngoài scope A | guard / isolation |
+
+### 2.2 Environment Tiers
+
+| **Env** | **Purpose** | **Data** | **Notes** |
+|---|---|---|---|
+| dev | Primary E2E walk | Seeded DB | Môi trường chính |
+| stag | Pre-release regression | Anonymized prod data | Gate trước deploy |
+
+### 2.3 Seed Data Requirements
+
+> Phải tồn tại trong DB trước khi walk. QC nhờ SE/DEV seed nếu không tạo được bằng GUI.
+
+| **Seed Item** | **Description** | **Required by (TC)** |
+|---|---|---|
+| {seed-1} | {vd: Admin scope A full permission} | All scenarios |
+| {seed-2} | {vd: Out-of-scope user} | `TC-F{NNN}-0XX` |
+
+### 2.4 Platform & Viewport Matrix
+
+| **Platform / View** | **Viewport** | **Priority** | **Scenarios** |
+|---|---|---|---|
+| Web Desktop | 1440px | P0 | All |
+| Web Tablet | 768px | P1 | journey only |
+| Web Mobile | 375px | P1 | journey only (nếu frd NFR có mobile) |
+
+> frd.md không có mobile NFR → skip Tablet/Mobile.
+
+---
+
+## 3. Coverage
+
+> FAC → E2E TC mapping. Mọi `TC-F*` phải xuất hiện ở test-design > Traceability Matrix. Planning only — execution result track ở §5 cột Test Result.
+
+| **FAC ID** | **Shape** | **Business Outcome cần verify** | **E2E TC** | **Priority** |
+|---|---|---|---|---|
+| `FAC-F{NNN}-001` | journey | {vd "5 record persisted, hiện trên list"} | `TC-F{NNN}-040` | 🔴 P0 |
+| `FAC-F{NNN}-002` | consistency | {vd "Message đồng nhất 3 màn"} | `TC-F{NNN}-041` | 🟡 P1 |
+| `FAC-F{NNN}-003` | integrity | {vd "Xóa account → 0 order sót"} | `TC-F{NNN}-042` | 🔴 P0 |
+
+**Coverage:** {n}/{total} FAC covered ({%}).
+
+---
+
+## 4. Integration Points & Data Flow
+
+> E2E verify **mọi integration boundary** trong business flow. QC không gọi API/DB trực tiếp → verify mỗi boundary bằng **quan sát qua sản phẩm**.
+
+### 4.1 Integration Map
+
+```mermaid
+flowchart TD
+    U([User / Browser]) -->|thao tác| FE[Frontend]
+    FE -->|gửi request| API[Backend API]
+    API -->|lưu| DB[(Database)]
+    API -.->|async job| Q[Job Queue / Worker]
+    Q --> DB
+    API -.->|optional| EXT[External Service]
+```
+
+### 4.2 Integration Points — Manual Verification
+
+| **ID** | **Integration Point** | **Trigger** | **Manual Verification (qua product)** | **Nếu hỏng** |
+|---|---|---|---|---|
+| `INT-01` | {request accepted} | {thao tác} | Màn chuyển loading→success **và** record xuất hiện ở bước sau (không chỉ toast) | báo lỗi đỏ / không đổi |
+| `INT-02` | {async job completes} | background | Đợi tới khi element kết quả hiện (≤60s), refresh nếu cần | quá lâu → job failed |
+| `INT-03` | {data persisted} | sau khi submit | **Rời màn hiện tại** → sang màn list → đếm/đọc data đúng | thiếu → data loss |
+| `INT-04` | {scope guard} | login user out-scope | List rỗng / báo 403 / redirect | thấy data → security bug |
+
+> 3 boundary QC không soi trực tiếp được (HTTP status, raw DB row, queue) → suy ra qua product như trên, hoặc dùng tab **Network** của devtools (nhẹ), hoặc nhờ DEV kiểm.
+
+---
+
+## 5. Test Cases
+
+> **TC ID:** inherit từ test-design (E2E Test Cases) — `TC-F{NNN}-{seq}`, stable. KHÔNG tạo ID mới.
+>
+> **Step prefix (manual):** `[goto]` mở trang/URL · `[action]` thao tác (click/nhập) · `[wait]` đợi async / refresh · `[verify-screen]` **rời sang màn khác xác nhận data thật** (= `[verify-db]` bằng tay) · `[check-network]` *(tùy chọn)* xem HTTP status ở devtools · `[teardown]` dọn data sau test.
+>
+> **Quy tắc `[verify-screen]`:** RỜI khỏi màn hiện tại → sang màn list/detail/admin → xác nhận data (count/status). Toast/success message KHÔNG đủ làm bằng chứng.
+>
+> **Test Result:** `—` (chưa chạy) | `✅ Pass` | `❌ Fail` | `⛔ Blocked` | `🔴 HOLD` | `N/A`.
+
+### 5.1 Journey / Happy Path
+
+> Walk complete business flow đến outcome cuối. ≥ 1 `[verify-screen]` mỗi scenario.
+
+| **E2E TC** | **FAC** | **Role** | **Pre-Conditions** | **Manual Steps** | **Business Outcome (Expected)** | **Test Result** | **Priority** |
+|---|---|---|---|---|---|---|---|
+| `TC-F{NNN}-040` | `FAC-F{NNN}-001` | {role} | 1. {precondition}<br>2. {seed exists} | 1. [goto] Mở `{/path}`<br>2. [action] {thao tác + nhập data}<br>3. [wait] Đợi {kết quả} hiện<br>4. [action] Bấm Confirm<br>5. [verify-screen] Sang `{/list}` → đếm/đọc data đúng<br>6. [wait] Refresh → data còn nguyên | • {N} record persisted, hiện trên {màn} đúng status<br>• State persist qua refresh<br>• (Toast KHÔNG dùng làm bằng chứng) | — | 🔴 P0 |
+
+### 5.2 Consistency (đa màn)
+
+> So khớp UI/behavior nhiều màn. Mắt người so trực tiếp — không cần journey tuần tự.
+
+| **E2E TC** | **FAC** | **Pre-Conditions** | **Manual Steps** | **Expected** | **Test Result** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-041` | `FAC-F{NNN}-002` | {N màn accessible} | 1. [action] trigger {behavior} ở màn A<br>2. [action] … màn B<br>3. [action] … màn C<br>4. [verify-screen] so 3 kết quả | • {behavior} identical (text/style/rule) across A/B/C | — | 🟡 P1 |
+
+### 5.3 Integrity (bất biến liên story, không tuần tự)
+
+> Assert business invariant sau khi kết hợp nhiều story. Verify trạng thái cuối + no side effect.
+
+| **E2E TC** | **FAC** | **Pre-Conditions** | **Manual Steps** | **Expected (invariant)** | **Test Result** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-042` | `FAC-F{NNN}-003` | {baseline state} | 1. [verify-screen] ghi baseline count/state<br>2. [action] thao tác story X<br>3. [action] thao tác story Y<br>4. [verify-screen] kiểm invariant ở các màn liên quan | • {vd: xóa account → 0 order sót ở mọi module}<br>• Tổng/đối soát khớp | — | 🔴 P0 |
+
+### 5.4 Negative / Guard *(nếu FAC có)*
+
+> Verify guard tại boundary — confirm error **VÀ** no side effect.
+> Pattern: `[verify-screen]` baseline → trigger error → `[action]` thấy error+guard → `[verify-screen]` count = baseline.
+
+| **E2E TC** | **FAC** | **Pre-Conditions** | **Manual Steps** | **Expected** | **Test Result** | **Priority** |
+|---|---|---|---|---|---|---|
+| `TC-F{NNN}-0XX` | `FAC-F{NNN}-00N` | {invalid condition} | 1. [verify-screen] baseline N<br>2. [action] {invalid}<br>3. [action] thấy error + guard chặn<br>4. [verify-screen] count còn = N | • Error hiển thị<br>• **No new record** (count = N) | — | 🔴 P0 |
+
+---
+
+## 6. Fixtures & Test Data
+
+> Manual không có factory tự động — file / data chuẩn bị tay (hoặc nhờ SE) trước khi walk.
+
+| **File / Data-set** | **Type** | **Content** | **Used by (TC)** |
+|---|---|---|---|
+| `{file-1}` | {Excel/JSON} | {vd: 5 valid rows, no dup} | `TC-F{NNN}-040` |
+| `{file-2}` | {…} | {vd: header mismatch} | `TC-F{NNN}-0XX` |
+
+---
+
+## 7. Execution
+
+### 7.1 Entry & Exit Criteria
+
+| | Criteria |
+|---|---|
+| **Entry** *(bắt đầu walk khi)* | frd.md approved · test-design.md exists · env running · seed data ready · account configured |
+| **Exit** *(done khi)* | Mọi journey + integrity P0 pass (business outcome verified) · guard pass · không open Critical bug · Test Result updated đầy đủ |
+| **Suspend** *(tạm dừng nếu)* | Bất kỳ P0 blocked · env down · integration boundary hỏng chặn walk |
+
+### 7.2 Execution Order
+
+> journey (P0) → integrity (P0) → guard → consistency. Bất kỳ P0 fail → STOP, raise bug.
+
+### 7.3 Success Criteria
+
+- [ ] Mọi journey scenario pass — business outcome verified (`[verify-screen]`, không chỉ toast)
+- [ ] Mọi guard scenario pass — out-scope không thấy / không ghi được data
+- [ ] Không integrity invariant nào vi phạm
+- [ ] Test Result column updated đầy đủ
+
+---
+
+## 8. Change Log
+
+| **Date** | **Cycle** | **Changes** | **Author** |
+|---|---|---|---|
+| {YYYY-MM-DD} | {cycle/release} | Initial E2E manual spec (derive từ test-design.md E2E Test Cases) | {Author} |