Kiến trúc Playwright & Dựng dự án TypeScript chuẩn
Playwright hoạt động thế nào bên dưới (browser → context → page), vì sao nó ít flaky hơn thế hệ trước, và dựng một dự án TypeScript có lint chặt ngay từ đầu.
Khoá Advanced QA & Test Engineering dạy chiến lược kiểm thử ở mức không phụ thuộc công cụ. Khoá này đi theo hướng ngược lại: chọn một công cụ — Playwright với TypeScript — và đi tới tận đáy, đủ để bạn dựng và vận hành bộ E2E cho một sản phẩm thật. Phần lớn bộ test Playwright tồi không phải vì người viết thiếu kỹ năng test, mà vì họ mang thói quen từ Selenium/Cypress sang (sleep cố định, XPath, một browser dùng chung) và bỏ qua những thứ Playwright thiết kế sẵn để chống flaky. Hiểu kiến trúc trước giúp mọi best practice về sau trở nên hiển nhiên thay vì phải học thuộc.
🎯 Mục tiêu học tập
- Giải thích mô hình Browser → BrowserContext → Page và vì sao mỗi test có một context riêng
- Hiểu cơ chế auto-waiting và web-first assertion — hai thứ khiến Playwright ít flaky
- Dựng dự án Playwright + TypeScript với cấu trúc thư mục, tsconfig strict, và ESLint bắt lỗi quên await
- Chạy, lọc, debug test bằng CLI và UI Mode
Mô hình Browser → Context → Page
| Tầng | Là gì | Chi phí tạo | Vòng đời mặc định trong Playwright Test |
|---|---|---|---|
| Browser | Một tiến trình trình duyệt (Chromium, Firefox, WebKit) | Đắt (hàng trăm ms đến vài giây) | Một lần cho mỗi worker |
| BrowserContext | Một "hồ sơ ẩn danh" cô lập: cookie, localStorage, quyền, cache riêng | Rất rẻ (vài ms) | Mới cho mỗi test |
| Page | Một tab trong context | Rẻ | Mới cho mỗi test |
Đây là quyết định thiết kế quan trọng nhất của Playwright: mỗi test nhận một context hoàn toàn mới. Test A đăng nhập, thêm hàng vào giỏ — test B không thấy gì trong số đó. Bạn có được sự cô lập gần như của việc mở trình duyệt mới cho mỗi test, với chi phí gần bằng không. Hệ quả:
- Test chạy được theo bất kỳ thứ tự nào và song song mà không dẫm lên nhau ở phía trình duyệt. (Dữ liệu phía server là chuyện khác — Module 8.)
- Không cần code "dọn dẹp cookie" trong
afterEach. - Muốn hai người dùng tương tác trong một test (chat, phân quyền)? Tạo hai context.
Playwright điều khiển trình duyệt từ ngoài tiến trình qua giao thức gỡ lỗi (CDP với Chromium, giao thức tương đương với Firefox/WebKit) trên một kết nối WebSocket duy nhất. Khác với công cụ chạy bên trong trang, nó không bị giới hạn bởi same-origin, điều khiển được nhiều tab, nhiều origin, iframe, và chặn được mạng ở tầng trình duyệt.
Vì sao Playwright ít flaky: auto-waiting và web-first assertion
Nguồn flaky lớn nhất của E2E là thời điểm: test thao tác khi trang chưa sẵn sàng.
Thế hệ công cụ trước bắt người viết tự chờ (sleep, waitForElement). Playwright
đưa việc chờ vào bên trong mọi thao tác:
| Cơ chế | Hoạt động |
|---|---|
| Auto-waiting cho hành động | Trước khi click(), Playwright tự chờ phần tử: gắn vào DOM, hiển thị, đứng yên (hết animation), nhận được sự kiện (không bị che), và đang bật. Thử lại cho đến khi đạt hoặc hết timeout |
| Locator lười | page.getByRole(...) không tìm phần tử ngay; nó là một mô tả cách tìm, được phân giải lại mỗi lần dùng. Không còn lỗi "stale element" |
| Web-first assertion | await expect(locator).toHaveText('Xong') tự thử lại cho đến khi đúng hoặc hết timeout (mặc định 5 giây) |
// Không cần bất kỳ lệnh chờ tường minh nào
await page.getByRole('button', { name: 'Thanh toán' }).click(); // tự chờ nút bấm được
await expect(page.getByRole('heading', { name: 'Đặt hàng thành công' })).toBeVisible(); // tự thử lại
Nếu bạn thấy
mình sắp viết page.waitForTimeout(3000), hãy dừng lại. Gần như luôn tồn tại một điều kiện cụ
thể để chờ (một phần tử xuất hiện, một response về, một URL đổi). Sleep cố định vừa làm test chậm, vừa
vẫn flaky khi máy CI chậm hơn dự tính.
Khởi tạo dự án và cấu trúc thư mục
npm init playwright@latest # chọn TypeScript, thư mục tests, thêm GitHub Actions workflow
npx playwright install --with-deps # tải trình duyệt và thư viện hệ thống
Cấu trúc thư mục khuyến nghị cho dự án thật (các module sau sẽ lấp đầy từng phần):
e2e/
├── playwright.config.ts
├── tsconfig.json
├── .env.example # mẫu biến môi trường; file .env thật KHÔNG commit
├── tests/
│ ├── auth.setup.ts # đăng nhập một lần, lưu storageState (Module 7)
│ ├── checkout/
│ │ ├── checkout.spec.ts
│ │ └── coupon.spec.ts
│ └── catalog/search.spec.ts
├── fixtures/
│ └── index.ts # test.extend(...) — điểm import duy nhất (Module 5)
├── pages/ # page object và component object (Module 6)
│ ├── checkout.page.ts
│ └── components/header.component.ts
├── api/ # client gọi API để chuẩn bị dữ liệu (Module 8)
│ └── orders.api.ts
├── data/ # factory sinh dữ liệu test
│ └── user.factory.ts
└── utils/
- Tổ chức test theo tính năng (checkout, catalog), không theo loại (smoke, regression) — loại test dùng tag (Module 10).
- File spec chỉ import
testvàexpecttừfixtures/, không trực tiếp từ@playwright/test. Lint được quy tắc này. - E2E có thể nằm chung repo với ứng dụng (dễ đổi test cùng PR với code) — thường là lựa chọn tốt hơn repo riêng.
tsconfig và ESLint: bắt lỗi trước khi chạy
// tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"strict": true,
"noUncheckedIndexedAccess": true,
"noEmit": true,
"baseUrl": ".",
"paths": {
"@fixtures": ["fixtures/index.ts"],
"@pages/*": ["pages/*"],
"@api/*": ["api/*"],
"@data/*": ["data/*"]
}
},
"include": ["**/*.ts"]
}
Playwright tự biên dịch TypeScript khi chạy nhưng không kiểm tra kiểu. Phải chạy
tsc --noEmit riêng (trong CI và pre-commit), nếu không lỗi kiểu sẽ lọt.
// eslint.config.mjs
import tseslint from 'typescript-eslint';
import playwright from 'eslint-plugin-playwright';
export default tseslint.config(
...tseslint.configs.recommendedTypeChecked,
{
languageOptions: { parserOptions: { projectService: true } },
rules: {
'@typescript-eslint/no-floating-promises': 'error', // quên await → lỗi
'@typescript-eslint/await-thenable': 'error',
},
},
{
...playwright.configs['flat/recommended'],
files: ['tests/**'],
rules: {
...playwright.configs['flat/recommended'].rules,
'playwright/no-wait-for-timeout': 'error',
'playwright/no-focused-test': 'error', // chặn test.only lọt vào repo
'playwright/no-skipped-test': 'warn',
'playwright/prefer-web-first-assertions': 'error',
'playwright/no-networkidle': 'error',
'playwright/expect-expect': 'warn',
},
},
);
Quên
await. expect(locator).toBeVisible() không có await trả về một
Promise bị bỏ rơi: test pass ngay cả khi phần tử không tồn tại, hoặc fail ở một dòng
khác hẳn chỗ sai. Quy tắc no-floating-promises biến lỗi này thành lỗi lint. Đây là quy tắc
lint đáng giá nhất của cả dự án.
Chạy và debug hằng ngày
| Lệnh | Dùng khi |
|---|---|
npx playwright test | Chạy tất cả, không giao diện |
npx playwright test --ui | UI Mode: chạy, xem lại từng bước, tự chạy lại khi sửa file — môi trường viết test chính |
npx playwright test checkout/ -g "mã giảm giá" | Lọc theo thư mục và theo tên |
npx playwright test --project=chromium --headed | Một trình duyệt, có cửa sổ |
npx playwright test --debug | Mở Inspector, chạy từng bước |
npx playwright test --last-failed | Chỉ chạy lại các test vừa trượt |
npx playwright test --repeat-each=20 | Kiểm tra độ ổn định của test mới |
npx playwright codegen https://... | Ghi thao tác thành code — để khám phá locator, không phải để dùng nguyên văn |
npx playwright show-report / show-trace trace.zip | Mở báo cáo HTML / trace |
Cài extension Playwright Test for VS Code: chạy/debug từng test từ lề trái, chọn locator trực tiếp trên trang, xem trace ngay trong editor.
🏋️ Bài tập thực hành
Chọn một ứng dụng để dùng suốt khoá (ứng dụng của công ty bạn trên môi trường staging, hoặc một
ứng dụng mẫu công khai có đăng nhập và giỏ hàng). (1) Khởi tạo dự án theo cấu trúc thư mục ở trên, cấu hình
tsconfig strict và ESLint như mẫu. (2) Viết 3 test đầu tiên cho một luồng đơn giản. (3) Cố ý tạo ba lỗi:
quên await trước một expect, thêm waitForTimeout, để lại
test.only — xác nhận lint báo cả ba. (4) Thêm script npm run check chạy
tsc --noEmit và eslint, gắn vào pre-commit. (5) Viết một test mở hai
BrowserContext cùng lúc để tự thấy chúng không chia sẻ cookie.
📚 Tài nguyên học tập
-
Playwright — InstallationKhởi tạo dự án và chạy test đầu tiênDocs
-
Playwright — Isolation (Browser contexts)Mô hình cô lập bằng BrowserContextDocs
-
Playwright — Auto-waiting (Actionability)Các kiểm tra Playwright thực hiện trước mỗi hành độngDocs
-
eslint-plugin-playwrightBộ quy tắc lint cho PlaywrightRepo
-
Playwright — TypeScriptCấu hình TypeScript, path mapping, kiểm tra kiểuDocs
✅ Tự đánh giá hoàn thành
- Giải thích được Browser, Context, Page và vì sao mỗi test có context riêng
- Giải thích được auto-waiting và web-first assertion bằng ví dụ
- Dự án có tsconfig strict, tsc --noEmit và ESLint với no-floating-promises
- Dùng thành thạo UI Mode, --debug, --last-failed, --repeat-each