@relipa/ai-flow-kit 0.1.2 → 0.1.3

package/README.md

@@ -91,6 +91,7 @@ npm uninstall -g @relipa/ai-flow-kit
 |---------|-------------|
 | `aiflow init` | Setup framework, adapters, and multi-AI rules. |
 | `aiflow use <ticket...>` | Load context from one or more tickets/files. First target is primary; rest become supplementary. |
+| `aiflow execute <target>` | **QA:** Execute test cases — load TC file, sync Playwright scripts, run and collect evidence. |
 | `aiflow fetch-links <url>` | Fetch a Backlog/Jira link and print SupplementaryContext JSON (used by AI at runtime). |
 | `aiflow task` | Manage multiple tasks — pause, switch, resume. |
 | `aiflow task next` | Finalize gate approval and prepare for fresh session. |
@@ -141,6 +142,31 @@ aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 
 ---
 
+### `aiflow execute <target>`
+
+Execute test cases from a Backlog/Jira ticket, a TC file, or manually. The AI syncs Playwright scripts, runs them, collects evidence, and generates a test report.
+
+```bash
+# From a ticket (taskType must be "execute")
+aiflow execute PROJ-44
+
+# From a TC file directly
+aiflow execute ./testcases/AD10.md
+
+# Manual — AI asks for TC file path
+aiflow execute
+```
+
+**What happens (4-gate Execute Flow):**
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` exists, check `BASE_URL` and `playwright.config.ts`
+2. **Gate 2 — Script Sync:** Hash-based TC↔script sync — gen new, update changed, skip unchanged (never fabricates selectors — uses Playwright MCP)
+3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence per `run-{N}/`, update TC file R1/R2 columns
+4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, ask per-bug Jira confirmation
+
+> **Multi-AI:** Works with Claude, Gemini, Cursor, Copilot — the execute-flow skill is loaded via `ak init`/`ak up`.
+
+---
+
 ### `aiflow sync-skills`
 
 Synchronize AI instruction files (`CLAUDE.md`, `GEMINI.md`, etc.) and Skills without upgrading the package version. 

package/bin/aiflow.js

@@ -19,6 +19,7 @@ const taskCommand     = require('../scripts/task');
 const checkpointCommand = require('../scripts/checkpoint');
 const { record }      = require('../scripts/telemetry/record');
 const { updateTaskGateState } = require('../scripts/task');
+const scaffoldPlaywrightCommand = require('../scripts/scaffold-playwright');
 const semver = require('semver');
 const { execSync: execSyncChild, spawnSync } = require('child_process');
 
@@ -63,7 +64,8 @@ program
             'up': 'update',
             'sync': 'sync-skills',
             'dr': 'doctor',
-            'tel': 'telemetry'
+            'tel': 'telemetry',
+            'sc': 'scaffold'
         };
         if (aliases[first]) {
             first = aliases[first];
@@ -575,4 +577,41 @@ program
         telemetryCommand(action || 'status', options);
     });
 
+// ── scaffold ──────────────────────────────────────────────────
+const scaffoldCmd = program.command('scaffold').alias('sc').description('Scaffold project harness files');
+
+scaffoldCmd
+    .command('playwright')
+    .alias('pw')
+    .description('Scaffold Playwright E2E harness (playwright.config.ts, BasePage, fixtures, auth, .mcp.json)')
+    .option('-f, --force', 'overwrite existing files')
+    .option('-d, --dir <path>', 'target directory (default: current directory)')
+    .addHelpText('after', `
+Examples:
+  $ ak scaffold playwright                  Scaffold into current directory
+  $ ak scaffold playwright --force          Overwrite existing files
+  $ ak scaffold playwright --dir ./my-app   Scaffold into ./my-app
+
+Next steps after scaffolding:
+  1. npm install --save-dev @playwright/test
+  2. npx playwright install chromium
+  3. cp .env.example .env  # then fill in BASE_URL
+  4. npx playwright test
+`)
+    .action(async (options) => {
+        const targetDir = options.dir ? require('path').resolve(options.dir) : process.cwd();
+        console.log(chalk.cyan('\n⟳ Scaffolding Playwright E2E harness...\n'));
+        const result = await scaffoldPlaywrightCommand.scaffoldPlaywright(targetDir, { force: !!options.force });
+        console.log(chalk.cyan('\n📦 Next steps:'));
+        console.log(chalk.gray('  1. npm install --save-dev @playwright/test'));
+        console.log(chalk.gray('  2. npx playwright install chromium'));
+        console.log(chalk.gray('  3. cp .env.example .env  # then fill in BASE_URL'));
+        console.log(chalk.gray('  4. npx playwright test'));
+        if (result.copied.length === 0 && result.skipped.length > 0) {
+            console.log(chalk.yellow('\n  ⚠ All files already exist. Use --force to overwrite.\n'));
+        } else {
+            console.log(chalk.green('\n✨ Scaffold complete!\n'));
+        }
+    });
+
 program.parse(process.argv);

package/custom/harness/playwright/.env.example

@@ -0,0 +1,10 @@
+# Sao chép thành .env rồi điền giá trị. KHÔNG commit .env (đã .gitignore).
+
+BASE_URL=http://localhost:3000
+
+# --- Đăng nhập — chỉ cần khi app yêu cầu login ---
+# Có E2E_USER → auth tự bật: đăng nhập 1 lần, lưu phiên, các test tái dùng.
+E2E_USER=
+E2E_PASSWORD=
+E2E_LOGIN_PATH=/login
+E2E_POST_LOGIN_PATH=/dashboard

package/custom/harness/playwright/playwright.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig, devices } from '@playwright/test';
+
+try { require('dotenv').config(); } catch (_) {}
+
+const baseURL = process.env.BASE_URL || 'http://localhost:3000';
+const authFile = 'tests/e2e/.auth/user.json';
+const useAuth = Boolean(process.env.E2E_USER);
+
+export default defineConfig({
+  testDir: './tests/e2e/specs',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['list'],
+  ],
+  use: {
+    baseURL,
+    screenshot: 'only-on-failure',
+    video: 'on-first-retry',
+    trace: 'on-first-retry',
+  },
+  projects: useAuth
+    ? [
+        { name: 'setup', testMatch: /auth\.setup\.ts/ },
+        {
+          name: 'chromium',
+          use: { ...devices['Desktop Chrome'], storageState: authFile },
+          dependencies: ['setup'],
+        },
+      ]
+    : [{ name: 'chromium', use: devices['Desktop Chrome'] }],
+});

package/custom/harness/playwright/tests/e2e/auth.setup.ts

@@ -0,0 +1,25 @@
+import { test as setup, expect } from '@playwright/test';
+import * as path from 'path';
+
+const authFile = path.join('tests', 'e2e', '.auth', 'user.json');
+
+setup('xác thực', async ({ page }) => {
+  const user = process.env.E2E_USER;
+  const password = process.env.E2E_PASSWORD;
+  const loginPath = process.env.E2E_LOGIN_PATH || '/login';
+  const postLoginPath = process.env.E2E_POST_LOGIN_PATH || '/dashboard';
+
+  if (!user || !password) {
+    throw new Error('E2E_USER và E2E_PASSWORD phải được thiết lập trong .env');
+  }
+
+  await page.goto(loginPath);
+  // Cập nhật các locator bên dưới bằng selector thật từ app (dùng automation-testing skill)
+  await page.getByRole('textbox', { name: 'Email' }).fill(user);
+  await page.getByLabel('Mật khẩu').fill(password);
+  await page.getByRole('button', { name: 'Đăng nhập' }).click();
+
+  const escaped = postLoginPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  await expect(page).toHaveURL(new RegExp(escaped));
+  await page.context().storageState({ path: authFile });
+});

package/custom/harness/playwright/tests/e2e/fixtures/test.ts

@@ -0,0 +1,6 @@
+import { test as base } from '@playwright/test';
+
+export const LOGGED_OUT = { cookies: [], origins: [] } as const;
+
+export const test = base;
+export { expect } from '@playwright/test';

package/custom/harness/playwright/tests/e2e/pages/BasePage.ts

@@ -0,0 +1,9 @@
+import { Page } from '@playwright/test';
+
+export class BasePage {
+  constructor(protected readonly page: Page) {}
+
+  async navigate(path: string): Promise<void> {
+    await this.page.goto(path);
+  }
+}

package/custom/harness/playwright/tests/e2e/support/auth.ts

@@ -0,0 +1,5 @@
+export const AUTH_FILE = 'tests/e2e/.auth/user.json';
+
+export function isAuthEnabled(): boolean {
+  return Boolean(process.env.E2E_USER);
+}

package/custom/mcp-presets/playwright.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--isolated", "--browser", "chromium", "--headless"]
+    }
+  }
+}

package/custom/rules/test-patterns.md

@@ -0,0 +1,70 @@
+# Test Patterns — Quy ước chung cho automation-testing
+
+Tài liệu này được skill `automation-testing` đọc ở Phase 1 và áp dụng khi sinh test.
+Mục tiêu: test ổn định, dễ đọc, ít vỡ khi UI đổi.
+
+## Nguyên tắc chọn locator (ưu tiên từ trên xuống)
+
+1. `getByRole(role, { name })` — bám theo accessibility, bền nhất.
+2. `getByLabel(text)` — cho input có `<label>`.
+3. `getByPlaceholder(text)` — khi không có label.
+4. `getByText(text)` — cho message, nội dung tĩnh.
+5. `getByTestId(id)` — khi dev đã gắn `data-testid`.
+6. CSS / XPath — **chỉ khi bất đắc dĩ**, kèm comment lý do.
+
+> Locator phải lấy từ DOM thật (Phase 3 qua Playwright MCP), không tự bịa tên.
+
+## Quy ước chung
+
+- Mỗi test độc lập: tự `navigate` tới trang cần test, không phụ thuộc test trước.
+- Page Object: 1 file / 1 màn hình; locator khai báo ở constructor; action là method.
+- Spec import `{ test, expect }` từ `tests/e2e/fixtures/test.ts`.
+- ID test (`TC01`, `TC02`...) khớp bảng test case đã chốt ở Phase 2.
+- Tên test, comment viết tiếng Việt.
+- Không hardcode tài khoản/dữ liệu thật; dùng dữ liệu test do tester cung cấp.
+
+---
+
+## Pattern 1 — Login
+
+Steps điển hình: vào trang login → nhập email/password → submit.
+- Thành công: `await expect(page).toHaveURL(/dashboard/)`.
+- Sai thông tin: `await expect(errorMessage).toBeVisible()`.
+- Validation rỗng: submit ngay → `await expect(page.getByText('... bắt buộc')).toBeVisible()`.
+
+## Pattern 2 — Form validation
+
+- Submit khi field rỗng → kiểm tra message bắt buộc của từng field.
+- Nhập sai định dạng (email, số điện thoại) → kiểm tra message định dạng.
+- Nhập hợp lệ → submit thành công (toast / redirect / record mới xuất hiện).
+
+## Pattern 3 — CRUD (Create / Read / Update / Delete)
+
+- **Create**: mở form → điền → submit → khẳng định record xuất hiện trong list.
+- **Read**: tìm/lọc → khẳng định kết quả đúng.
+- **Update**: mở record → sửa → lưu → khẳng định giá trị mới hiển thị.
+- **Delete**: xóa → xác nhận → khẳng định record biến mất.
+- Mẹo: tạo dữ liệu có hậu tố thời gian/ngẫu nhiên để tránh trùng giữa các lần chạy.
+
+## Pattern 4 — Modal / Dialog
+
+- Mở modal → `await expect(dialog).toBeVisible()`.
+- Thao tác trong modal dùng locator scope trong dialog: `dialog.getByRole(...)`.
+- Đóng/confirm → khẳng định modal đóng (`toBeHidden`) và side-effect đúng.
+
+## Pattern 5 — Table / Pagination / Search
+
+- Search: nhập từ khóa → khẳng định hàng khớp xuất hiện, hàng không khớp biến mất.
+- Pagination: sang trang → khẳng định nội dung trang đổi.
+- Dùng `getByRole('row')`, `getByRole('cell')` để bám bảng theo accessibility.
+
+## Pattern 6 — Auth-gated pages (storageState)
+
+Cơ chế có sẵn trong repo — **ưu tiên dùng**, đừng đăng nhập lại trong từng test:
+
+- Đăng nhập **1 lần** ở `tests/e2e/auth.setup.ts`, lưu phiên vào `.auth/user.json`.
+- Bật bằng env `E2E_USER` (+ `E2E_PASSWORD`, `E2E_LOGIN_PATH`, `E2E_POST_LOGIN_PATH`).
+- Khi bật, mọi test chạy ở trạng thái **đã đăng nhập** sẵn — không cần `beforeEach` login.
+- Test cần **chưa đăng nhập** (test login/logout): `test.use({ storageState: LOGGED_OUT })`
+  ở đầu spec (`LOGGED_OUT` import từ `../../fixtures/test`).
+- Selector trong `auth.setup.ts` phải là selector THẬT của trang login (lấy ở Phase 3).

package/custom/skills/automation-testing/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: automation-testing
+description: Sinh Playwright TypeScript E2E test từ test case draft của tester. Dùng Playwright MCP để xem DOM THẬT của app và lấy selector chính xác (không đoán). Dùng khi tester muốn tạo script test tự động từ mô tả test case bằng ngôn ngữ tự nhiên.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_generate_locator, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_fill_form, mcp__playwright__browser_select_option, mcp__playwright__browser_press_key, mcp__playwright__browser_wait_for, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages, mcp__playwright__browser_navigate_back, mcp__playwright__browser_close
+---
+
+# Skill: automation-testing
+
+Sinh **Playwright TypeScript** test scripts từ test case draft của tester.
+Điểm khác biệt cốt lõi so với "sinh code thuần": skill **mở app thật bằng Playwright MCP**,
+chụp cây accessibility/DOM và sinh selector từ element CÓ THẬT — nên script chạy được ngay,
+tester không cần biết TypeScript và hạn chế tối đa việc nhờ dev sửa selector.
+
+## Cách gọi
+
+```
+/automation-testing baseUrl: <url> [autoRun: true|false] [headed: true|false] [ticketId: <id>]
+---
+<test case draft của tester — text tự do, mỗi dòng một case>
+```
+
+Ví dụ:
+```
+/automation-testing baseUrl: http://localhost:3000 autoRun: false
+---
+1. Vào trang login, nhập đúng email/password → vào được dashboard
+2. Nhập sai password → hiện thông báo lỗi
+3. Để trống email → hiện validation lỗi
+```
+
+## Tham số (parse từ phần đầu lời gọi)
+
+Đọc các tham số từ text người dùng truyền vào (dạng `key: value`). Nếu không thấy, dùng default.
+
+| Param      | Default | Ý nghĩa |
+|------------|---------|---------|
+| `baseUrl`  | —       | URL web app đang test. **Bắt buộc.** Nếu thiếu → hỏi tester rồi mới tiếp tục. |
+| `autoRun`  | `false` | Tự chạy `npx playwright test` sau khi sinh script. |
+| `headed`   | `true`  | Hiện cửa sổ browser khi `autoRun=true`. |
+| `ticketId` | suy ra  | Thư mục con cho spec (`tests/e2e/specs/<ticketId>/`). Nếu thiếu → suy từ tên feature (vd `login`). |
+
+Phần text sau dấu `---` là **test case draft**.
+
+---
+
+## Phase 1 — Collect (Thu thập input)
+
+Đọc tất cả nguồn có sẵn, theo thứ tự ưu tiên:
+
+1. `plan/<ticketId>/requirement.md` (nếu có) — dùng `Read`.
+2. `plan/<ticketId>/plan.md` (nếu có).
+3. **Test case draft** — phần text sau `---` trong lời gọi.
+4. `custom/rules/test-patterns.md` — các pattern chuẩn (login, CRUD, form, modal...). **Luôn đọc file này** để áp dụng quy ước chung.
+
+Kiểm tra điều kiện tiên quyết:
+- Thiếu `baseUrl` → hỏi tester, dừng lại chờ.
+- Không có bất kỳ test case nào (cả draft lẫn requirement) → hỏi:
+  > "Bạn muốn test feature gì? Hãy mô tả các test case hoặc paste test case draft vào đây."
+
+---
+
+## Phase 2 — Analyze (Sinh danh sách test case có cấu trúc)
+
+Phân tích tất cả input và lập bảng test case:
+
+```
+## Test Cases — <Feature Name>
+
+| ID   | Tên test case            | Steps                                          | Expected Result            |
+|------|--------------------------|------------------------------------------------|----------------------------|
+| TC01 | Đăng nhập thành công      | 1. Vào /login 2. Nhập email+pass hợp lệ 3. Submit | Redirect về /dashboard  |
+| TC02 | Sai mật khẩu             | 1. Vào /login 2. Nhập sai pass 3. Submit       | Hiện error message         |
+| TC03 | Để trống email           | 1. Vào /login 2. Submit ngay                   | Hiện "Email là bắt buộc"   |
+```
+
+> ⚠️ **GATE 1 — BẮT BUỘC.** Hiển thị bảng và hỏi:
+> "Danh sách test cases trên đã đúng chưa? Cần thêm/sửa/xóa case nào không?
+> Xác nhận để tôi mở app và lấy selector thật."
+>
+> **Dừng lại, chờ tester xác nhận.** Không tự chuyển Phase 3.
+
+---
+
+## Phase 3 — Explore (Khám phá DOM thật qua Playwright MCP) 🔑
+
+Đây là bước quyết định độ chính xác. **Không được đoán selector** — phải lấy từ app thật.
+
+Với mỗi trang/màn hình liên quan trong các test case đã chốt:
+
+1. `mcp__playwright__browser_navigate` tới `<baseUrl><path>` (vd `http://localhost:3000/login`).
+2. `mcp__playwright__browser_snapshot` để lấy cây accessibility (role, name, ref của từng element).
+3. Với từng element cần thao tác (input, button, message...), dùng
+   `mcp__playwright__browser_generate_locator` để lấy **locator Playwright chuẩn** từ element thật.
+4. Nếu một test case cần đi qua nhiều bước (vd phải submit mới hiện error), dùng
+   `browser_type` / `browser_fill_form` / `browser_click` để **đi tới đúng trạng thái** rồi
+   `browser_snapshot` lại để lấy selector của element xuất hiện sau đó (error message, modal...).
+5. Ghi lại bảng ánh xạ: phần tử logic → locator thật. Ví dụ:
+
+   ```
+   Email field   → getByRole('textbox', { name: 'Email' })
+   Password field→ getByLabel('Mật khẩu')
+   Submit button → getByRole('button', { name: 'Đăng nhập' })
+   Error message → getByText('Sai tên đăng nhập hoặc mật khẩu')
+   ```
+
+Quy tắc ưu tiên locator (theo Playwright best practice):
+`getByRole` > `getByLabel` > `getByPlaceholder` > `getByText` > `getByTestId` > CSS.
+Chỉ dùng CSS/XPath khi không còn cách nào khác, và ghi chú lý do.
+
+> ⚠️ **Nếu không mở được app** (baseUrl sai, app chưa chạy, route không tồn tại):
+> báo rõ cho tester, **không** sinh selector đoán mò. Hỏi tester sửa baseUrl / khởi động app.
+>
+> Đóng browser bằng `mcp__playwright__browser_close` khi khám phá xong.
+
+### Nếu app yêu cầu đăng nhập (auth)
+
+Khi feature cần test nằm sau màn hình login:
+
+1. Khám phá selector trang login bằng MCP (như trên).
+2. Cập nhật `tests/e2e/auth.setup.ts`: thay 3 dòng locator mặc định (Email / Mật khẩu /
+   nút Đăng nhập) bằng **selector thật** vừa khám phá, và chỉnh `expectPathAfterLogin`.
+3. Hỏi tester **tài khoản test** (không hardcode tài khoản thật). Hướng dẫn họ điền vào `.env`:
+   `E2E_USER`, `E2E_PASSWORD`, `E2E_LOGIN_PATH`, `E2E_POST_LOGIN_PATH` (xem `.env.example`).
+   Có `E2E_USER` → auth tự bật: project `setup` đăng nhập 1 lần, lưu `.auth/user.json`,
+   các test sau tái dùng phiên (không login lại từng test).
+4. Test mà bản thân nó cần trạng thái **CHƯA đăng nhập** (vd chính test login/logout):
+   thêm ở đầu spec `test.use({ storageState: LOGGED_OUT })` (import `LOGGED_OUT` từ
+   `../../fixtures/test`).
+
+---
+
+## Phase 4 — Generate (Sinh script với selector thật)
+
+Sinh file theo cấu trúc:
+
+```
+tests/e2e/
+├── pages/
+│   ├── BasePage.ts            ← chỉ tạo nếu chưa có (đã có sẵn trong repo)
+│   └── <Feature>Page.ts       ← Page Object, locator lấy từ Phase 3
+├── specs/
+│   └── <ticketId>/
+│       └── <feature>.spec.ts  ← nhóm nhiều TCs (xem quy tắc bên dưới)
+└── fixtures/test.ts           ← chỉ tạo nếu chưa có (đã có sẵn)
+```
+
+Khi được gọi từ `coverage-check` (Phase 2d), output vào `test-plan/test-scripts/`:
+
+```
+test-plan/test-scripts/
+├── AD10_001.spec.ts   ← mỗi TC_ID một file riêng
+├── AD10_002.spec.ts
+└── ...
+```
+
+Quy tắc sinh code:
+
+- **`<Feature>Page.ts`**: kế thừa `BasePage`. Khai báo tất cả `Locator` ở constructor,
+  **dùng đúng locator lấy được ở Phase 3**. Mỗi hành động là một async method (vd `login()`).
+  Tham khảo `templates/PageObject.example.ts` để biết style.
+
+- **Đặt tên test function — bắt buộc chứa TC_ID:**
+  ```typescript
+  // ScreenID là mã màn hình/chức năng của từng dự án (AD10, LOGIN, ORD, ... — không cố định)
+  test.describe('[ScreenID] — Tên màn hình', () => {
+    test('[ScreenID_001] Mô tả scenario đầu tiên', async ({ page }) => {
+      // ...
+    })
+    test('[ScreenID_002] Mô tả scenario thứ hai', async ({ page }) => {
+      // ...
+    })
+  })
+  ```
+  Ví dụ thực tế (ScreenID tùy dự án): `[AD10_001]`, `[LOGIN_001]`, `[ORD_002]`
+
+  Format bắt buộc: `'[TC_ID] Mô tả scenario'` — TC_ID phải nằm ở **đầu tên test**, trong dấu `[]`.
+  Mục đích: khi chạy `--grep "AD10_001"` (hoặc TC_ID thực tế) sẽ select đúng test case, và kết quả map 1-1 với testcase document.
+
+- **`<feature>.spec.ts`**: import `{ test, expect }` từ `../../fixtures/test`.
+  dùng `test.describe('[ScreenID]', ...)` để nhóm. Assertion rõ ràng (`expect(...).toBeVisible()`...).
+- **Không tạo lại** `BasePage.ts` / `playwright.config.ts` / `fixtures/test.ts` /
+  `auth.setup.ts` / `support/auth.ts` nếu đã tồn tại (kiểm tra bằng `Glob` trước) —
+  với `auth.setup.ts` chỉ **sửa locator/đường dẫn**, không ghi đè toàn bộ.
+
+### Incremental Update — chỉ generate scripts mới hoặc đã thay đổi
+
+Khi được gọi với danh sách TC_IDs (từ `coverage-check` hoặc sau khi TESTER update testcases):
+
+1. **Kiểm tra scripts đã tồn tại:** `Glob` tìm các file trong `test-plan/test-scripts/*.spec.ts`
+2. **Phân loại từng TC_ID:**
+   - Nếu `[TC_ID].spec.ts` **chưa tồn tại** → `[NEW]` — sinh script mới
+   - Nếu `[TC_ID].spec.ts` **đã tồn tại** và TC nằm trong danh sách "đã thay đổi" (do TESTER chỉ định) → `[UPDATED]` — regenerate, overwrite
+   - Nếu `[TC_ID].spec.ts` **đã tồn tại** và không trong danh sách thay đổi → `[SKIP]` — không đụng vào
+3. **Chỉ mở DOM/Playwright MCP cho TCs cần generate** (`[NEW]` và `[UPDATED]`)
+4. **Báo cáo kết quả:**
+   ```
+   Script generation complete:
+     [NEW]     AD10_005.spec.ts — created
+     [UPDATED] AD10_002.spec.ts — regenerated (TC content changed)
+     [SKIP]    AD10_001.spec.ts — unchanged, kept existing
+     [SKIP]    AD10_003.spec.ts — unchanged, kept existing
+   ```
+
+Khi TESTER không chỉ định danh sách thay đổi (chạy lần đầu từ `coverage-check`), generate TẤT CẢ TCs có `Type = Auto` trong `final-testcases.md` mà chưa có script.
+
+---
+
+## Phase 5 — Execute
+
+Set `BASE_URL` = `baseUrl` khi chạy để Playwright dùng đúng app.
+
+### autoRun = false (default)
+In hướng dẫn chạy thủ công:
+```
+✅ Đã sinh script xong!
+
+Chạy test:
+  BASE_URL=<baseUrl> npx playwright test tests/e2e/specs/<ticketId>/
+  BASE_URL=<baseUrl> npx playwright test --headed     # hiện browser
+  npx playwright test --ui                              # mở Playwright UI
+Xem report:
+  npx playwright show-report
+```
+
+### autoRun = true
+1. Chạy bằng `Bash`:
+   `BASE_URL=<baseUrl> npx playwright test tests/e2e/specs/<ticketId>/ <--headed nếu headed=true>`
+2. Tóm tắt pass/fail cho tester (dễ đọc, không bắt đọc log thô).
+3. Nếu có test fail: chỉ ra TC nào fail, lý do, và đề xuất sửa.
+   In `npx playwright show-report` để mở HTML report.
+
+---
+
+## Nguyên tắc chung
+
+- **Gate trước khi sinh code** (Phase 2) là bắt buộc — tránh sinh sai hàng loạt.
+- **Selector phải đến từ DOM thật** (Phase 3) — đây là lý do tồn tại của skill này.
+- Viết test case, tên test, comment bằng **tiếng Việt** cho khớp draft của tester.
+- Nếu app yêu cầu đăng nhập trước, hỏi tester credentials test (đừng hardcode tài khoản thật).

