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.
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óm | Matcher |
|---|---|
| Trạng thái | toBeVisible, toBeHidden, toBeEnabled, toBeDisabled, toBeChecked, toBeFocused, toBeEditable, toBeAttached, toBeInViewport |
| Nội dung | toHaveText (khớp toàn bộ, chuẩn hoá khoảng trắng), toContainText, toHaveValue, toHaveValues |
| Thuộc tính | toHaveAttribute, toHaveClass, toHaveCSS, toHaveId, toHaveAccessibleName, toHaveRole |
| Tập hợp | toHaveCount; toHaveText([...]) với mảng để kiểm tra cả danh sách theo thứ tự |
| Trang | toHaveURL, toHaveTitle |
| API | expect(response).toBeOK() |
| Ảnh / cấu trúc | toHaveScreenshot, 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();
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.poll | toPass | |
|---|---|---|
| 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 cho | Trạ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
| Timeout | Mặc định | Phạm vi | Cấu hình |
|---|---|---|---|
| Test | 30 giây | Toàn bộ một test (kể cả fixture setup và hook) | timeout trong config; test.setTimeout(); test.slow() (nhân 3) |
| Expect | 5 giây | Mỗi assertion tự thử lại | expect: { timeout } trong config; tham số { timeout } của từng assertion |
| Action | Không giới hạn (bị chặn bởi timeout test) | Mỗi click, fill... | use: { actionTimeout } |
| Navigation | Không giới hạn (bị chặn bởi timeout test) | goto, waitForURL | use: { navigationTimeout } |
| Global | Không | Toàn bộ lần chạy | globalTimeout — 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
(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
-
Playwright — AssertionsDanh sách đầy đủ matcher tự thử lại và không thử lại, soft assertion, poll, toPass, custom matcherDocs
-
Playwright — TimeoutsPhân cấp timeout và cách cấu hìnhDocs
-
Playwright — Auto-waitingĐiều kiện actionability của từng hành độngDocs
-
Playwright — API: LocatorAssertionsTra cứu tham số của từng matcher trên locatorDocs
✅ 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