Skill cho Codex và Claude giúp tester tái hiện bug, verify fix và biến yêu cầu kiểm thử thành test tự động chạy được và bảo trì được, bằng Playwright + TypeScript — kể cả log dài, luồng nhiều màn hình/role và bug chỉ xuất hiện khi thao tác nhanh.
Đây là một Agent Skill theo chuẩn mở, dùng được trong Codex và Claude Code. Skill đóng gói hướng dẫn, reference và script để agent tự nạp khi bạn nhờ tái hiện bug hoặc làm automation test. Bạn nói bằng tiếng Việt như nói với đồng nghiệp; agent lo phần trinh sát, selector, cấu hình và code.
Phát triển dựa trên ý tưởng của anthropics/skills/webapp-testing, viết lại cho stack TypeScript và cho quy trình làm việc thực tế của tester Việt Nam.
Tester chuyển sang automation thường vấp ba chỗ:
| Vấn đề | Skill xử lý thế nào |
|---|---|
| Đoán selector → test lúc chạy lúc không | Bắt buộc trinh sát app thật trước khi viết code (scripts/explore.mjs đọc DOM và sinh locator có thật, cảnh báo locator dính nhiều phần tử) |
| Script dùng một lần rồi bỏ | Kết tinh thành dự án có cấu trúc: Page Object, fixture, config đa môi trường, CI — commit vào repo được |
| File test case Excel nằm một nơi, code nằm một nơi | scripts/excel_to_spec.py đọc file UAT có sẵn, sinh khung spec + bảng truy vết test-map.json |
| Bug tester mô tả nhanh, DEV cần verify lại sau fix | Chuẩn hóa full row + evidence → tái hiện baseline → verify đúng build fix → targeted regression |
| Log dài, đi qua nhiều màn hình rồi Agent bỏ sót state/bước | Compile từng raw clause thành scenario map có actor, context/page, from/to state, timing, branch và observation point; báo coverage x/y |
| Phải bấm nhanh/liên tục mới ra bug | Tách setup → critical burst → oracle, chạy cadence/attempt matrix, đo timing thực tế và không chèn wait làm trigger biến mất |
Nguyên tắc xuyên suốt: Recon → Codify. Trinh sát app thật trước, rồi mới kết tinh thành suite.
Phiên bản 1.2.0 thêm một protocol riêng cho bug phức tạp, nằm ở references/complex-flow-race-reproduction.md:
- Log văn bản dài → scenario map: giữ raw anchor của từng clause, actor/session/tab, state trước–sau, bước lặp/nhánh và từ khóa timing như “ngay”, “liên tục”, “lần thứ hai”. Agent phải báo
raw_clause_coverage: x/y, không được tóm tắt mất bước. - Luồng stateful xuyên màn hình: giữ toàn bộ causal chain trong một test/attempt, nhưng chia code sạch bằng
test.step, Page Object và flow helper. Tab/popup cùng session dùng chungBrowserContext; hai role độc lập dùng hai context. - Critical burst: setup được chờ readiness bình thường; đoạn trigger chỉ chứa action nguồn theo đúng thứ tự/cadence; oracle chạy sau burst. Agent không được thêm toast wait/screenshot/assertion ở giữa rồi vô tình “stabilize away” bug.
- Cadence và tần suất: timing không rõ được ghi
Unknownrồi khám phá bằng speed ladder. Mỗi profile báo requested/observed timing vàreproduced x/y; baseline intermittent không mặc định chỉ chạy hai lượt. - Evidence có thể ảnh hưởng race: tách profile low-overhead và evidence-rich khi trace/video làm thay đổi tỷ lệ. Không gộp denominator và không kết luận
Not reproducedchỉ vì bật trace thì bug ít xuất hiện hơn. - Fix verification có căn cứ: giữ cùng build fingerprint, state, cadence và instrumentation profile giữa baseline/target; chỉ
Verified fixedkhi symptom cũ không còn, KQMM + persistence đạt và targeted regression không lỗi.
Các pattern kỹ thuật bám theo tài liệu chính thức của Playwright về auto-waiting/actionability, events, pages/contexts, input, trace viewer và retries.
- Tester thủ công đang chuyển sang automation — biết rõ cần test gì, chưa rành selector, async, CI.
- QA lead cần dựng khung automation chuẩn cho team trong vài phút thay vì vài ngày.
- Dev muốn có bộ E2E mà không phải tự nghiên cứu từ đầu.
| Mảng | Nội dung |
|---|---|
| Web UI E2E | Locator theo vai trò, Page Object, form, bảng dữ liệu, upload/download, iframe, tab mới, dialog |
| API testing | request fixture, kiểm tra status/schema, chain token, tạo dữ liệu qua API cho test UI |
| Visual regression | toHaveScreenshot, che vùng động, quản lý ảnh baseline theo OS |
| Responsive & cross-browser | Đa viewport, giả lập thiết bị, Chromium/Firefox/WebKit |
| Accessibility | @axe-core/playwright, WCAG 2.1 AA, kiểm tra bàn phím |
| Mock & giả lập lỗi | page.route, HAR, lỗi 500, timeout, offline, mạng 3G |
| Dữ liệu & xác thực | storageState đăng nhập một lần, đa role, sinh dữ liệu duy nhất, dọn dữ liệu |
| Từ Excel sang script | Đọc mẫu KỊCH BẢN NGHIỆM THU / UAT, sinh spec + truy vết |
| Report & CI/CD | HTML report, Allure, JUnit cho TestRail/Xray, GitHub Actions, Jenkins, GitLab, sharding |
| Hiệu năng | Core Web Vitals, Lighthouse, ranh giới khi nào phải dùng k6 |
| Chẩn đoán | Test flaky, timeout, lỗi chỉ xảy ra trên CI, locator gãy |
| Bug reproduction & fix verification | Đọc bug log nhiều tab/evidence, tái hiện baseline, phân loại nguyên nhân, verify fix và đề xuất Close/Reopen |
| Complex flow & race reproduction | Scenario map, multi-screen/tab/role, critical burst, cadence matrix, attempt rate và observer effect |
Trên Codex — cài cho tài khoản hiện tại:
npx @duong.dev/playwright-automation install --codexCài theo repo để team dùng chung; Codex tự quét .agents/skills/ từ thư mục làm việc lên repo root:
npx @duong.dev/playwright-automation install --codex --projectSau đó gõ /skills hoặc nhắc trực tiếp $playwright-automation.
Trên Claude Code — giữ nguyên lệnh cũ:
npx @duong.dev/playwright-automation installCài cho riêng dự án hiện tại để cả team dùng chung (commit .claude/skills/ vào repo):
npx @duong.dev/playwright-automation install --projectGỡ hoặc xem đang cài ở đâu:
npx @duong.dev/playwright-automation where --codex
npx @duong.dev/playwright-automation uninstall --codex
npx @duong.dev/playwright-automation uninstall
npx @duong.dev/playwright-automation whereTrên claude.ai — tải file .skill ở Releases (hoặc tự đóng gói, xem docs/INSTALL.md), rồi vào Settings → Capabilities → Skills → Upload skill.
Chi tiết đầy đủ (clone bằng git, cài theo dự án, cập nhật, gỡ, kiểm tra đã nhận skill chưa): docs/INSTALL.md
Không có cú pháp gì phải nhớ. Cứ nói việc cần làm:
Test giúp tôi chức năng đăng nhập ở https://staging.congty.vn, tài khoản test là
tester@congty.vn / Abc@12345. Xem có bug gì không.
Dựng khung automation cho dự án, staging ở https://staging.congty.vn,
API ở https://api-staging.congty.vn. Cần cả test API và visual.
Đây là file KỊCH BẢN NGHIỆM THU.xlsx của tôi. Chuyển sheet "Đăng nhập"
thành script Playwright.
Test này lúc pass lúc fail trên Jenkins mà chạy máy tôi thì luôn xanh. Sao vậy?
Bug log này dài và đi qua nhiều màn hình. Hãy map đủ từng clause, giữ nguyên state
giữa các màn hình, rồi tự tái hiện. Lỗi chỉ ra khi bấm Lưu → Quay lại thật nhanh;
hãy đo cadence, chạy nhiều attempts và đừng chờ toast ở giữa hai action.
Nhiều kịch bản hơn kèm output mẫu: docs/USAGE.md
playwright-automation/
├── SKILL.md # Điểm vào — quy trình, định tuyến, nguyên tắc chống flaky
├── agents/openai.yaml # Metadata UI và prompt mặc định cho Codex/ChatGPT
├── references/ # Tài liệu chuyên sâu, agent chỉ đọc file cần dùng
│ ├── bug-reproduction.md # Tái hiện bug, verify fix, evidence và verdict
│ ├── complex-flow-race-reproduction.md # Log dài, multi-flow, cadence/race
│ ├── project-setup.md # Cài đặt, playwright.config.ts, đa môi trường
│ ├── ui-e2e.md # Locator, Page Object, form, bảng, iframe
│ ├── api-testing.md # request fixture, schema, checklist test API
│ ├── visual-responsive.md # Screenshot, viewport, cross-browser
│ ├── accessibility.md # axe-core, WCAG
│ ├── network-mocking.md # page.route, HAR, giả lập lỗi
│ ├── auth-and-data.md # storageState, đa role, dữ liệu test
│ ├── excel-to-spec.md # Chuyển test case Excel sang code
│ ├── reporting-ci.md # Reporter, Allure, GitHub Actions, Jenkins
│ ├── performance.md # Web Vitals, Lighthouse, k6
│ └── troubleshooting.md # Chẩn đoán flaky, timeout, lỗi CI
├── scripts/ # Gọi trực tiếp, đọc --help trước
│ ├── explore.mjs # Trinh sát trang, sinh locator có thật
│ ├── scaffold.mjs # Dựng khung dự án Playwright TS
│ └── excel_to_spec.py # Excel test case → spec + test-map.json
└── assets/template/ # Bộ khung dự án mà scaffold.mjs sinh ra
Skill dùng cơ chế progressive disclosure: SKILL.md luôn được nạp (ngắn gọn), còn references/ chỉ nạp khi cần. Nhờ vậy skill phủ rộng mà không làm nặng context.
Ba script chạy được ngoài Codex/Claude, hữu ích cho tester muốn tự thao tác:
# Trinh sát trang, lấy locator có thật thay vì đoán
node scripts/explore.mjs --url https://staging.congty.vn/login --out ./recon
# Dựng khung dự án đầy đủ
node scripts/scaffold.mjs --dir ./e2e --base-url https://staging.congty.vn --features ui,api,visual
# Đọc file test case Excel, sinh khung spec
python scripts/excel_to_spec.py --file "KỊCH BẢN NGHIỆM THU.xlsx" --dry-runMỗi script đều có --help mô tả đầy đủ tham số.
| Thành phần | Yêu cầu | Dùng cho |
|---|---|---|
| Node.js | ≥ 18 | explore.mjs, scaffold.mjs, chạy Playwright |
| Playwright | npm i -D @playwright/test |
Chạy test và trinh sát |
| Python | ≥ 3.9 + openpyxl |
excel_to_spec.py (chỉ khi cần đọc Excel) |
Không cài trước cũng được — Codex hoặc Claude sẽ hướng dẫn cài đúng lúc cần.
Vài quyết định có chủ ý, nếu bạn định sửa skill thì nên biết lý do:
- Khung spec sinh từ Excel cố tình FAIL (
expect(true, ...).toBe(false)). Một khung test luôn xanh nguy hiểm hơn không có test, vì nó tạo cảm giác đã kiểm tra trong khi chưa kiểm tra gì. retries: 2chỉ bật trên CI. Retry ở local sẽ giấu lỗi thật của script.- Race baseline chạy
retries=0, thườngworkers=1. Retry làm sai denominatorx/y; parallel load chỉ được thêm như một biến thử nghiệm riêng. waitForTimeoutkhông dùng để chờ readiness. Nó chỉ được chấp nhận khi delay chính là test input cadence, được đặt tên, đo và đưa vào ma trận.force/dispatchEventlà nhánh chẩn đoán. Bằng chứng chính vẫn phải dùng action user-like với actionability mặc định.- Locator trong
assets/template/pages/LoginPage.tslà phỏng đoán. Cố ý — quy trình bắt buộc chạyexplore.mjslấy locator thật rồi thay vào. - Nội dung viết bằng tiếng Việt, thuật ngữ kỹ thuật giữ tiếng Anh. Tester đọc được thì vẫn sửa được test khi agent không có mặt.
Sửa nội dung trong references/ hoặc assets/template/ rồi mở pull request. Nếu sửa scripts/, chạy thử trước:
node scripts/explore.mjs --url <trang bất kỳ> --out /tmp/recon
node scripts/scaffold.mjs --dir /tmp/e2e --dry-run
python scripts/excel_to_spec.py --file <file.xlsx> --dry-runApache License 2.0 — Copyright 2026 DuongLT.
Bạn được tự do dùng, sửa, phân phối và dùng cho mục đích thương mại. Điều kiện: giữ lại thông báo bản quyền và giấy phép, đồng thời ghi rõ những file bạn đã sửa. Giấy phép cũng cấp quyền sử dụng bằng sáng chế (patent grant) và không đi kèm bảo hành nào.