@relipa/ai-flow-kit 0.1.2 → 0.1.4-beta.0

package/custom/skills/execute-flow/SKILL.md

@@ -0,0 +1,499 @@
+---
+name: execute-flow
+description: Executing Flow — 4 gates độc lập để thực thi Playwright từ testcase có sẵn. Gate 1 load TC file và sinh work plan. Gate 2 sync scripts (hash-based). Gate 3 chạy playwright và thu thập evidence. Gate 4 sinh report và hỏi log bug lên Jira. Không cần đi qua workflow.md Gate 1-2.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_generate_locator, mcp__playwright__browser_close
+---
+
+# Executing Flow
+
+Flow độc lập để tester thực thi test từ TC file có sẵn, không cần chạy lại phân tích (workflow.md Gate 1-2).
+
+## Entry Points
+
+| Nguồn | Trigger | Cách AI xử lý |
+|-------|---------|---------------|
+| Ticket | `ak execute PROJ-33` | Tìm TC file trong `.aiflow/context/current.json` |
+| File | `ak execute ./testcases/AD10.md` | Đọc trực tiếp file path |
+| Manual | `ak execute` (không argument) | Hỏi tester: "TC file của bạn ở đâu?" |
+
+---
+
+## ⛩️ GATE 1 — Context & Work Plan
+
+### Pre-flight checks (auto, không hỏi tester)
+
+Kiểm tra trước khi làm gì:
+
+0. **MCP Playwright** có được cấu hình không?
+   - Kiểm tra **`~/.claude/settings.json`** (global user-level, áp dụng cho mọi project): có key `playwright` trong `mcpServers` không?
+   - Nếu thiếu → dừng, hỏi tester:
+     > "⚠️ MCP Playwright chưa được cấu hình. Đây là yêu cầu bắt buộc để chạy browser automation.
+     > Sẽ cài vào **global settings** (`~/.claude/settings.json`) — chỉ cần làm một lần, dùng được cho mọi repo.
+     > → Tự động cài đặt? [Y/n]"
+   - Nếu tester chọn **Y** (hoặc Enter):
+     - Đọc `~/.claude/settings.json`
+     - Thêm key `playwright` vào `mcpServers` (giữ nguyên các key khác):
+       ```json
+       "playwright": {
+         "command": "npx",
+         "args": ["-y", "@playwright/mcp@latest", "--isolated", "--browser", "chromium", "--headless"]
+       }
+       ```
+     - Ghi lại file `~/.claude/settings.json`
+     - Thông báo:
+       > "✅ Đã cài MCP Playwright vào global settings. **Vui lòng restart Claude Code** để load MCP server, sau đó chạy lại lệnh `ak execute`."
+     - Dừng. Không proceed cho đến khi tester restart và chạy lại.
+   - Nếu tester chọn **n** → dừng, hướng dẫn:
+     > "Để cài thủ công: mở `~/.claude/settings.json`, thêm `playwright` vào `mcpServers`, rồi restart Claude Code."
+
+1. TC file có parse được không? (file tồn tại, có Section 3 — Danh sách Test Cases)
+2. `ak-test/` folder có tồn tại không? Nếu không → hướng dẫn tester tạo: `mkdir ak-test`
+3. `BASE_URL` env var có set không? Nếu không → hỏi: "BASE_URL chưa set. App đang chạy ở URL nào?"
+
+Items 1–3 chạy ngay khi entry. Item 4 chạy sau khi repo được xác định từ Bước 1 (parse TC file):
+
+4. `playwright.config.ts` có tồn tại trong `ak-test/{repo}/` không? Nếu không → dừng, hướng dẫn tester: "Chưa có playwright.config.ts cho repo {repo}. Tạo file từ template tại `ak-test/{repo}/playwright.config.ts` (xem skill execute-flow templates)."
+
+Nếu bất kỳ check nào fail → dừng, hướng dẫn fix. Không proceed.
+
+### Bước 1: Parse TC file
+
+Đọc TC file, extract từ Section 1 — Thông tin chung:
+- `Screen_ID`: từ "Mã màn hình - Tên màn hình" (vd `AD10_Create Product` → ScreenID = `AD10`)
+- `Screen_Name`: phần sau `_` (vd `Create Product`)
+- `Repo`: từ dòng "Repo" (vd `repo-fe`)
+
+Nếu thiếu `Repo` field → hỏi tester:
+> "TC file của màn hình `{ScreenID}` chưa có thông tin Repo. Repo này nằm trong repository nào?
+> (vd: repo-fe, repo-be)"
+
+Chờ tester trả lời rồi mới tiếp tục.
+
+Nếu nhiều màn hình khác repo → hỏi từng màn hình một.
+
+### Bước 1b: Đọc Source Code (nếu workspace có source repos)
+
+Chạy ngay sau khi xác định được `Repo`, trước khi extract TCs.
+
+Nếu workspace mở dạng parent folder chứa cả `ak docs` lẫn source code repos:
+
+1. **Nếu GitNexus MCP có sẵn** (`.mcp.json` có entry `gitnexus`):
+   - `gitnexus: query("tên màn hình {ScreenID}")` → tìm component, page, form liên quan
+   - `gitnexus: context("ComponentName")` → xem toàn bộ component/template
+2. **Nếu không có GitNexus**: đọc trực tiếp trong `{repo}/`:
+   - Component / Page / View của màn hình — tìm `data-testid`, `id`, `name` của các element
+   - Form / Input structure — hiểu hierarchy của DOM
+   - Route / path mapping — xác nhận URL path của màn hình
+3. Lưu lại thông tin để Gate 2 (Script Sync) sử dụng:
+   - Danh sách `data-testid` / `id` của các element tương tác
+   - Cấu trúc form (fieldset, section, tab nếu có)
+   - URL path chính xác của màn hình
+
+> Mục đích: Giúp `script-sync` (Gate 2) viết Playwright scripts với selectors chính xác hơn, giảm phụ thuộc vào browser snapshot khi app chưa chạy.
+
+### Bước 2: Extract TCs từ Section 3
+
+Đọc tất cả rows trong các bảng Section 3.x, extract:
+- TC_ID, Test Case Name, Severity
+
+Phân loại sơ bộ:
+- **Manual TC**: Steps đề cập "kiểm tra DB", "kiểm tra file", "Quan sát giao diện tổng quan", "Kiểm tra layout/màu sắc"
+- **Automation TC**: còn lại
+
+### Bước 3: Scan scripts hiện tại
+
+Tìm `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts`:
+- Nếu tồn tại: đọc `@tc-id` comments → xác định TCs đã có script
+- Tính hash cho từng TC → so với `@tc-hash` trong file → xác định `updated` vs `skipped`
+- Nếu không tồn tại: tất cả automation TCs đều là `new`
+
+### Bước 4: Hiển thị Work Plan
+
+```
+📋 WORK PLAN — {ticket hoặc tên TC file}
+
+Requirement Overview:
+- Màn hình: {ScreenID}_{Screen Name} ({repo})
+- Tổng TC: {N} | Automation: {N} | Manual/Untest: {N}
+
+Script Sync Plan:
+| Screen | TC_ID    | Script hiện tại           | Trạng thái    |
+|--------|----------|---------------------------|---------------|
+| AD10   | AD10_001 | -                         | 🆕 Gen mới    |
+| AD10   | AD10_002 | AD10.spec.ts (hash match) | ⏭️ Skip       |
+| AD10   | AD10_005 | AD10.spec.ts (hash diff)  | 🔄 Update     |
+| AD10   | AD10_023 | -                         | ⚠️ Manual TC  |
+
+→ Cần gen mới: {N} | Update: {N} | Skip: {N} | Manual (Untest): {N}
+```
+
+```
+⏸️ GATE 1: WORK PLAN READY
+
+Screens: {N} | Total TC: {N} ({N} automation / {N} manual)
+Scripts: {N} gen mới | {N} update | {N} skip
+Repo mapping: {ScreenID} → {repo}
+
+→ Type APPROVED to proceed to Gate 2 (Script Sync)
+→ Type REPO: {ScreenID}={repo} để cập nhật repo mapping
+```
+
+Dừng. Chờ APPROVED.
+
+---
+
+## ⛩️ GATE 2 — Script Sync
+
+Chỉ chạy sau Gate 1 APPROVED.
+
+### Invoke script-sync skill
+
+Gọi `script-sync` skill với context:
+- `tcFile`: path TC file
+- `repo`: từ Gate 1
+- `screenId`: always lowercase ScreenID (vd `ad10`, not `AD10`) — directory path uses lowercase
+- `screenUrl`: hỏi tester nếu chưa biết: "URL path của màn hình {ScreenID} là gì? (vd `/admin/products/create`)"
+- `baseUrl`: từ `BASE_URL` env var
+
+Nhận về: danh sách kết quả per TC.
+
+### Hiển thị kết quả
+
+```
+⏸️ GATE 2: SCRIPT SYNC COMPLETE
+
+Gen mới: {N} | Updated: {N} | Skipped: {N}
+Manual (Untest): {N} TCs
+Blocked: {N} TCs — xem lý do bên trên
+
+→ Review: [ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts](ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts)
+→ Type APPROVED to run tests
+→ Type SKIP: {TC_ID} để đánh dấu Pending và tiếp tục
+→ Or provide feedback to fix scripts
+```
+
+Dừng. Chờ APPROVED.
+
+Khi tester gõ `SKIP: AD10_019`: đánh dấu TC đó là Pending, loại khỏi danh sách sẽ chạy.
+
+---
+
+## ⛩️ GATE 3 — Execute & Evidence
+
+Chỉ chạy sau Gate 2 APPROVED.
+
+### Bước 1: Xác định run number
+
+Scan `ak-test/{repo}/results/{screenId}/` để tìm run folder hiện có:
+- Nếu không có folder nào → `run-1`
+- Nếu có `run-1`, `run-2` → `run-3`
+
+Tạo folder: `ak-test/{repo}/results/{screenId}/run-{N}/`
+
+### Bước 2: Chạy Playwright
+
+```bash
+cd ak-test/{repo}
+BASE_URL={baseUrl} npx playwright test scripts/{screenId}/{ScreenID}.spec.ts
+```
+
+Note: Reporters are already configured in `playwright.config.ts` (json → `test-results/results.json`, html, list). The CLI `--reporter` flag would override these settings, so it is omitted here.
+
+### Bước 3: Parse kết quả
+
+Đọc `ak-test/{repo}/test-results/results.json` (Playwright JSON output).
+
+Với mỗi test:
+- Extract TC_ID từ test title (format: `AD10_001 - {name}` hoặc `[AD10_001] {name}`)
+- Map: TC_ID → `{status: 'passed'|'failed', duration, attachments, errors}`
+
+### Bước 4: Tổ chức Evidence
+
+Với mỗi TC:
+
+**Tạo folder:** `ak-test/{repo}/results/{screenId}/run-{N}/{TC_ID}-{kebab-scenario}/`
+
+Với `kebab-scenario` = Test Case Name lowercase, dấu cách thành `-`, bỏ ký tự đặc biệt.
+
+**Copy files từ Playwright output:**
+- Screenshots → `step-NN-{desc}.png`
+- Trace file → `trace.zip`
+
+**Tạo `result.md`:**
+
+Khi PASS:
+```markdown
+# Result: {TC_ID} — {Test Case Name}
+
+**Status:** ✅ PASS
+**Duration:** {X}s
+**Run:** run-{N} | {YYYY-MM-DD HH:MM}
+
+## Evidence
+| Step | Screenshot |
+|------|-----------|
+| {step 1} | step-01-{desc}.png |
+| {step 2} | step-02-{desc}.png |
+```
+
+Khi FAIL:
+```markdown
+# Result: {TC_ID} — {Test Case Name}
+
+**Status:** ❌ FAIL
+**Duration:** {X}s
+**Run:** run-{N} | {YYYY-MM-DD HH:MM}
+
+## Failure Details
+**Error:** {error message từ Playwright}
+
+## Evidence
+| File | Mô tả |
+|------|-------|
+| failure-screenshot.png | Trạng thái lúc fail |
+| trace.zip | Playwright trace |
+
+## Bug Reference
+→ Xem: bugs/BUG-{NNN}-{slug}.md
+```
+
+Với Manual TCs (Untest): không tạo evidence folder.
+
+### Bước 5: Auto-draft Bug Reports
+
+Với mỗi TC failed, tạo `ak-test/{repo}/results/{screenId}/run-{N}/bugs/BUG-{NNN}-{slug}.md`:
+
+```markdown
+# BUG-{NNN} — {Test Case Name}
+
+**TC_ID:** {TC_ID}
+**Severity:** {severity từ TC file}
+**Status:** 🔴 Open
+**Found at:** Gate 3 Execution | {YYYY-MM-DD}
+**Environment:** {baseUrl} | Chrome | Windows
+
+---
+
+## Steps to Reproduce
+
+{Steps từ TC file, numbered}
+
+## Expected Result
+
+{Expected Result từ TC file}
+
+## Actual Result
+
+{Actual behavior từ Playwright error}
+
+## Evidence
+
+- Screenshot: `{TC_ID}-{scenario}/failure-screenshot.png`
+- Playwright trace: `{TC_ID}-{scenario}/trace.zip`
+
+## Technical Notes
+
+```
+{Playwright error message}
+```
+
+---
+
+## Resolution
+
+- [ ] Dev fix
+- [ ] Retest: `RETEST: {TC_ID}`
+```
+
+BUG số: đếm file trong `bugs/` folder, +1. Format: `001`, `002`,...
+
+### Bước 6: Cập nhật TC file gốc
+
+Ghi kết quả vào các cột R1/R2 trong TC file:
+
+- R1 = lần chạy đầu tiên (run-1). Nếu R1 đã có giá trị → ghi vào R2.
+- R1 Tester = `AI-R1`, R2 Tester = `AI-R2`
+
+```markdown
+| AD10_001 | ... | ✅ Pass | {YYYY-MM-DD} | AI-R1 |   |   |   |
+| AD10_005 | ... | ❌ Fail | {YYYY-MM-DD} | AI-R1 |   |   |   |
+| AD10_023 | ... | ⏭️ Untest | - | - |   |   |   |
+```
+
+Cập nhật Section 2 — Test Execution Summary table:
+
+```markdown
+| Round {N} | {passed} | {failed} | {untest} | {pending} | {total} | {passed/total*100}% |
+```
+
+### Bước 7: Hiển thị Gate 3
+
+```
+⏸️ GATE 3: EXECUTION COMPLETE
+
+Results (run-{N}):
+- Passed:  {N} / {total automation}
+- Failed:  {N} / {total automation}
+- Untest:  {N} (manual TCs)
+- Pending: {N} (blocked/skipped)
+
+Bugs drafted: {N} ({N} Critical, {N} High, {N} Medium, {N} Low)
+Unresolved critical: {N}
+
+→ Evidence: ak-test/{repo}/results/{screenId}/run-{N}/
+→ Type APPROVED when all critical/high bugs resolved
+→ Type RETEST: {TC_ID} to re-execute
+→ Type PENDING: {TC_ID} để đánh dấu TC không chạy được
+```
+
+Dừng. Chờ APPROVED.
+
+### RETEST loop
+
+Khi tester gõ `RETEST: AD10_005, AD10_008`:
+
+1. **Re-run Dev Artifacts Check**: invoke `pr-impact-analysis` skill nếu PR đã khai báo.
+   - Nếu phát hiện commit mới → đề xuất TC bổ sung, tester approve delta trước
+2. **Chạy selective test:**
+   ```bash
+   cd ak-test/{repo}
+   BASE_URL={baseUrl} npx playwright test --grep "AD10_005|AD10_008"
+   ```
+3. Xác định run number mới (run-{N+1})
+4. Tổ chức evidence vào `run-{N+1}/` (không xóa run cũ)
+5. Cập nhật R2 columns trong TC file
+6. Cập nhật bug status:
+   - TC pass sau retest → ghi `RESOLVED` vào bug file: `**Status:** ✅ Resolved`
+   - TC vẫn fail → ghi `**Retest {N}:** Still OPEN` vào bug file
+
+Khi tester gõ `PENDING: AD10_025`: cập nhật TC row với `⏳ Pending`.
+
+---
+
+## ⛩️ GATE 4 — Report & Bug Logging
+
+Chỉ chạy sau Gate 3 APPROVED.
+
+### Bước 1: Tổng hợp kết quả
+
+Đọc tất cả `result.md` trong `run-{N}/`:
+- Count passed/failed/untest/pending per run
+- Identify last run number (run-{max})
+
+Đọc `bugs/BUG-*.md` trong run folder: phân loại severity + status (Open/Resolved).
+
+### Bước 2: Cập nhật Section 2 trong TC file
+
+Cập nhật bảng Test Execution Summary với số liệu từ R1 và R2.
+
+### Bước 3: Sinh testreport.md
+
+Tạo `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md` theo template chuẩn:
+
+```markdown
+# SUMMARY TEST REPORT
+
+## Project Information
+| Property | Value | Property | Value |
+|:---|:---|:---|:---|
+| Project Name | {tên dự án từ TC file hoặc hỏi tester} | Author | AI |
+| Project Code | {ScreenID} | Reviewer | {tên tester} |
+| Created At | {ngày chạy R1} | Report Date | {hôm nay} |
+| Last updated at | {hôm nay} | | |
+
+## Test Execution Summary
+| No | Module code | Written By | Created Date | R1 Passed | R1 Failed | R1 UnTest | R1 Pending | R2 Passed | R2 Failed | R2 UnTest | R2 Pending | Blocked | Total test cases | Tổng passed | % hoàn thành | Created Date | Updated Date | Sprint | Creator | Reviewer / Approver |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | {ScreenID} | AI | {date} | {r1p} | {r1f} | {r1u} | {r1pe} | {r2p} | {r2f} | {r2u} | {r2pe} | {blocked} | {total} | {tổng passed} | {%} | {date} | {date} | {sprint nếu có} | AI | {tester} |
+
+## Bug Summary
+| Bug ID | Severity | Title | Status | Jira Ticket |
+|--------|----------|-------|--------|-------------|
+{rows từ bugs/}
+
+## Sign-off
+- **Recommendation:** {Go nếu 0 Critical+High Open / No-go nếu còn / Conditional go nếu chỉ Medium còn open}
+- **Conditions:** {liệt kê nếu Conditional}
+```
+
+**Exit criteria:**
+- 0 Critical bugs Open → Go (kể cả còn Medium/Low)
+- 0 High bugs Open → Go (nếu không có Critical)
+- Còn Critical hoặc High Open → No-go
+- Chỉ còn Medium/Low Open → Conditional go
+
+### Bước 4: Bug logging flow
+
+Hỏi từng bug theo thứ tự severity (Critical → High → Medium → Low):
+
+```
+🐛 BUG-{NNN} [{Severity}] — {Title}
+   TC: {TC_ID} | Evidence: run-{N}/bugs/BUG-{NNN}...
+   Steps: {steps tóm tắt}
+   Expected: {expected}
+   Actual: {actual}
+
+→ Log lên Jira? [Y/n]  (hoặc gõ SKIP-BUG để bỏ qua)
+```
+
+Nếu tester gõ `Y`:
+- Gọi `ak bug-log` (nếu adapter có) hoặc hướng dẫn tester copy nội dung
+- Ghi ticket ID vào bug file: `**Jira Ticket:** {ticket-id}`
+- Ghi ticket ID vào cột Ticket ID của TC trong TC file
+
+Nếu `n` hoặc `SKIP-BUG`: ghi `Not logged` trong testreport.md Bug Summary.
+
+### Bước 5: Hiển thị Gate 4
+
+```
+⏸️ GATE 4: REPORT READY
+
+Overall: {Pass / Fail / Conditional}
+Passed: {N}/{total} | % hoàn thành: {N}%
+Bugs logged to Jira: {N}/{total bugs}
+Recommendation: {Go / No-go / Conditional go}
+
+→ Review: [ak-test/{repo}/results/{screenId}/run-{N}/testreport.md](ak-test/{repo}/results/{screenId}/run-{N}/testreport.md)
+→ Type APPROVED to sign off
+→ Type NO-GO: {reason} to reject release
+```
+
+Dừng. Chờ APPROVED hoặc NO-GO.
+
+---
+
+## Commands Reference
+
+```
+# Entry points
+ak execute PROJ-33                    # từ ticket
+ak execute ./testcases/AD10.md        # từ file
+ak execute                            # manual
+
+# Gate 1
+REPO: AD10=repo-fe, API01=repo-be     # cập nhật repo mapping
+
+# Gate 2
+SKIP: {TC_ID}                         # đánh dấu Pending, bỏ qua script
+
+# Gate 3
+RETEST: {TC_ID}                       # re-execute 1 TC
+RETEST: {TC_ID1}, {TC_ID2}            # re-execute nhiều TCs
+PENDING: {TC_ID}                      # đánh dấu không chạy được
+
+# Gate approval
+APPROVED                              # chuyển gate tiếp theo
+NO-GO: {reason}                       # reject (chỉ Gate 4)
+SKIP-BUG: BUG-{NNN}                   # bỏ qua không log bug này
+```
+
+---
+
+## Mandatory Rules
+
+- ✅ Dừng ở mỗi gate, chờ APPROVED trước khi proceed
+- ✅ `run-{N}` không bao giờ bị xóa hay overwrite — luôn tạo folder mới
+- ✅ R1/R2 trong TC file gốc được cập nhật sau mỗi lần chạy
+- ✅ Hỏi từng bug một — không auto-log toàn bộ
+- ❌ Không lấy expected result từ PR/code — chỉ từ TC file
+- ❌ Không skip gate kể cả khi "chỉ có 1 TC"

package/custom/skills/execute-flow/templates/playwright.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from '@playwright/test'
+import path from 'path'
+
+const LOGGED_OUT = { storageState: undefined }
+
+export default defineConfig({
+  testDir: './scripts',
+  outputDir: './test-results',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  reporter: [
+    ['json', { outputFile: 'test-results/results.json' }],
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['list'],
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'on',
+    video: 'on-first-retry',
+    headless: !process.env.HEADED,
+  },
+  projects: [
+    // Uncomment nếu cần auth setup:
+    // { name: 'setup', testMatch: /auth\.setup\.ts/ },
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        // storageState: '.auth/user.json', // uncomment nếu cần auth
+      },
+      // dependencies: ['setup'], // uncomment nếu cần auth
+    },
+  ],
+})
+
+export { LOGGED_OUT }