Cấu hình, Projects, Song song & Sharding
Thiết kế playwright.config.ts cho dự án thật: nhiều môi trường, projects và dependencies, fullyParallel, workers, retry, tag, và tổ chức bộ test theo tầng chạy.
File playwright.config.ts là bảng điều khiển của cả bộ test: nó quyết định chạy cái gì, ở
đâu, nhanh cỡ nào, và thu thập gì khi fail. Cấu hình mặc định chạy được, nhưng một cấu hình được thiết kế có
chủ đích tạo ra khác biệt giữa bộ test 45 phút mà không ai chờ và bộ test 6 phút chạy trên mọi pull request.
Song song hoá cũng là phép thử trung thực nhất cho mọi thứ bạn làm ở Module 5-8: bộ test cô lập tốt thì cứ
thêm worker là nhanh lên; bộ test có phụ thuộc ẩn thì vỡ.
🎯 Mục tiêu học tập
- Viết playwright.config.ts có cấu trúc: môi trường, timeout, thu thập bằng chứng, reporter
- Dùng projects cho trình duyệt, thiết bị, vai trò, và tầng test; nối bằng dependencies
- Hiểu mô hình worker, fullyParallel, và chọn số worker hợp lý
- Đặt chính sách retry có chủ đích và phân biệt flaky với fail
- Dùng tag và annotation để chạy đúng tập test cho từng hoàn cảnh
Một file config cho dự án thật
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
import 'dotenv/config';
import { env } from './utils/env';
const isCI = !!process.env.CI;
export default defineConfig({
testDir: './tests',
outputDir: './test-results',
fullyParallel: true,
workers: isCI ? 4 : undefined, // mặc định cục bộ: một nửa số nhân CPU
forbidOnly: isCI, // test.only lọt vào CI → fail cả lần chạy
retries: isCI ? 2 : 0,
maxFailures: isCI ? 30 : undefined, // dừng sớm khi môi trường sập, đỡ tốn 40 phút
timeout: 30_000,
expect: { timeout: 5_000 },
globalTimeout: isCI ? 30 * 60_000 : undefined,
reporter: isCI
? [['blob'], ['github'], ['junit', { outputFile: 'results/junit.xml' }]]
: [['list'], ['html', { open: 'on-failure' }]],
use: {
baseURL: env.BASE_URL,
actionTimeout: 10_000,
navigationTimeout: 15_000,
trace: 'on-first-retry', // trace đầy đủ cho lần chạy lại đầu tiên
screenshot: 'only-on-failure',
video: 'retain-on-failure',
locale: 'vi-VN',
timezoneId: 'Asia/Ho_Chi_Minh',
testIdAttribute: 'data-testid',
},
projects: [ /* xem mục sau */ ],
// Tự khởi động ứng dụng khi chạy cục bộ; CI thường trỏ tới môi trường đã triển khai
webServer: env.BASE_URL.includes('localhost') ? {
command: 'npm run start:e2e',
url: 'http://localhost:3000/healthz',
reuseExistingServer: !isCI,
timeout: 120_000,
} : undefined,
});
- Cố định
localevàtimezoneId: định dạng ngày, số, tiền phụ thuộc chúng; không cố định thì test pass trên máy bạn và fail trên CI ở múi giờ khác. - Môi trường qua biến (
BASE_URL), không qua nhiều file config. Cùng một bộ test chạy được trên local, staging, và môi trường xem trước của PR. trace: 'on-first-retry'là điểm cân bằng tốt: không tốn chi phí cho test pass, có đủ bằng chứng khi fail. Nếu không bật retry thì dùng'retain-on-failure'.
Projects: một bộ test, nhiều cấu hình
projects: [
// Tầng 0: chuẩn bị
{ name: 'setup', testMatch: /.*\.setup\.ts/, teardown: 'cleanup' },
{ name: 'cleanup', testMatch: /.*\.teardown\.ts/ },
// Tầng 1: API test — nhanh, không trình duyệt
{ name: 'api', testDir: './tests/api', dependencies: ['setup'] },
// Tầng 2: E2E trên trình duyệt chính
{
name: 'chromium',
testIgnore: /tests\/api\//,
use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/customer.json' },
dependencies: ['setup'],
},
// Tầng 3: đa trình duyệt và di động — chỉ tập test được gắn tag
{ name: 'firefox', grep: /@cross-browser/, use: { ...devices['Desktop Firefox'], storageState: '...' }, dependencies: ['setup'] },
{ name: 'webkit', grep: /@cross-browser/, use: { ...devices['Desktop Safari'], storageState: '...' }, dependencies: ['setup'] },
{ name: 'mobile', grep: /@mobile/, use: { ...devices['iPhone 15'], storageState: '...' }, dependencies: ['setup'] },
// Vai trò khác
{
name: 'admin',
testDir: './tests/admin',
use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/admin.json' },
dependencies: ['setup'],
},
],
| Dùng project để | Ghi chú |
|---|---|
| Chạy trên nhiều trình duyệt/thiết bị | Không cần chạy mọi test trên mọi trình duyệt. Phần lớn lỗi là lỗi logic, một trình duyệt bắt được; chạy đa trình duyệt cho tập đại diện |
| Tách tầng test | API, E2E, visual — mỗi tầng một project với cấu hình riêng |
| Vai trò người dùng | Mỗi project một storageState |
| Chuẩn bị và dọn dẹp | dependencies và teardown |
| Tham số hoá bằng option fixture | Cùng test, khác feature flag/ngôn ngữ (Module 5) |
Chạy chọn lọc: --project=chromium, --project=api --project=chromium. Thêm
--no-deps để bỏ qua project phụ thuộc khi đang viết test và file auth đã có sẵn.
Mô hình song song
| Khái niệm | Ý nghĩa |
|---|---|
| Worker | Một tiến trình hệ điều hành, có trình duyệt riêng. Các worker hoàn toàn độc lập, không chia sẻ biến |
| Mặc định | Các file chạy song song trên các worker; các test trong một file chạy tuần tự trên cùng worker |
fullyParallel: true | Mọi test, kể cả trong cùng file, được phân phối độc lập cho các worker |
mode: 'serial' | Các test trong describe chạy lần lượt; một cái fail thì bỏ qua phần sau; retry chạy lại cả nhóm |
| Worker khởi động lại | Sau mỗi test fail, worker bị huỷ và tạo mới để đảm bảo sạch |
// Biến cấp module KHÔNG chia sẻ giữa worker, và bị tạo lại khi worker khởi động lại
let counter = 0; // mỗi worker có bản riêng — đừng dựa vào nó để phối hợp
// Phân vùng tài nguyên theo worker
test('...', async ({ page }, testInfo) => {
testInfo.parallelIndex; // 0..workers-1: ổn định, dùng để chọn tài khoản/cổng/schema
testInfo.workerIndex; // tăng mỗi lần worker khởi động lại: duy nhất, dùng cho tên file tạm
});
Chọn số worker: test Playwright nặng về I/O và trình duyệt ngốn CPU/RAM. Điểm khởi đầu: số worker bằng số nhân CPU của máy CI (hoặc ít hơn một chút), rồi đo. Quá nhiều worker làm mọi thứ chậm đi và sinh timeout giả — một dạng flaky do thiếu tài nguyên. Nút cổ chai cũng có thể ở phía ứng dụng được test: môi trường staging yếu không chịu nổi 16 worker cùng lúc.
Khi một máy không đủ: sharding chia bộ test ra nhiều máy
(--shard=1/4) — chi tiết ở Module 13.
Retry: công cụ, không phải thuốc giảm đau
| Kết quả | Nghĩa là | Hành động |
|---|---|---|
| passed | Pass ngay lần đầu | — |
| flaky | Fail lần đầu, pass khi chạy lại | Phải điều tra — đây là tín hiệu, không phải thành công |
| failed | Fail ở mọi lần thử | Lỗi thật hoặc test hỏng |
- Bật retry trên CI (1-2 lần), tắt ở máy cá nhân: trên CI để pipeline không bị chặn bởi nhiễu hạ tầng; cục bộ để bạn thấy sự chập chờn khi đang viết test.
- Theo dõi tỉ lệ flaky như một chỉ số chất lượng. Retry che dấu vấn đề nếu không ai nhìn vào danh sách test flaky (Module 11, 14).
- Cân nhắc
failOnFlakyTestscho các nhánh quan trọng khi bộ test đã ổn định: flaky cũng làm đỏ pipeline, buộc phải xử lý. - Retry có thể che lỗi sản phẩm thật: một race condition trong ứng dụng xảy ra 1/5 lần sẽ "flaky" rồi pass. Người dùng thì không có nút retry.
- Cấu hình riêng cho nhóm test:
test.describe.configure({ retries: 0 }).
Tag, annotation và chọn tập test
test('đặt hàng thành công bằng thẻ', { tag: ['@smoke', '@checkout', '@cross-browser'] }, async ({ page }) => { ... });
test.describe('báo cáo doanh thu', { tag: '@slow' }, () => { ... });
// Annotation: ghi chú có cấu trúc, hiện trong báo cáo
test('xuất hoá đơn PDF', {
annotation: { type: 'issue', description: 'https://tracker.example.com/BUG-1423' },
}, async ({ page }) => { ... });
// Điều khiển việc chạy
test.skip(({ browserName }) => browserName === 'webkit', 'Tính năng chưa hỗ trợ Safari');
test.fixme('đang hỏng do BUG-1502, sẽ sửa trong sprint 14'); // không chạy, hiện trong báo cáo
test.fail(); // khẳng định test PHẢI fail (lỗi đã biết)
test.slow(); // nhân 3 timeout
npx playwright test --grep @smoke
npx playwright test --grep "@checkout" --grep-invert "@slow"
npx playwright test --grep "(?=.*@smoke)(?=.*@checkout)" # cả hai tag
| Tầng chạy | Khi nào | Tập test | Mục tiêu thời gian |
|---|---|---|---|
| Smoke | Mỗi commit; sau mỗi lần triển khai | @smoke: 10-30 test hành trình sống còn | Dưới 3 phút |
| Pull request | Mỗi PR | API + E2E trên Chromium (trừ @slow) | Dưới 10 phút |
| Đầy đủ | Sau merge vào nhánh chính; hằng đêm | Tất cả, đa trình duyệt, di động, visual | Dưới 30 phút (có sharding) |
Mỗi
test.skip/test.fixme cần lý do và liên kết tới ticket. Không có kỷ luật này, số
test bị bỏ qua tăng dần cho đến khi một phần đáng kể bộ test chỉ còn là trang trí. Đưa "số test bị skip"
vào báo cáo định kỳ.
🏋️ Bài tập thực hành
(1) Viết lại playwright.config.ts theo mẫu: biến môi trường được xác thực, timeout
đủ bốn mức, thu thập trace/screenshot/video có chủ đích, reporter khác nhau cho local và CI, locale và múi
giờ cố định. (2) Định nghĩa các project: setup, cleanup, api, chromium, firefox/webkit cho tập gắn tag,
mobile, và một vai trò thứ hai. (3) Bật fullyParallel và đo thời gian chạy với 1, 2, 4, 8 worker;
vẽ biểu đồ và tìm điểm lợi ích giảm dần; ghi nhận nút cổ chai là máy chạy test hay ứng dụng. (4) Gắn tag cho
toàn bộ test và định nghĩa ba tầng chạy với mục tiêu thời gian; thêm script npm cho từng tầng. (5) Chạy bộ
test 10 lần liên tiếp trên CI với retry bật, thu danh sách test flaky và tỉ lệ. (6) Rà mọi
skip/fixme: thêm lý do và ticket, hoặc xoá.
📚 Tài nguyên học tập
-
Playwright — Test configurationToàn bộ tuỳ chọn cấu hìnhDocs
-
Playwright — ProjectsProjects, dependencies, teardownDocs
-
Playwright — ParallelismWorker, fullyParallel, serial, shardingDocs
-
Playwright — RetriesChính sách retry, khởi động lại worker, phát hiện flakyDocs
-
Playwright — Annotations & tagsskip, fixme, fail, slow, tag và annotationDocs
-
Playwright — Web serverTự khởi động ứng dụng trước khi chạy testDocs
✅ Tự đánh giá hoàn thành
- Config có môi trường qua biến, timeout bốn mức, locale/múi giờ cố định, forbidOnly trên CI
- Projects tách tầng và vai trò, nối bằng dependencies
- fullyParallel bật; số worker được chọn dựa trên đo đạc
- Retry chỉ bật trên CI và tỉ lệ flaky được theo dõi
- Có tag và ba tầng chạy với mục tiêu thời gian; mọi skip/fixme có lý do và ticket