package/custom/skills/automation-testing/templates/BasePage.ts

@@ -0,0 +1,29 @@
+import { Page, Locator } from '@playwright/test'
+
+export abstract class BasePage {
+  readonly page: Page
+
+  constructor(page: Page) {
+    this.page = page
+  }
+
+  async navigate(path: string) {
+    await this.page.goto(path)
+    await this.waitForLoad()
+  }
+
+  async waitForLoad() {
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async takeScreenshot(name: string) {
+    await this.page.screenshot({
+      path: `evidence/${name}.png`,
+      fullPage: true,
+    })
+  }
+
+  async getPageTitle(): Promise<string> {
+    return this.page.title()
+  }
+}

package/custom/skills/automation-testing/templates/PageObject.example.ts

@@ -0,0 +1,29 @@
+// TEMPLATE THAM CHIẾU — không phải file chạy thật.
+// Skill dùng style này để sinh tests/e2e/pages/<Feature>Page.ts.
+// CÁC LOCATOR DƯỚI ĐÂY LÀ VÍ DỤ — khi sinh thật phải thay bằng locator
+// lấy từ Phase 3 (Playwright MCP browser_snapshot / browser_generate_locator).
+
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './BasePage';
+
+export class LoginPage extends BasePage {
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    super(page);
+    // ↓ Locator THẬT lấy từ DOM ở Phase 3, ưu tiên getByRole > getByLabel > ...
+    this.emailInput = page.getByRole('textbox', { name: 'Email' });
+    this.passwordInput = page.getByLabel('Mật khẩu');
+    this.submitButton = page.getByRole('button', { name: 'Đăng nhập' });
+    this.errorMessage = page.getByText('Sai tên đăng nhập hoặc mật khẩu');
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}

package/custom/skills/automation-testing/templates/playwright.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e/specs',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['json', { outputFile: 'test-results/results.json' }],
+  ],
+
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'on-first-retry',
+    headless: !process.env.HEADED,
+    locale: 'vi-VN',
+  },
+
+  projects: [
+    // Auth setup (chỉ chạy khi có E2E_USER trong .env)
+    ...(process.env.E2E_USER
+      ? [{ name: 'setup', testMatch: /auth\.setup\.ts/ }]
+      : []),
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        ...(process.env.E2E_USER ? { storageState: '.auth/user.json' } : {}),
+      },
+      dependencies: process.env.E2E_USER ? ['setup'] : [],
+    },
+  ],
+
+  outputDir: 'test-results',
+})

package/custom/skills/automation-testing/templates/spec.example.ts

@@ -0,0 +1,29 @@
+// TEMPLATE THAM CHIẾU — không phải file chạy thật.
+// Skill dùng style này để sinh tests/e2e/specs/<ticketId>/<feature>.spec.ts.
+// ID test (TC01...) phải khớp bảng test case đã chốt ở Phase 2.
+
+import { test, expect } from '../../fixtures/test';
+import { LoginPage } from '../../pages/LoginPage';
+
+test.describe('Đăng nhập hệ thống', () => {
+  test('TC01 - Đăng nhập thành công với credentials hợp lệ', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.navigate('/login');
+    await loginPage.login('admin@example.com', 'Password123');
+    await expect(page).toHaveURL(/\/dashboard/);
+  });
+
+  test('TC02 - Hiển thị lỗi khi nhập sai mật khẩu', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.navigate('/login');
+    await loginPage.login('admin@example.com', 'wrong-password');
+    await expect(loginPage.errorMessage).toBeVisible();
+  });
+
+  test('TC03 - Hiển thị validation khi để trống email', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.navigate('/login');
+    await loginPage.submitButton.click();
+    await expect(page.getByText('Email là bắt buộc')).toBeVisible();
+  });
+});