Playwright + TypeScript Thực chiến
Trang chủ / Module 4
✅ Module 4 / 15 · 1 tuần

Assertions & Chờ đúng cách

Web-first assertion tự thử lại, phân biệt với assertion tức thời, soft assertion, expect.poll và toPass, phân cấp timeout, và viết custom matcher.

AssertionsAuto-retryTimeoutsexpect.poll
📌 Vì sao module này quan trọng

Một test chỉ có giá trị bằng những gì nó khẳng định. Hai kiểu thất bại phổ biến: assertion không tự chờ (đọc giá trị ra rồi so, flaky khi trang chưa cập nhật xong), và assertion quá yếu (chỉ kiểm tra "trang không sập", bỏ lọt lỗi thật). Playwright cho bạn bộ assertion tự thử lại rất mạnh — nhưng chỉ khi dùng đúng dạng. Module này cũng làm rõ hệ thống timeout, thứ mà khi hiểu sai sẽ khiến người ta tăng timeout toàn cục lên 2 phút để "chữa" flaky.

🎯 Mục tiêu học tập

  • Phân biệt assertion tự thử lại (trên locator/page) với assertion tức thời (trên giá trị)
  • Dùng đúng bộ matcher: trạng thái, nội dung, thuộc tính, số lượng, URL
  • Dùng expect.poll và toPass cho điều kiện không gắn với locator
  • Hiểu phân cấp timeout: test, expect, action, navigation
  • Viết soft assertion, thông báo lỗi tuỳ biến, và custom matcher

Tự thử lại hay tức thời: khác biệt sống còn

// TỒI — tức thời: đọc giá trị tại MỘT thời điểm rồi so
const text = await page.getByTestId('cart-count').textContent();
expect(text).toBe('3');                       // flaky: giỏ hàng có thể chưa cập nhật xong

const visible = await page.getByRole('alert').isVisible();
expect(visible).toBe(true);                   // isVisible() trả về ngay, không chờ

// TỐT — web-first: truyền LOCATOR vào expect, Playwright tự thử lại đến khi đúng
await expect(page.getByTestId('cart-count')).toHaveText('3');
await expect(page.getByRole('alert')).toBeVisible();

Cách nhận biết: await expect(locator)... thì tự thử lại; expect(giá trị)... thì không. Các phương thức trả về giá trị ngay — textContent(), innerText(), isVisible(), isEnabled(), count(), getAttribute(), inputValue() — gần như không bao giờ nên đi cùng expect. Mỗi cái đều có matcher tương ứng tự thử lại.

Thay vìDùng
expect(await l.isVisible()).toBe(true)await expect(l).toBeVisible()
expect(await l.textContent()).toContain('x')await expect(l).toContainText('x')
expect(await l.count()).toBe(5)await expect(l).toHaveCount(5)
expect(await l.inputValue()).toBe('x')await expect(l).toHaveValue('x')
expect(await l.getAttribute('href')).toBe(u)await expect(l).toHaveAttribute('href', u)
expect(page.url()).toContain('/orders')await expect(page).toHaveURL(/\/orders\/\w+/)

Bộ matcher thường dùng

NhómMatcher
Trạng tháitoBeVisible, toBeHidden, toBeEnabled, toBeDisabled, toBeChecked, toBeFocused, toBeEditable, toBeAttached, toBeInViewport
Nội dungtoHaveText (khớp toàn bộ, chuẩn hoá khoảng trắng), toContainText, toHaveValue, toHaveValues
Thuộc tínhtoHaveAttribute, toHaveClass, toHaveCSS, toHaveId, toHaveAccessibleName, toHaveRole
Tập hợptoHaveCount; toHaveText([...]) với mảng để kiểm tra cả danh sách theo thứ tự
TrangtoHaveURL, toHaveTitle
APIexpect(response).toBeOK()
Ảnh / cấu trúctoHaveScreenshot, toMatchAriaSnapshot (Module 12)
// Kiểm tra cả danh sách, đúng thứ tự, trong một assertion tự thử lại
await page.getByRole('combobox', { name: 'Sắp xếp' }).selectOption({ label: 'Giá tăng dần' });
await expect(page.getByTestId('product-price')).toHaveText(['89.000 ₫', '129.000 ₫', '189.000 ₫']);

