React E2E Testing Custom Skill

Skill dành cho Codex để chuyển tài liệu testcase Markdown thành Playwright E2E spec theo ánh xạ một-một, chạy kiểm thử đầy đủ và tạo báo cáo Markdown có expected result, actual result cùng screenshot cho từng testcase.

Chức năng chính

• Đối chiếu testcase Markdown, Playwright spec và báo cáo theo Test Case ID.
• Tạo một Playwright test(...) độc lập cho mỗi testcase được tài liệu hóa.
• Hỗ trợ xác thực thật hoặc mock API theo đúng service contract của ứng dụng.
• Kiểm thử phân quyền, bảng dữ liệu, form, trang chi tiết và refetch sau mutation.
• Tạo báo cáo Markdown tự động kể cả khi test thất bại.
• Kiểm tra độ phủ bằng script audit đi kèm.
• Tổng hợp nhiều báo cáo Markdown thành tài liệu DOCX khi cần.

Yêu cầu hệ thống

Bắt buộc để cài skill

• Node.js 18 trở lên.
• npm, hoặc một package runner tương thích với npx.
• Codex có hỗ trợ repository skill trong .agents/skills.
• Project đích phải có file package.json tại thư mục gốc.

Bắt buộc để chạy E2E

Cài Playwright Test trong project đích:

npm install --save-dev @playwright/test
npx playwright install

Trong môi trường CI Linux, có thể cần cài thêm system dependencies:

npx playwright install --with-deps

Project cũng cần có:

• playwright.config.ts hoặc file cấu hình Playwright tương đương.
• Script khởi động ứng dụng hoặc cấu hình webServer cho Playwright.
• Các biến môi trường kiểm thử như .env.test nếu dùng đăng nhập thật.
• Tài liệu testcase Markdown và thư mục chứa E2E spec phù hợp với cấu trúc project.

Skill không tự động cài hoặc thay đổi các dependency của project đích.

Tùy chọn

Để lint Playwright spec theo workflow được đề xuất:

npm install --save-dev eslint

Nếu project đã có ESLint thì không cần cài lại.

Để tổng hợp các báo cáo Markdown thành DOCX, cài Python 3 và python-docx:

python -m pip install python-docx

Trên một số hệ thống, lệnh Python có thể là python3:

python3 -m pip install python-docx

python-docx không cần thiết nếu chỉ tạo Playwright spec và báo cáo Markdown.

Cài đặt

Sau khi package được publish lên npm, chạy tại thư mục gốc của project đích:

npx react-e2e-testing-custom-skill init

Skill được cài vào:

.agents/skills/react-e2e-testing-custom

Cài vào một project khác với đường dẫn cụ thể:

npx react-e2e-testing-custom-skill init --project /path/to/project

Kiểm tra trước mà không ghi file:

npx react-e2e-testing-custom-skill init --dry-run

Cập nhật

Để thay thế phiên bản đã cài:

npx react-e2e-testing-custom-skill init --update

--update và --force có cùng tác dụng. CLI không xóa bản cũ mà đổi tên nó thành thư mục backup bên cạnh bản mới:

.agents/skills/react-e2e-testing-custom.backup-<timestamp>-<pid>

Sau khi xác nhận bản mới hoạt động, người dùng có thể tự xóa backup.

Sử dụng với Codex

Khởi động Codex tại project đã cài skill. Nếu skill chưa xuất hiện ngay, mở một lượt làm việc mới hoặc khởi động lại Codex.

Gọi skill trực tiếp trong prompt:

$react-e2e-testing-custom hãy chuyển docs/test-case/ticket.md thành Playwright E2E spec đầy đủ, chạy test và tạo báo cáo Markdown.

Codex cũng có thể tự kích hoạt skill khi yêu cầu phù hợp với phần description trong SKILL.md.

Workflow điển hình

1. Đặt tài liệu testcase trong docs/test-case/ hoặc thư mục tương ứng của project.
2. Yêu cầu Codex đọc testcase, code giao diện, service contract và cấu hình Playwright.
3. Codex tạo một test độc lập cho từng Test Case ID.
4. Chạy discovery và coverage audit trước khi chạy browser.
5. Chạy toàn bộ module spec, kể cả khi có lỗi sản phẩm đã biết.
6. Tạo báo cáo Markdown và chạy coverage audit lần cuối.

Các lệnh kiểm tra thường dùng:

npx playwright test test/e2e/<module>.spec.ts --list
node .agents/skills/react-e2e-testing-custom/scripts/audit-e2e-coverage.cjs \
  --cases docs/test-case/<module>.md \
  --spec test/e2e/<module>.spec.ts
npx playwright test test/e2e/<module>.spec.ts

Sau khi có báo cáo:

node .agents/skills/react-e2e-testing-custom/scripts/audit-e2e-coverage.cjs \
  --cases docs/test-case/<module>.md \
  --spec test/e2e/<module>.spec.ts \
  --report docs/test-case/test-result/<module>-e2e-report.md

Trên PowerShell, thay ký tự nối dòng \ bằng backtick hoặc viết lệnh trên một dòng.

Các file được cài

react-e2e-testing-custom/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   └── aggregate-test-documentation.md
└── scripts/
    ├── audit-e2e-coverage.cjs
    ├── build_aggregate_e2e_docx.py
    ├── playwright-markdown-reporter.cjs
    └── playwright-report-fixture.ts

README, npm installer và test của installer thuộc package phân phối nhưng không được copy vào .agents/skills của project đích.

Lệnh CLI

react-e2e-skill init [options]

--project <path>  Chọn thư mục gốc của project
--force           Thay thế bản đã cài và giữ backup
--update          Bí danh của --force
--dry-run         Hiển thị thao tác mà không ghi file
--version         Hiển thị phiên bản package
--help            Hiển thị trợ giúp

Bảo mật

• Không đưa mật khẩu, token, cookie, JWT hoặc authorization header vào testcase, report hay screenshot.
• Không commit giá trị bí mật trong .env.test.
• Ưu tiên secret store của CI cho tài khoản kiểm thử.
• Kiểm tra screenshot trước khi chia sẻ báo cáo ra ngoài tổ chức.

License

Phát hành theo MIT License.