Playwright + TypeScript Thực chiến
Trang chủ / Module 10
⚙️ Module 10 / 15 · 1 tuần

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.

playwright.configProjectsParallelTags
📌 Vì sao module này quan trọng

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 locale và 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 testAPI, E2E, visual — mỗi tầng một project với cấu hình riêng
Vai trò người dùngMỗi project một storageState
Chuẩn bị và dọn dẹpdependencies và teardown
Tham số hoá bằng option fixtureCù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
WorkerMộ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 địnhCá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: trueMọ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ạiSau 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
passedPass ngay lần đầu—
flakyFail lần đầu, pass khi chạy lạiPhải điều tra — đây là tín hiệu, không phải thành công
failedFail ở 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 failOnFlakyTests cho 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ạyKhi nàoTập testMục tiêu thời gian
SmokeMỗi commit; sau mỗi lần triển khai@smoke: 10-30 test hành trình sống cònDưới 3 phút
Pull requestMỗi PRAPI + E2E trên Chromium (trừ @slow)Dưới 10 phút
Đầy đủSau merge vào nhánh chính; hằng đêmTất cả, đa trình duyệt, di động, visualDưới 30 phút (có sharding)
⚠️ skip và fixme phải có hạn

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

Thiết kế cấu hình và tầng chạy cho dự án

(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

✅ 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