// Phủ định cũng tự thử lại: chờ đến khi spinner biến mất
await expect(page.getByRole('progressbar')).toBeHidden();
await expect(page.getByRole('button', { name: 'Gửi' })).not.toBeDisabled();
⚠️ Cẩn thận với assertion phủ định

await expect(errorMessage).toBeHidden() ngay sau khi bấm nút sẽ pass tức thì — vì lỗi chưa kịp hiện. Assertion phủ định chỉ có nghĩa sau khi bạn đã khẳng định một điều tích cực chứng tỏ thao tác đã xử lý xong (thông báo thành công hiện, URL đổi). Thứ tự đúng: chờ dấu hiệu hoàn tất, rồi mới kiểm tra thứ không được xuất hiện.

expect.poll và toPass: thử lại cho mọi thứ khác

Khi điều kiện không gắn với một locator — trạng thái ở backend, một file, kết quả của nhiều bước:

// expect.poll: gọi lại hàm cho đến khi giá trị trả về thoả matcher
await expect.poll(async () => {
  const res = await request.get(`/api/orders/${orderId}`);
  return (await res.json()).status;
}, {
  message: 'Đơn hàng phải chuyển sang "paid" sau khi webhook thanh toán được xử lý',
  timeout: 30_000,
  intervals: [500, 1000, 2000],        // giãn dần; phần tử cuối lặp lại
}).toBe('paid');

// toPass: thử lại cả một khối gồm nhiều bước và nhiều assertion
await expect(async () => {
  await page.getByRole('button', { name: 'Làm mới' }).click();
  await expect(page.getByRole('row', { name: /DH-104233/ })).toContainText('Đã giao', { timeout: 2_000 });
}).toPass({ timeout: 60_000 });
expect.polltoPass
Thử lại cái gìMột hàm trả về giá trịMột khối code có assertion bên trong
Dùng choTrạng thái backend, giá trị tính toán"Làm X rồi kiểm tra Y, chưa được thì làm lại"
Lưu ýHàm phải không có tác dụng phụKhối phải chạy lại an toàn; đặt timeout ngắn cho assertion bên trong

Đây là thay thế đúng đắn cho mọi waitForTimeout kiểu "chờ 5 giây cho job nền chạy xong". Nhưng đừng lạm dụng toPass để che một thao tác UI chập chờn — nếu phải bấm lại nút mới ăn, đó là lỗi cần điều tra (Module 11).

Phân cấp timeout

TimeoutMặc địnhPhạm viCấu hình
Test30 giâyToàn bộ một test (kể cả fixture setup và hook)timeout trong config; test.setTimeout(); test.slow() (nhân 3)
Expect5 giâyMỗi assertion tự thử lạiexpect: { timeout } trong config; tham số { timeout } của từng assertion
ActionKhông giới hạn (bị chặn bởi timeout test)Mỗi click, fill...use: { actionTimeout }
NavigationKhông giới hạn (bị chặn bởi timeout test)goto, waitForURLuse: { navigationTimeout }
GlobalKhôngToàn bộ lần chạyglobalTimeout — nên đặt trên CI
// playwright.config.ts — điểm khởi đầu hợp lý
export default defineConfig({
  timeout: 30_000,
  expect: { timeout: 5_000 },
  use: { actionTimeout: 10_000, navigationTimeout: 15_000 },
  globalTimeout: process.env.CI ? 30 * 60_000 : undefined,
});
  • Đặt actionTimeout: không có nó, một cú click vào phần tử không tồn tại treo đủ 30 giây rồi báo "test timeout" mơ hồ. Có nó, lỗi báo sau 10 giây và chỉ đúng dòng.
  • Tăng timeout cục bộ, có lý do: một thao tác biết là chậm (xuất báo cáo) thì toBeVisible({ timeout: 30_000 }) ngay tại đó, kèm chú thích. Không tăng toàn cục.
  • Tăng timeout toàn cục không chữa được flaky — nó chỉ làm mỗi lần fail tốn thêm thời gian và che dấu vấn đề hiệu năng thật.

Soft assertion, thông báo lỗi, và test.step

