@educa-corp/sdd-framework 0.9.7 → 0.9.8

package/core/skills/qc/qa-script-designer/_shared/mobile-conventions.md

@@ -0,0 +1,196 @@
+---
+version: 1.0
+updated: 2026-09-09
+new_in: QC-Workflow-Proposal (8-phase) — mobile chưa từng có trong skill set cũ
+---
+
+# Mobile Automation Conventions — TypeScript + WebdriverIO + Appium
+
+Skill **tự chứa**: quy ước bắt buộc khi sinh automation script mobile bằng WebdriverIO +
+Appium + TypeScript, cho app **Flutter** (dev team đang dùng). Mọi file layer trong
+`qa-script-designer/mobile/*` đọc file này trước.
+
+## 0. Vì sao Flutter cần driver riêng (đọc trước khi viết locator)
+
+Flutter tự vẽ UI trên một canvas (Skia), **không** map trực tiếp sang native view tree như
+React Native hay app native thật. Hệ quả: Appium driver chuẩn (`UiAutomator2` Android,
+`XCUITest` iOS) chỉ "thấy" các widget mà Flutter **chủ động expose** qua `Semantics`
+(accessibility tree của OS) — nếu widget không bật `Semantics`/không có `label`, driver chuẩn
+coi như nó không tồn tại, dù mắt người thấy rõ trên màn hình.
+
+**Vì vậy dùng `automationName: 'FlutterIntegration'`** (Appium Flutter Integration Driver,
+dựa trên package `integration_test` của Flutter) — driver này đọc **thẳng Flutter widget
+tree** qua `key` (`ValueKey`), không phụ thuộc accessibility tree của OS. Ổn định hơn nhiều
+cho app Flutter, và đây là driver mặc định của mọi skill trong file này.
+
+```typescript
+// wdio.conf.ts (trích)
+export const config: WebdriverIO.Config = {
+  capabilities: [{
+    platformName: 'Android', // hoặc 'iOS'
+    'appium:automationName': 'FlutterIntegration',
+    'appium:app': process.env.APP_PATH,
+  }],
+};
+```
+
+## 1. Locator Strategy — thứ tự ưu tiên (bắt buộc)
+
+| # | Locator | Khi dùng | Ví dụ |
+|---|---|---|---|
+| 1 | **`ValueKey` contract (test-id Flutter)** | Luôn ưu tiên — tương đương `data-testid` bên web | `$('~login_submit_btn')` (FlutterIntegration map `~` → `ValueKey`) hoặc `driver.$('flutter finder', ...)` tuỳ version |
+| 2 | **Semantics label / accessibility-id** | Widget có bật `Semantics(label: ...)` nhưng chưa gán `Key` | `$('~Đăng nhập')` |
+| 3 | **Text hiển thị** (chỉ static, không lặp) | Không có key/label, element tĩnh duy nhất trên màn | `$('android=new UiSelector().text("Đăng nhập")')` |
+| 4 | **XPath theo cấu trúc widget tree** (bất đắc dĩ) | Không còn lựa chọn nào khác | Luôn kèm `// FIXME: cần ValueKey, xem IMPROVE-xxx` |
+
+**Không dùng làm mức đầu tiên:** toạ độ tuyệt đối (tap theo x/y — vỡ ngay khi đổi kích thước
+màn hình/device), index không filter trên danh sách động, text đa ngôn ngữ dễ đổi.
+
+### 1.1 Contract `ValueKey` với dev Flutter (bắt buộc xác nhận trước khi viết locator)
+
+Tương đương `@trace.testid_attr` bên web — dev phải gán `Key(ValueKey('login_submit_btn'))`
+cho mọi widget tương tác được liệt trong tech-doc §4.5.6. Đọc contract này trước khi viết
+Page Object; thiếu → cảnh báo mềm, fallback Semantics label, và ghi `IMPROVE-xxx` đề nghị dev
+bổ sung `ValueKey`.
+
+### 1.2 Probe widget tree thật trước khi viết locator (bắt buộc nếu §4.5.6 không đủ)
+
+Giống bên web phải "Probe DOM thật" khi SPA thiếu `data-testid`, bên mobile **không được đoán
+`ValueKey`/label từ mắt nhìn màn hình** — phải xác nhận bằng công cụ trước khi viết locator:
+
+- **Appium Inspector** (GUI chính thức của Appium): kết nối cùng `automationName:
+  FlutterIntegration` + capability của app đang test, tap vào widget để xem `ValueKey`/label
+  thật nó expose — không phải cấu trúc DOM/View suy đoán.
+- **Flutter DevTools** (`flutter run` + mở DevTools → Widget Inspector): xem trực tiếp widget
+  tree đang chạy, kể cả khi widget chưa gán `Key` (giúp biết chính xác cần đề nghị dev thêm
+  `Key` ở widget nào, thay vì đoán qua ảnh chụp màn hình).
+
+Không có 1 trong 2 công cụ trên khả dụng (vd môi trường không cài được) → fallback: build app
+debug, chạy tay 1 lần, dựa vào Semantics label nếu bật `flutter run --enable-software-rendering
+--dds-port` kèm accessibility bật trên OS — nhưng đây là **fallback chậm hơn**, ưu tiên 2 công
+cụ trên trước.
+
+## 2. Page Object Model — 3 lớp (bắt buộc, giống cấu trúc web)
+
+```typescript
+// pageobjects/login.page.ts
+import { BasePage } from './base.page';
+
+class LoginPage extends BasePage {
+  // ── Lớp 1: Locators ──
+  private get emailInput() { return $('~login_email_input'); }
+  private get passwordInput() { return $('~login_password_input'); }
+  private get submitBtn() { return $('~login_submit_btn'); }
+
+  // ── Lớp 2: Actions ──
+  async login(email: string, password: string) {
+    await (await this.emailInput).setValue(email);
+    await (await this.passwordInput).setValue(password);
+    await (await this.submitBtn).click();
+  }
+
+  // ── Lớp 3: Assertions ──
+  async assertValidationError(message: string) {
+    await expect($('~login_error')).toHaveText(message);
+  }
+}
+export default new LoginPage();
+```
+
+- `BasePage` gọn: chứa helper chung (chờ app foreground, chụp screenshot).
+- Điều hướng đa màn: mỗi màn 1 Page Object riêng, action trả về hoặc test tự import Page Object
+  màn kế tiếp (module singleton pattern WDIO chuẩn — khác Playwright PO là instance theo `page`).
+
+## 3. Wait & Timing (bắt buộc)
+
+- **Không** `browser.pause(N)` cố định — dùng `waitForDisplayed()`, `waitForEnabled()`,
+  `waitUntil()` của WebdriverIO (auto-retry theo điều kiện).
+- App Flutter cần thời gian dựng frame đầu — dùng `waitForDisplayed({ timeout: 10000 })` cho
+  màn hình đầu sau cold start, không phải `pause`.
+- Thao tác vuốt/scroll trên danh sách dài: dùng gesture helper WDIO (`touchAction`/
+  `$.scrollIntoView()`), không lặp `pause` giữa mỗi lần vuốt.
+
+## 4. Assertion (bắt buộc)
+
+- Dùng matcher `expect(element).toBeDisplayed()/toHaveText()/toBeEnabled()` (WDIO
+  `expect-webdriverio`) — auto-retry, thông báo lỗi rõ.
+- Không `assert` trần trụi; mỗi test assert nội dung/state thật, không chỉ "app không crash".
+
+## 5. Test Independence & Data
+
+- Không hard-code device/app path/credential → biến môi trường (`process.env.*`) hoặc
+  `wdio.conf.ts` theo profile.
+- Reset app state giữa test qua `driver.reset()` hoặc deep-link/API riêng — **không** dựa vào
+  thứ tự test để "dọn" state của nhau.
+- Native permission dialog (camera, location, notification) — xử lý qua Appium
+  `mobile: acceptAlert` / capability tự-cấp quyền khi cài, không tap toạ độ mù.
+
+### 5.1 `noReset` / `fullReset` — chọn đúng đánh đổi tốc độ vs. cách ly
+
+Capability quyết định mức "sạch" của app giữa các phiên chạy — chọn sai làm suite chậm không
+cần thiết **hoặc** flaky do rò rỉ state:
+
+| Capability | Hành vi | Khi dùng |
+|---|---|---|
+| `fullReset: true` | Gỡ cài đặt + cài lại app mỗi session | TC cần trạng thái **cài đặt lần đầu** thật (onboarding, permission dialog lần đầu) — chậm nhất, dùng tối thiểu |
+| `noReset: false` (mặc định, không set `fullReset`) | Xoá app data giữa session nhưng **không** gỡ cài đặt | Mặc định hợp lý cho phần lớn TC — cân bằng tốc độ/cách ly |
+| `noReset: true` | Giữ nguyên toàn bộ data/session giữa các lần chạy | Chỉ dùng cho test **đọc** (không side-effect) hoặc khi đã tự quản lý cleanup qua API riêng — nhanh nhất nhưng rủi ro rò rỉ state nếu dùng sai chỗ |
+
+Nguyên tắc chọn: TC có side-effect (tạo/sửa/xoá data, đổi setting) → không dùng `noReset: true`
+trừ khi có cleanup API riêng đáng tin; TC chỉ đọc/verify hiển thị → `noReset: true` để tăng tốc
+đáng kể cho suite lớn.
+
+### 5.2 Device Farm cho Compatibility testing
+
+Emulator/simulator không thay thế được test trên **thiết bị thật đa dạng OS version/hãng máy**
+— đặc biệt quan trọng cho Android (phân mảnh OS/màn hình lớn hơn iOS nhiều). Khi TC
+compatibility yêu cầu phủ nhiều device/OS thật mà không có đủ máy vật lý, dùng device farm
+(BrowserStack App Automate, Sauce Labs, hoặc Firebase Test Lab) — cấu hình `capabilities` trỏ
+tới farm qua remote WebDriver URL thay vì local Appium server, code test không đổi. Ghi rõ
+trong TC non-functional compatibility: farm nào, danh sách device/OS mục tiêu, vì đây là chi
+phí (thường tính phí theo phút chạy) cần PM/lead duyệt trước khi đưa vào CI thường xuyên.
+
+## 6. Naming & Structure
+
+Vị trí file + quy tắc slug — xem **`_shared/file-naming-and-folders.md`** (nguồn chuẩn duy
+nhất). Quy ước còn lại riêng cho code:
+
+| Gì | Convention |
+|---|---|
+| Test title | `it('TC_xxx — <mô tả ngắn>', async () => {...})` — tag Priority nhúng trong title (xem §6.1, WDIO/Mocha không có `tag` option như Playwright) |
+| Comment trace | `// @trace.verifies={UC-ID}-SC{N}` ngay trên mỗi `it(...)` |
+
+### 6.1 Mapping `Priority` (TC) → tag (script) — bắt buộc, suy tự động
+
+WebdriverIO chạy trên Mocha — không có cơ chế `tag` như Playwright Test, nên tag nhúng ngay
+trong title và lọc bằng `--mochaOpts.grep`. Đọc field `Priority` (`P0`/`P1`/`P2`) từ
+`TC_<FEATURE>.md` — **không tự đặt theo cảm tính**:
+
+| Priority (TC) | Title convention | Lý do |
+|:---:|---|---|
+| `P0` | `it('TC_xxx @smoke @regression — <mô tả>', ...)` | Tính năng lõi — vào cả smoke lẫn regression |
+| `P1`/`P2` | `it('TC_xxx @regression — <mô tả>', ...)` | Chỉ vào regression đầy đủ |
+
+**Chạy riêng smoke suite** (xem `/qc-smoke-test`):
+`npx wdio run wdio.conf.ts --mochaOpts.grep "@smoke"`.
+Review script đối chiếu đúng mapping này — P0 thiếu `@smoke` trong title là lỗi 🟠.
+
+## 7. Common Pitfalls — lỗi thường gặp cần tránh (checklist self-review)
+
+| # | Lỗi | Tại sao sai | Sửa |
+|---|---|---|---|
+| 1 | `browser.pause(5000)` sau mọi action | Chậm, flaky theo tốc độ máy/device thật vs emulator | `waitForDisplayed()`/`waitUntil()` |
+| 2 | Locator theo toạ độ (`tap({x: 100, y: 200})`) | Vỡ ngay khi đổi kích thước màn hình/device khác | `ValueKey`/Semantics label |
+| 3 | Dùng driver `UiAutomator2`/`XCUITest` thuần cho app Flutter không bật Semantics | Driver "mù" phần lớn UI, locator not-found sai lệch thành "bug sản phẩm" | `automationName: FlutterIntegration` + `ValueKey` |
+| 4 | Không reset app state giữa test | Test sau phụ thuộc state test trước — flaky khi chạy lẻ | `driver.reset()` hoặc API/deep-link reset riêng |
+| 5 | Bỏ qua xử lý permission dialog native | Test treo chờ dialog vô thời hạn hoặc tap sai nút | Capability tự-cấp quyền, hoặc `mobile: acceptAlert` |
+| 6 | Test giả định luôn chạy trên 1 kích thước màn hình | Vỡ trên device thật khác resolution/aspect ratio | Locator theo key, tránh toạ độ; test responsive riêng nếu cần |
+| 7 | Không phân biệt cold start vs app đã mở sẵn | Timeout sai (cold start chậm hơn nhiều) | Timeout riêng cho bước launch đầu tiên |
+| 8 | Gộp test Android + iOS chung 1 file không parametrize | Trùng lặp code, khó bảo trì khi 1 platform đổi hành vi | Cấu hình `capabilities` theo platform, share Page Object logic, tách config |
+
+## 8. Compile & Lint (bắt buộc trước khi báo Human approve)
+
+```bash
+npx tsc --noEmit                    # type-check toàn bộ
+npx wdio run wdio.conf.ts --spec ... --dryRun    # nếu runner hỗ trợ; nếu không, review danh sách it() thủ công = số TC Automatable=Y
+```

