Playwright Test Agents: để AI lập kế hoạch, sinh và tự sửa test
Playwright có ba Test Agents: planner tạo test plan Markdown, generator sinh Playwright Test và healer chạy, sửa các test lỗi. Playbook này giúp QA tổ chức quy trình spec → test → bản vá có thể review.
Một luồng mới cần test plan. Một loạt test cũ lại fail vì UI đổi. Thay vì để AI tạo ra một khối mã khó kiểm soát, Playwright Test Agents tách công việc thành các artefact có thể đọc và review: plan Markdown, file test và bản vá cho test lỗi.
Playwright cung cấp sẵn ba agent:
Planner: khám phá ứng dụng và tạo test plan dạng Markdown.
Generator: chuyển test plan Markdown thành các file Playwright Test.
Healer: chạy test suite và tự sửa các test đang fail.
Ba agent có thể dùng độc lập, chạy nối tiếp hoặc ghép thành một vòng lặp agentic. Với QA, luồng dễ kiểm soát nhất là: lập plan → duyệt plan → sinh test → chạy và xem bản vá.
Ba agent, ba đầu ra cần review
| Công việc | Agent | Đầu ra |
|---|---|---|
| Mô tả scenario, bước thực hiện và kết quả mong đợi | Planner | Test plan trong specs/ |
| Chuyển plan thành mã kiểm thử | Generator | Playwright Test trong tests/ |
| Xử lý test thất bại | Healer | Test đã pass hoặc test bị skip |
Điểm quan trọng là agent không chỉ trả lời bằng hội thoại. Playwright tổ chức đầu ra thành file trong repository, giúp đội QA xem lại plan, mã test và thay đổi được đề xuất.
Khởi tạo agent definitions
Bắt đầu bằng lệnh init-agents để thêm agent definitions vào project. Playwright cung cấp lựa chọn cho VS Code, Claude Code, Codex và OpenCode.
Ví dụ với VS Code:
bash
npx playwright init-agents --loop vscode
Với Claude Code:
bash
npx playwright init-agents --loop claude
Với Codex:
bash
npx playwright init-agents --loop codex
Với OpenCode:
bash
npx playwright init-agents --loop opencode
Agent definitions là tập hợp instructions và công cụ MCP do Playwright cung cấp. Tài liệu khuyến nghị tạo lại chúng mỗi khi cập nhật Playwright để nhận instructions và tools mới.
> Trải nghiệm agentic trong VS Code yêu cầu VS Code v1.105 trở lên. Phiên bản này được phát hành ngày 9/10/2025.
Cấu trúc artefact điển hình:
text
repo/
.github/
specs/
basic-operations.md
tests/
seed.spec.ts
create/
add-valid-todo.spec.ts
playwright.config.ts
Trong đó:
.github/ chứa agent definitions.
specs/ chứa test plan có thể đọc được.
tests/ chứa Playwright Test được sinh.
seed.spec.ts chuẩn bị môi trường để agent tương tác với ứng dụng.
Bắt đầu bằng seed test
Planner nhận một yêu cầu rõ ràng, chẳng hạn: “Generate a plan for guest checkout”.
Agent cũng có thể dùng:
Seed test để thiết lập môi trường cần thiết.
PRD để có thêm bối cảnh về sản phẩm.
Seed test giúp planner chạy các phần khởi tạo đã có trong dự án, gồm global setup, project dependencies, fixtures và hooks. Nó cũng là ví dụ để agent dựa vào khi tạo test.
Ví dụ seed test dùng custom fixture:
ts
import { test, expect } from './fixtures'
test('seed', async ({ page }) => {
// this test uses custom fixtures from ./fixtures
})
Khi giao việc cho planner, hãy đưa seed.spec.ts vào context hoặc nêu rõ tên file trong prompt. Nhờ vậy, agent biết cách khởi tạo đúng page, fixture và môi trường hiện có trước khi khám phá ứng dụng.
Bước 1: Dùng planner tạo test plan
Planner khám phá ứng dụng và sinh test plan Markdown cho một hoặc nhiều scenario, user flow.
Đầu ra được lưu trong specs/. Ví dụ theo tài liệu Playwright:
text
specs/basic-operations.md
Một test plan có thể gồm:
Tổng quan ứng dụng.
Nhóm test scenario.
Seed test được sử dụng.
Các bước thực hiện.
Kết quả mong đợi.
Ví dụ một scenario trong plan:
md
### 1.1 Add Valid Todo
Steps:
Click in the "What needs to be done?" input field
Type "Buy groceries"
Press Enter key
Expected Results:
Todo appears in the list with unchecked checkbox
Counter shows "1 item left"
Input field is cleared and ready for next entry
Đây là điểm QA nên dừng lại để review. Plan là lớp trung gian giữa yêu cầu và mã test: dễ đọc hơn script, nhưng phải đủ cụ thể để generator biến thành test chạy được.
Bước 2: Dùng generator tạo Playwright Test
Generator nhận test plan Markdown trong specs/ và tạo test suite trong tests/.
Khi thực hiện scenario, generator xác minh locator và assertion trực tiếp. Playwright cũng hỗ trợ generation hints và catalog assertion để phục vụ việc kiểm tra cấu trúc và hành vi.
Ví dụ, generator có thể tạo file:
text
tests/add-valid-todo.spec.ts
Test được sinh có thể liên kết trở lại plan và seed test:
ts
// spec: specs/basic-operations.md
// seed: tests/seed.spec.ts
Với scenario thêm todo, test minh họa trong tài liệu dùng locator theo role, thực hiện thao tác rồi kiểm tra kết quả:
ts
const todoInput = page.getByRole('textbox', {
name: 'What needs to be done?'
})
await todoInput.click()
await todoInput.fill('Buy groceries')
await todoInput.press('Enter')
await expect(page.getByText('Buy groceries')).toBeVisible()
const todoCheckbox = page.getByRole('checkbox', {
name: 'Toggle Todo'
})
await expect(todoCheckbox).toBeVisible()
await expect(todoCheckbox).not.toBeChecked()
await expect(page.getByText('1 item left')).toBeVisible()
await expect(todoInput).toHaveValue('')
await expect(todoInput).toBeFocused()
Sau khi generator tạo test, hãy đối chiếu lại ba phần:
Scenario trong file Markdown có đầy đủ không?
Locator có trỏ đến đúng phần tử mà scenario yêu cầu không?
Assertion có phản ánh đúng expected result trong plan không?
Bước 3: Dùng healer khi test fail
Healer xử lý khi test không chạy qua. Theo tài liệu Playwright, agent sẽ:
Phát lại các bước bị lỗi.
Kiểm tra UI hiện tại để tìm phần tử hoặc flow tương đương.
Đề xuất bản vá, chẳng hạn cập nhật locator, điều chỉnh chờ hoặc sửa dữ liệu.
Chạy lại test cho đến khi pass hoặc đến khi guardrail dừng vòng lặp.
Đầu ra của healer có thể là:
Một test đã pass.
Một test bị skip nếu healer cho rằng chức năng đang bị hỏng.
Đây là lý do bản vá từ healer vẫn cần được review như một thay đổi mã bình thường. Nếu locator thay đổi, QA cần xác nhận phần tử mới vẫn đúng với scenario. Nếu test bị skip, đội cần xác định đây là lỗi chức năng hay thay đổi hợp lệ của sản phẩm.
Quy trình làm việc gợi ý cho QA
Một quy trình ngắn gọn, dễ truy vết:
Chuẩn bị seed.spec.ts với fixture và môi trường cần thiết.
Yêu cầu planner tạo plan trong specs/.
Review scenario, bước test và expected result trong Markdown.
Yêu cầu generator tạo test trong tests/.
Review locator, assertion và liên kết giữa test với spec.
Chạy test suite.
Khi test fail, dùng healer để tạo bản vá hoặc xác định test cần skip.
Review thay đổi trước khi chấp nhận vào suite.
Checklist trước khi dùng vòng lặp agentic
[ ] Có seed test phù hợp với môi trường và fixture của dự án.
[ ] Planner nhận được yêu cầu rõ ràng và, nếu cần, PRD.
[ ] Test plan đã được xem lại trước khi sinh mã test.
[ ] Test sinh ra được đối chiếu với scenario trong specs/.
[ ] Bản vá từ healer được kiểm tra trước khi chấp nhận.
[ ] Agent definitions được tạo lại khi Playwright được cập nhật.
Playwright Test Agents không thay thế vai trò thiết kế test của QA. Chúng giúp đưa quy trình từ yêu cầu đến test chạy được vào các artefact rõ ràng: planner tạo plan, generator tạo test và healer xử lý lỗi. Khi giữ được specs/, tests/ và các thay đổi có thể review, đội vừa tận dụng được AI vừa duy trì khả năng kiểm soát chất lượng.