test('trang chi tiết đơn hàng hiển thị đủ thông tin', async ({ page }) => {
  await page.goto(`/orders/${orderId}`);

  // Điều kiện tiên quyết: assertion cứng — sai thì dừng
  await expect(page.getByRole('heading', { name: `Đơn hàng ${orderId}` })).toBeVisible();

  // Nhiều kiểm tra độc lập: soft — ghi nhận lỗi và đi tiếp, cuối test mới fail
  await expect.soft(page.getByTestId('order-status')).toHaveText('Đã thanh toán');
  await expect.soft(page.getByTestId('order-total')).toHaveText('1.250.000 ₫');
  await expect.soft(page.getByTestId('shipping-address')).toContainText('Quận 1');

  // Thông báo tuỳ biến: nói ĐIỀU GÌ sai về mặt nghiệp vụ
  await expect(page.getByRole('button', { name: 'Huỷ đơn' }),
    'Đơn đã thanh toán không được phép huỷ trực tiếp').toBeDisabled();
});

// test.step: chia test dài thành các bước có tên, hiện trong báo cáo và trace
await test.step('Thêm sản phẩm vào giỏ', async () => { ... });
await test.step('Áp mã giảm giá', async () => { ... });

Dùng soft assertion khi các kiểm tra độc lập và bạn muốn thấy tất cả lỗi trong một lần chạy (kiểm tra nhiều trường trên một trang). Không dùng cho điều kiện mà các bước sau phụ thuộc.

Custom matcher

Khi một kiểm tra nghiệp vụ lặp lại nhiều nơi, đóng gói thành matcher để test đọc như đặc tả:

// fixtures/matchers.ts
import { expect as base, type Locator } from '@playwright/test';

export const expect = base.extend({
  async toHaveMoney(locator: Locator, expected: number, options?: { timeout?: number }) {
    const formatted = new Intl.NumberFormat('vi-VN').format(expected) + ' ₫';
    let pass = true;
    let message = '';
    try {
      await base(locator).toHaveText(formatted, options);       // tái dùng matcher tự thử lại
    } catch (e) {
      pass = false;
      message = (e as Error).message;
    }
    return {
      pass,
      name: 'toHaveMoney',
      message: () => pass ? `Không mong đợi ${formatted}` : `Số tiền không khớp, mong đợi ${formatted}\n${message}`,
    };
  },
});

// Trong test
await expect(page.getByTestId('order-total')).toHaveMoney(1_250_000);

Điểm mấu chốt: xây custom matcher trên một matcher tự thử lại có sẵn để thừa hưởng cơ chế chờ. Xuất expect này từ fixtures/index.ts cùng với test (Module 5) để cả dự án dùng chung.

🏋️ Bài tập thực hành

Loại bỏ mọi assertion tức thời và mọi sleep

(1) Quét dự án tìm mọi expect(await ...), isVisible(), textContent(), count() đi cùng expect, và mọi waitForTimeout. Thay từng cái bằng dạng tự thử lại tương ứng; bật quy tắc lint prefer-web-first-assertions. (2) Tìm một luồng có xử lý nền (thanh toán qua webhook, gửi email, xuất file) và viết test dùng expect.poll kiểm tra trạng thái qua API. (3) Cấu hình bốn mức timeout như mẫu; cố ý click một phần tử không tồn tại, so sánh thông báo lỗi khi có và không có actionTimeout. (4) Viết một custom matcher cho một kiểm tra nghiệp vụ lặp lại trong ứng dụng của bạn. (5) Viết một test có lỗi "assertion phủ định pass quá sớm", chứng minh nó pass sai, rồi sửa bằng cách chờ dấu hiệu hoàn tất trước.

📚 Tài nguyên học tập

✅ Tự đánh giá hoàn thành

  • Không còn expect(await locator.xxx()) trong dự án
  • Không còn waitForTimeout; mọi chỗ chờ đều gắn với một điều kiện cụ thể
  • Dùng expect.poll/toPass cho trạng thái backend và xử lý nền
  • Có actionTimeout và navigationTimeout; không tăng timeout toàn cục để chữa flaky
  • Dùng soft assertion, thông báo lỗi nghiệp vụ, và test.step ở chỗ phù hợp