package/core/skills/qc/qa-script-designer/_shared/web-conventions.md

@@ -0,0 +1,257 @@
+---
+version: 1.0
+updated: 2026-09-09
+source: upstream/qc-base-new/Automation-Standards.md §4 §6 §7 §8 §9 §10 §11 (Approved)
+---
+
+# Web Automation Conventions — TypeScript + Playwright Test
+
+Skill **tự chứa**: quy ước bắt buộc khi sinh automation script web bằng `@playwright/test` +
+TypeScript. Mọi file layer trong `qa-script-designer/web/*` đọc file này trước — không lặp
+lại các quy tắc ở đây, chỉ có phần logic sinh-script riêng của layer.
+
+## 1. Locator Strategy — thứ tự ưu tiên (bắt buộc)
+
+Đây là nguồn lỗi automation phổ biến nhất: locator giòn (fragile) làm script fail không phải
+vì bug sản phẩm mà vì UI đổi CSS/text/thứ tự DOM. Luôn theo đúng thứ tự ưu tiên sau, **dừng ở
+mức đầu tiên khả dụng** — không nhảy xuống mức thấp hơn "cho nhanh":
+
+| # | Locator | Khi dùng | Ví dụ |
+|---|---|---|---|
+| 1 | **Test-ID contract** | Luôn ưu tiên nếu tech-doc có `@trace.testid_attr` + bảng §4.5.6 | `page.getByTestId('login-submit-btn')` |
+| 2 | **Role + Accessible Name** | Không có test-id nhưng element có role/aria chuẩn (button/link/textbox/checkbox…) | `page.getByRole('button', { name: 'Đăng nhập' })` |
+| 3 | **Label** (cho form field) | Input có `<label for>` hoặc `aria-label` | `page.getByLabel('Email')` |
+| 4 | **Text** (chỉ cho element tĩnh, không lặp lại nhiều lần trên trang) | Heading, thông báo, tiêu đề duy nhất | `page.getByText('Đăng nhập thành công')` |
+| 5 | **CSS/XPath theo cấu trúc ổn định** (BEM class, không phải class utility sinh tự động) | Bất khả kháng — không có gì ở trên | `page.locator('.login-form__submit')` |
+
+**Không bao giờ dùng làm mức đầu tiên** (chỉ là fallback bất đắc dĩ, luôn kèm ghi chú
+`// FIXME: cần test-id, xem IMPROVE-xxx`):
+- Class do bundler/CSS-in-JS sinh tự động (`css-1a2b3c`, `sc-hGRVom`, các hash động) — đổi mỗi
+  lần build, **không ổn định giữa các lần deploy**.
+- XPath tuyệt đối/theo vị trí (`/html/body/div[3]/div[2]/button`) — vỡ ngay khi DOM chèn thêm 1
+  node.
+- Index không có điều kiện đi kèm (`.first()`, `nth(2)`) khi danh sách có thể thay đổi thứ tự.
+- Text tiếng Việt cho element có thể đổi copy/đa ngôn ngữ.
+
+**Locator cho danh sách/bảng động:** dùng `locator().filter({ hasText })` hoặc lọc theo
+test-id của row thay vì đếm index cố định; nếu cần verify thứ tự thật (sort/paging), so sánh
+mảng giá trị thay vì giả định vị trí.
+
+### 1.1 Cấu hình test-id attribute (bắt buộc trước khi dùng `getByTestId`)
+
+Đọc `@trace.testid_attr` từ header tech-doc gộp:
+
+| Đọc được | Làm gì |
+|---|---|
+| `data-testid` (mặc định Playwright) | Dùng thẳng `getByTestId()`. |
+| Khác `data-testid` (vd `data-test`, `data-qa`) | **Bắt buộc** cấu hình trước: `playwright.config.ts` → `use: { testIdAttribute: 'data-test' }`. Bỏ bước này → `getByTestId()` luôn tìm `data-testid` mặc định → **locator trượt 100%**, trông giống bug sản phẩm nhưng thực ra là script-bug. |
+| Không có field | Cảnh báo mềm, fallback Role/Text, và ghi `IMPROVE-xxx` đề nghị dev bổ sung field. |
+
+## 2. Page Object Model — 3 lớp (bắt buộc)
+
+```typescript
+// pages/login.page.ts
+import { type Page, type Locator, expect } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class LoginPage extends BasePage {
+  // ── Lớp 1: Locators — chỉ khai báo, KHÔNG hành động ──
+  private readonly emailInput: Locator;
+  private readonly passwordInput: Locator;
+  private readonly submitBtn: Locator;
+
+  constructor(page: Page) {
+    super(page);
+    this.emailInput = page.getByTestId('login-email-input');
+    this.passwordInput = page.getByTestId('login-password-input');
+    this.submitBtn = page.getByTestId('login-submit-btn');
+  }
+
+  // ── Lớp 2: Actions — verb_noun(), trả về Page kế tiếp nếu điều hướng ──
+  async login(email: string, password: string): Promise<DashboardPage> {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitBtn.click();
+    return new DashboardPage(this.page);
+  }
+
+  // ── Lớp 3: Assertions — expect(), không bare assert ──
+  async assertValidationError(message: string): Promise<void> {
+    await expect(this.page.getByTestId('login-error')).toHaveText(message);
+  }
+}
+```
+
+- Kế thừa `BasePage` gọn (chứa `page`, helper chung như `screenshot()`), **không** framework
+  report riêng (Allure…) — reporter là của Playwright Test.
+- Điều hướng giữa màn: action trả về Page Object màn kế tiếp (`return new NextPage(this.page)`)
+  — test chuỗi được `const dashboard = await loginPage.login(...)`.
+- Selector khai báo tập trung ở constructor/đầu class — không rải trong action method.
+- Test **không bao giờ** gọi `page.click()`/`page.fill()` trực tiếp — luôn qua method của PO.
+
+## 3. Report Readability — `test.step()` (bắt buộc)
+
+Playwright Test có `test.step()` built-in — report/trace viewer hiển thị từng step rõ ràng,
+thu gọn được, giúp đọc lại 1 test dài dễ hơn nhiều so với đọc thẳng code:
+
+```typescript
+test('TC_LOGIN_001 — đăng nhập thành công', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+
+  await test.step('Nhập thông tin đăng nhập hợp lệ', async () => {
+    await loginPage.login('user@test.com', 'Password123');
+  });
+
+  await test.step('Xác nhận vào được Dashboard', async () => {
+    await expect(page).toHaveURL(/\/dashboard/);
+  });
+});
+```
+
+Bọc **mỗi chặng có ý nghĩa nghiệp vụ** (không phải mỗi dòng code) bằng `test.step()` — đặc
+biệt quan trọng cho test đa bước (feature đa-màn, E2E journey) nơi report cần chỉ đúng bước
+nào fail thay vì chỉ báo cả `test()` fail chung chung.
+
+## 4. Wait & Timing (bắt buộc)
+
+- **Không bao giờ** `page.waitForTimeout(N)` cố định để "chờ cho chắc" — dùng auto-wait của
+  `expect()`/action locator (Playwright tự retry tới khi actionable hoặc timeout).
+- Sau navigation/submit cần chờ mạng ổn định: `page.waitForLoadState('networkidle')` — nhưng
+  **không** gọi `waitForTimeout` ngay sau đó (thừa, che giấu race condition thật).
+  networkidle không tương thích tốt hoặc app poll liên tục.
+- Verify network call thật: `page.waitForResponse(url => ...)` — không mock trong integration
+  test (mock = unit test, không phải test tích hợp).
+
+## 5. Assertion (bắt buộc)
+
+- Dùng `expect(locator).toHaveText/toBeVisible/toHaveValue(...)` — auto-retry, thông báo lỗi rõ.
+- **Không** `assert someCondition` trần trụi không thông điệp; **không** `assert response` mơ hồ.
+- Mỗi test **assert nội dung thật**, không chỉ assert URL sau điều hướng.
+- Negative case: assert đúng thông báo lỗi cụ thể, không chỉ "có lỗi xuất hiện".
+- **`expect.soft()`** khi cần assert nhiều điều độc lập trong 1 test mà không muốn dừng ngay ở
+  assert đầu tiên fail (vd: kiểm tra đồng thời 5 field hiển thị đúng trên 1 form) — Playwright
+  gom hết soft-assertion fail rồi báo 1 lần cuối test, đọc report đỡ mất công chạy lại từng cái
+  một. **Không lạm dụng**: assertion mang tính điều kiện tiên quyết cho bước sau (vd "đã login
+  chưa") vẫn phải dùng `expect()` thường để dừng ngay, tránh test tiếp tục chạy trên state sai.
+
+## 6. Test Independence & Data
+
+- Không hard-code URL/credential/timeout → `process.env.*` hoặc file `config/env.ts`.
+- Mỗi test độc lập: dữ liệu từ `TEST_DATA_PLAN.md` (factory/fixture), cleanup sau khi tạo.
+- Không global state chia sẻ giữa test; gom test theo (role, account) nếu auth tốn chi phí,
+  qua Playwright `test.describe.serial` có chủ đích — không phải mặc định.
+
+### 6.1 Auth reuse — `storageState` (bắt buộc khi feature cần login)
+
+Login qua UI ở **mỗi** test (điền form, submit, chờ redirect) là nguồn chậm + flaky lớn nhất
+của một suite Playwright — mỗi lần login là một chuỗi network call thật. Best practice chuẩn
+của Playwright: **login một lần trong global setup, lưu lại session, mọi test tái sử dụng**:
+
+```typescript
+// auth.setup.ts — chạy 1 lần trước cả suite (khai trong playwright.config.ts: projects: [{ name: 'setup', testMatch: /auth\.setup\.ts/ }])
+import { test as setup } from '@playwright/test';
+
+setup('authenticate as teacher', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByTestId('login-email-input').fill(process.env.TEACHER_EMAIL!);
+  await page.getByTestId('login-password-input').fill(process.env.TEACHER_PASSWORD!);
+  await page.getByTestId('login-submit-btn').click();
+  await page.waitForURL(/\/dashboard/);
+  await page.context().storageState({ path: 'playwright/.auth/teacher.json' });
+});
+```
+
+```typescript
+// playwright.config.ts (trích) — project phụ thuộc setup, dùng lại storageState
+projects: [
+  { name: 'setup', testMatch: /auth\.setup\.ts/ },
+  { name: 'teacher-tests', use: { storageState: 'playwright/.auth/teacher.json' }, dependencies: ['setup'] },
+],
+```
+
+- Mỗi role cần 1 file storageState riêng (`teacher.json`, `admin.json`…) — khớp `Account` trong
+  `TEST_DATA_PLAN.md`.
+- TC **về chính hành vi login** (validate lỗi sai mật khẩu, khoá tài khoản…) **không** dùng
+  storageState — đó là TC test luôn chính flow login qua UI, không phải TC cần login xong mới
+  test cái khác.
+- File storageState chứa session thật → thêm vào `.gitignore`, không commit.
+
+## 7. Retry & Flaky Quarantine (bắt buộc cấu hình)
+
+Test automation **luôn** có một tỷ lệ flaky nền do timing/network/môi trường CI — coi đó là
+bình thường và có quy trình xử lý có hệ thống, thay vì coi mọi lần fail là product-gap hoặc
+mọi lần pass-sau-retry là "không sao":
+
+```typescript
+// playwright.config.ts (trích)
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,   // CI retry tối đa 2 lần; local KHÔNG retry (fail phải hiện ngay để debug)
+  reporter: [['html'], ['list']],
+});
+```
+
+- **Retry chỉ để hấp thụ nhiễu môi trường CI, không phải để che giấu bug.** Test pass sau
+  retry vẫn hiện trong report là "flaky" (Playwright HTML Report tự đánh dấu `flaky` khác với
+  `passed`) — **không coi là pass sạch**. Đây là tín hiệu `qc-run-script` phải đọc để đưa vào
+  nhóm cần điều tra riêng (xem gate phân loại Fail của `/qc-run-script`), không tự động lờ đi.
+- **Quarantine**: một test flaky lặp lại ≥3 lần chạy gần nhất → tách khỏi suite chính
+  (`test.skip` tạm + tag `@flaky`, hoặc project riêng `flaky-tests` không chặn CI), mở
+  `IMPROVE-xxx`/ghi chú kỹ thuật để điều tra root cause (thường là thiếu `storageState`, thiếu
+  cách ly data, hoặc race condition thật trong sản phẩm) — không để một test flaky nằm mãi
+  trong suite chính làm nhiễu tín hiệu của tất cả lần chạy sau.
+
+## 8. Naming & Structure
+
+Vị trí file + quy tắc slug (`<feature>` từ `TC_<FEATURE>.md`, kiểm tra tồn tại trước khi tạo
+mới khi nhiều UC cùng chạm 1 màn) — xem **`_shared/file-naming-and-folders.md`** (nguồn chuẩn
+duy nhất, không lặp lại bảng path ở đây nữa). Quy ước còn lại riêng cho code:
+
+| Gì | Convention |
+|---|---|
+| Test title | `test('TC_xxx — <mô tả ngắn>', async ({ page }) => {...})` — TC_ID **trong title**, không chỉ comment |
+| Tag | Suy **tự động** từ `Priority` của TC gốc — xem §8.1, không tự chọn tuỳ ý |
+| Comment trace | `// @trace.verifies={UC-ID}-SC{N}` ngay trên mỗi `test(...)` |
+
+### 8.1 Mapping `Priority` (TC) → tag (script) — bắt buộc, suy tự động
+
+`qc-design-script` đọc field `Priority` (`P0`/`P1`/`P2`) đã có sẵn trong `TC_<FEATURE>.md` —
+**không tự đặt tag theo cảm tính**:
+
+| Priority (TC) | Tag gắn vào `test()` | Lý do |
+|:---:|---|---|
+| `P0` | `{ tag: ['@smoke', '@regression'] }` | P0 = tính năng lõi/luồng chính — vừa chạy trong smoke suite (nhanh, mỗi build) vừa nằm trong regression đầy đủ |
+| `P1` | `{ tag: ['@regression'] }` | Quan trọng nhưng không phải lõi — không cần chặn mỗi build, chạy ở regression đầy đủ |
+| `P2` | `{ tag: ['@regression'] }` | Biên/phụ — cùng regression, không vào smoke |
+
+```typescript
+test('TC_LOGIN_001 — đăng nhập thành công', { tag: ['@smoke', '@regression'] }, async ({ page }) => {
+  // ...
+});
+```
+
+**Chạy riêng smoke suite** (xem `/qc-smoke-test`): `npx playwright test --grep @smoke`.
+Review script (`/qc-review`, `qa-reviewer/script/web/*`) đối chiếu đúng mapping này — tag lệch
+Priority (vd P0 nhưng thiếu `@smoke`) là lỗi 🟠 cần sửa, vì nó khiến smoke suite bỏ sót tính
+năng lõi.
+
+## 9. Common Pitfalls — lỗi thường gặp cần tránh (checklist self-review)
+
+| # | Lỗi | Tại sao sai | Sửa |
+|---|---|---|---|
+| 1 | `await page.waitForTimeout(3000)` để "chờ load" | Chậm, flaky (mạng chậm hơn 3s vẫn fail; nhanh hơn thì lãng phí) | `expect(locator).toBeVisible()` / `waitForLoadState` |
+| 2 | Locator theo class hash (`'.css-1x2y3z'`) | Vỡ mỗi lần build lại CSS-in-JS | Test-id contract, hoặc Role/Label |
+| 3 | `test.skip()` không lý do | Không biết TC bị bỏ vì gì, dễ quên xử lý | `test.skip(true, 'GAP-03 — chưa có API reset state')` |
+| 4 | Assertion chỉ ở bước cuối cùng của journey dài | Bug ở giữa flow bị che bởi state cuối đúng "tình cờ" | Assert sau mỗi bước có side-effect quan trọng |
+| 5 | Test phụ thuộc thứ tự chạy (`test B` cần `test A` chạy trước) | Playwright chạy song song mặc định — sinh flaky ngẫu nhiên | Fixture độc lập cho mỗi test, không biến global |
+| 6 | Hard-code data đã tồn tại sẵn trên môi trường (`userId: 42`) | Vỡ khi seed data đổi, không chạy song song được | Tạo qua API/fixture trong `beforeEach`, cleanup `afterEach` |
+| 7 | Bắt exception rồi bỏ qua (`try { ... } catch {}`) để test "luôn xanh" | Che giấu lỗi thật, fake-pass | Không catch; để test fail đúng bản chất |
+| 8 | Dùng `.first()`/`.nth(N)` không kèm filter | Thứ tự phần tử có thể đổi (server-side sort, feature flag) | `.filter({ hasText })`, hoặc locator theo test-id của item |
+| 9 | Test gọi trực tiếp `page.locator(...)` thay vì qua Page Object | Trùng lặp selector nhiều nơi, khó bảo trì khi UI đổi | Mọi interaction qua method PO |
+| 10 | So sánh screenshot toàn trang cho mọi test (visual regression tràn lan) | Flaky theo font/OS/timing render, chi phí review cao | Chỉ dùng visual assertion cho component cụ thể cần, có mask vùng động |
+
+## 10. Compile & Lint (bắt buộc trước khi báo Human approve)
+
+```bash
+npx tsc --noEmit                              # type-check toàn bộ, không build ra file
+npx playwright test --list                    # liệt kê test sẽ chạy — đếm phải khớp số TC Automatable=Y
+```

package/core/skills/qc/qa-script-designer/api/auth.md

@@ -0,0 +1,43 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §5.5 §9.1 · AGT-010 (Approved)
+---
+
+# Sinh script — API xác thực & phân quyền
+
+**Đọc `_shared/api-conventions.md` rồi `endpoint.md` trước.** Đây là phần thêm.
+
+## Khi nào trigger
+- TC kiểm đăng nhập, vòng đời token, hoặc **quyền truy cập theo vai** lên endpoint.
+
+## Phase 1 — Clarify
+Liệt kê **mọi endpoint được bảo vệ** trong phạm vi, và **mọi vai** có trong hợp đồng. Bảng
+vai × endpoint là đầu vào của Phase 2.
+
+## Phase 2 — Generate
+
+**Fixture token theo vai** *(§5.5)* — `fixtures/api.fixture.ts` cấp một context cho mỗi vai.
+Không đăng nhập lại trong từng test: chậm, và dễ chạm rate-limit.
+
+**Mỗi endpoint được bảo vệ sinh đủ ba ca** *(§9.1)*:
+
+| Ca | Mong đợi |
+|---|---|
+| Không token | `401` |
+| Token sai / hết hạn | `401` |
+| Token đúng nhưng **sai vai** | `403` |
+
+Không gộp `401` với `403` — hai lỗi khác nhau: *chưa biết anh là ai* vs *biết rồi nhưng anh
+không được phép*. Gộp là mất khả năng phân biệt lỗi cấu hình xác thực với lỗi phân quyền.
+
+**Assert phải là "bị chặn", không phải "không lỗi":** assert đúng mã, **và** assert body không
+rò dữ liệu của tài nguyên bị cấm.
+
+## Phase 3 — Trace tag + cột `Script file`
+Như `endpoint.md` Phase 3 và Phase 4, `@trace.test_type=functional`.
+
+## Self-review
+- Mỗi endpoint được bảo vệ có đủ 3 ca?
+- Fixture phân biệt **theo vai**, không dùng một token cho mọi test?
+- Không token thật nào nằm trong code?

package/core/skills/qc/qa-script-designer/api/endpoint.md

@@ -0,0 +1,61 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §4 §5 §6 §8 · AGT-010 (Approved)
+---
+
+# Sinh script — API endpoint *(CRUD, mã trạng thái, cấu trúc response)*
+
+**Đọc `_shared/api-conventions.md` trước.** File này chỉ có phần sinh-script riêng của tầng
+endpoint. Lane này dùng khi `active_platform = system`.
+
+## Khi nào trigger
+- Chuyển TC `Automatable: Y` của một endpoint *(từ `AUTOMATION_ASSESSMENT.md`)* thành spec,
+  sau khi `TC_<FEATURE>.Test.md` đã qua `/qc-review-testcase`.
+
+## Khi KHÔNG trigger
+- Xác thực / phân quyền → `auth.md` · biên đầu vào & injection → `security.md`
+- API gọi phụ trợ **bên trong** dự án web *(setup/teardown)* → `web/functional/api.md`
+
+## Phase 1 — Clarify
+
+Đọc `TC_<FEATURE>.Test.md` **chỉ các TC `Automatable: Y`** + `TEST_DATA_PLAN.md`. API Object cho
+resource này đã có chưa → tạo mới nếu chưa. Đọc hợp đồng endpoint từ tech-doc: path · method ·
+payload · mã trạng thái · cấu trúc response.
+
+## Phase 2 — Generate
+
+**Phủ đúng số TC `Automatable: Y`** — đếm trong `AUTOMATION_ASSESSMENT.md` = số `test(...)` phải
+sinh, **không hơn không kém**. TC `Y` mà gặp rào cản kỹ thuật lúc viết → `test.fixme('TC-API-xxx — {lý do}')`
++ ghi `IMPROVE-xxx`, **không âm thầm bỏ qua**.
+
+Gom bằng `test.describe` theo **resource → method**. Mỗi TC một `test()`, tiêu đề mang `TC-API-ID`.
+
+Sinh đủ ba lớp:
+
+| Lớp | File |
+|---|---|
+| API Object | `api-automation/api/<resource>.api.ts` — 1 method = 1 endpoint action |
+| Test data | `api-automation/data/<resource>.data.ts` |
+| Spec | `api-automation/tests/{TICKET-ID}/<feature>-<scenario>.spec.ts` |
+
+## Phase 3 — Trace tag bắt buộc
+
+```typescript
+// @trace.verifies={UC-ID}-SC{N}
+// @trace.source=specs/{domain}/{prd-slug}/bdd/system/{UC-ID}-{slug}.feature
+// @trace.test_type=functional
+```
+
+## Phase 4 — Điền cột `Script file`
+
+Sau khi sinh, **điền đường dẫn thật** vào cột `Script file` của từng TC `Y` trong
+`AUTOMATION_ASSESSMENT.md`. Đây là chỉ mục ngược duy nhất TC → file code; `/qc-run-script` đọc
+đúng cột này để biết chạy file nào.
+
+## Self-review trước khi báo xong
+
+- Số `test()` = số TC `Automatable: Y`?
+- Mọi request đi qua API Object, **không** `request.*` thô trong spec?
+- Mọi test assert **mã trạng thái** + ít nhất một assert về nội dung?
+- `npx tsc --noEmit` sạch và `--list` collect đúng số?

package/core/skills/qc/qa-script-designer/api/security.md

@@ -0,0 +1,41 @@
+---
+version: 1.0
+updated: 2026-09-17
+source: upstream/qc-base-new/API-Testing-Standards.md §8 §9.2 · AGT-010 (Approved)
+---
+
+# Sinh script — API biên đầu vào & injection
+
+**Đọc `_shared/api-conventions.md` rồi `endpoint.md` trước.** Đây là phần thêm.
+
+## Khi nào trigger
+- TC kiểm **biên của đầu vào** hoặc các mẫu injection lên endpoint.
+
+## Phase 1 — Clarify
+Với mỗi trường đầu vào, lấy từ hợp đồng: kiểu · bắt buộc/không · giới hạn min–max · tập giá trị
+hợp lệ. Thiếu ràng buộc trong hợp đồng → ghi `IMPROVE-xxx`, **không tự bịa ngưỡng**.
+
+## Phase 2 — Generate
+
+**Ba kỹ thuật phải thấy được trong code** *(§8)*:
+
+| Kỹ thuật | Sinh gì |
+|---|---|
+| **Phân lớp tương đương** | mỗi lớp ít nhất một ca — không chỉ ca hợp lệ |
+| **Giá trị biên** | với trường có giới hạn: `min-1` · `min` · `max` · `max+1` |
+| **Phủ HTTP method** | gọi method không hỗ trợ → mong đợi `405` |
+
+**Payload injection** *(§9.2)* — gom vào `data/<resource>.data.ts` thành **một bộ dùng lại**,
+không rải trong spec. Phủ đủ các họ: SQL · NoSQL · command · path traversal · XSS lưu trữ.
+
+**Mong đợi phải cụ thể:** `400`/`422` + thông điệp lỗi có cấu trúc, hoặc dữ liệu được làm sạch.
+**Không** assert kiểu *"không sập"* — một endpoint trả `200` kèm dữ liệu đã bị nhiễm vẫn "không sập".
+
+Thêm một assert: thông điệp lỗi **không rò** stack trace, tên bảng, hay phiên bản thư viện.
+
+## Phase 3 — Trace tag + cột `Script file`
+Như `endpoint.md`, `@trace.test_type=non-functional`.
+
+## Ranh giới
+Đây **không** phải kiểm thâm nhập. Sinh script theo TC đã duyệt; **không** tự mở rộng sang dò
+quét lỗ hổng, và **không** kết luận gì về mức an toàn của hệ thống.

package/core/skills/qc/qa-script-designer/mobile/e2e.md

@@ -0,0 +1,35 @@
+---
+version: 1.0
+updated: 2026-09-09
+---
+
+# Gen Script — Mobile E2E Journey (Flutter)
+
+**Đọc `_shared/mobile-conventions.md` trước.**
+
+## Khi nào trigger
+- Convert TC E2E journey (output `qa-designer/e2e/journey.md`, platform `app`), TC Automatable=Y.
+
+## Khi KHÔNG trigger
+- Test 1 màn/field → `functional/*` · 1 điểm tích hợp → `integration.md`
+
+## Quy ước riêng
+- Chuỗi Page Object xuyên các màn; verify V1…Vn sau mỗi chặng.
+- Journey dài trên thiết bị thật/emulator chậm hơn web đáng kể — timeout cho mỗi bước chờ nên
+  rộng hơn mặc định (cold start, animation transition Flutter).
+- Tiền điều kiện (tài khoản, data) qua fixture riêng (`beforeEach`), reset app state
+  (`driver.reset()`) trước mỗi journey — không dựa vào journey trước "dọn" giúp.
+
+## Phase 1 — Clarify
+Các màn/PO + hệ thống verify ngoài (nếu có); tài khoản/data cần dựng.
+
+## Phase 2 — Generate
+Mỗi journey → 1 test; verify đủ V1…Vn. Journey phụ thuộc gap → `it.skip('...GAP-xx')`.
+
+## Phase 3 — Self-Verify
+```bash
+npx tsc --noEmit
+```
+
+## Output
+`mobile-automation/test/specs/{TICKET-ID}/e2e/<feature>-<scenario>.spec.ts` + Page Object tái dùng.