Locators — Tìm phần tử bền vững
Thứ tự ưu tiên locator hướng người dùng, lọc và xâu chuỗi, strict mode, chiến lược test id, và các anti-pattern làm test gãy mỗi lần giao diện đổi.
Chất lượng locator quyết định tuổi thọ của bộ test. Một bộ test đầy XPath và class CSS sinh tự động sẽ gãy mỗi lần frontend refactor — và một bộ test hay báo động giả thì đội sẽ ngừng tin, rồi ngừng chạy. Triết lý của Playwright: tìm phần tử theo cách người dùng tìm nó — qua vai trò và nhãn hiển thị — vì đó là thứ ổn định nhất của một giao diện, đồng thời là thứ bạn thật sự muốn kiểm tra.
🎯 Mục tiêu học tập
- Áp dụng thứ tự ưu tiên: role → label/placeholder/text → test id → CSS (hạn chế) → XPath (tránh)
- Dùng filter, chaining, and/or để định vị chính xác trong danh sách và bảng
- Hiểu strict mode và xử lý lỗi 'resolved to N elements' đúng cách
- Thống nhất chiến lược data-testid với đội frontend
- Nhận diện và sửa các anti-pattern về locator
Thứ tự ưu tiên locator
| Ưu tiên | Locator | Dùng cho | Vì sao |
|---|---|---|---|
| 1 | getByRole('button', { name: 'Lưu' }) | Mọi phần tử tương tác: nút, link, ô nhập, checkbox, tiêu đề, hàng bảng | Khớp cách người dùng và trình đọc màn hình nhận biết; kiểm tra luôn accessibility |
| 2 | getByLabel('Email') | Trường biểu mẫu | Gắn với nhãn hiển thị |
| 2 | getByPlaceholder, getByText, getByAltText, getByTitle | Trường không nhãn; nội dung tĩnh; ảnh | Vẫn là thứ người dùng thấy |
| 3 | getByTestId('order-total') | Phần tử không có vai trò/nhãn ổn định; nội dung động; ứng dụng đa ngôn ngữ | Hợp đồng tường minh với frontend, không đổi theo giao diện |
| 4 | locator('css=...') | Trường hợp đặc biệt, phạm vi hẹp | Gắn với cấu trúc DOM — dễ gãy |
| Tránh | XPath, class sinh tự động (.css-1a2b3c), nth-child dài | — | Gãy khi DOM đổi dù hành vi không đổi |
// Tồi: gắn chặt vào cấu trúc DOM và class sinh tự động
await page.locator('#root > div:nth-child(2) > div.sc-bdVaJa > form > button').click();
await page.locator('//div[@class="modal"]//button[2]').click();
// Tốt: mô tả phần tử như người dùng thấy
await page.getByRole('button', { name: 'Xác nhận thanh toán' }).click();
await page.getByRole('dialog', { name: 'Xoá sản phẩm' }).getByRole('button', { name: 'Xoá' }).click();
name trong getByRole là accessible name (thường là chữ hiển
thị, aria-label, hoặc nhãn liên kết). Mặc định khớp chuỗi con, không phân biệt hoa thường;
thêm exact: true khi "Lưu" bị nhầm với "Lưu và tiếp tục", hoặc dùng regex.
Nếu
một nút không thể tìm bằng getByRole('button') vì nó là <div onclick>, thì
người dùng trình đọc màn hình cũng không dùng được nó. Hãy báo lỗi accessibility thay vì lặng lẽ chuyển
sang CSS selector.
Lọc và xâu chuỗi: làm việc với danh sách và bảng
// Tìm đúng hàng theo nội dung, rồi thao tác bên trong hàng đó
const row = page.getByRole('row').filter({ hasText: 'DH-104233' });
await expect(row.getByRole('cell', { name: 'Đã thanh toán' })).toBeVisible();
await row.getByRole('button', { name: 'Xem chi tiết' }).click();
// Lọc theo phần tử con (has) và phủ định (hasNot, hasNotText)
const card = page.getByRole('listitem').filter({
has: page.getByRole('heading', { name: 'Bình giữ nhiệt 500ml' }),
});
await card.getByRole('button', { name: 'Thêm vào giỏ' }).click();
const inStock = page.getByRole('listitem').filter({ hasNotText: 'Hết hàng' });
await expect(inStock).toHaveCount(8);
// Kết hợp điều kiện
const primarySubmit = page.getByRole('button', { name: 'Gửi' }).and(page.locator('.primary'));
const dialogOrToast = page.getByRole('dialog').or(page.getByRole('alert'));
await expect(dialogOrToast.first()).toBeVisible();
// Thu hẹp phạm vi: chaining từ một vùng
const sidebar = page.getByRole('navigation', { name: 'Danh mục' });
await sidebar.getByRole('link', { name: 'Đồ gia dụng' }).click();
Nguyên tắc: định vị vùng chứa trước bằng nội dung có nghĩa, rồi tìm bên trong. Tránh
.nth(3) và .first() để "chọn đại một cái" — chúng phụ thuộc thứ tự, mà thứ tự
thay đổi theo dữ liệu. Chỉ dùng khi thứ tự chính là điều bạn đang kiểm tra (kết quả đầu tiên sau
khi sắp xếp).
Strict mode: lỗi là người bạn
Khi một locator dùng cho hành động khớp nhiều hơn một phần tử, Playwright ném lỗi thay vì lặng lẽ chọn cái đầu tiên:
Error: locator.click: Error: strict mode violation:
getByRole('button', { name: 'Xoá' }) resolved to 3 elements
Đây là tính năng: nó chặn lớp lỗi "test bấm nhầm nút nhưng tình cờ vẫn pass". Cách sửa theo thứ tự nên thử:
- Thu hẹp phạm vi bằng vùng chứa có nghĩa (hàng, dialog, section).
- Lọc bằng
filter({ hasText }). - Tên chính xác hơn:
exact: true. - Test id nếu thật sự không có gì phân biệt.
.first()/.nth()là lựa chọn cuối, kèm chú thích lý do.
Các phương thức đếm và lặp (count(), all(), toHaveCount()) không
áp dụng strict. Lưu ý locator.all() không tự chờ — nếu danh sách đang tải,
nó trả về mảng rỗng hoặc thiếu. Chờ danh sách ổn định trước:
await expect(page.getByRole('listitem')).toHaveCount(12); // tự chờ đến khi đủ 12
for (const item of await page.getByRole('listitem').all()) {
await expect(item.getByRole('img')).toBeVisible();
}
Chiến lược data-testid
Test id là hợp đồng giữa QA và frontend. Làm đúng thì bền; làm bừa thì thành một lớp rác nữa phải bảo trì.
| Nên | Không nên |
|---|---|
| Dùng khi role/label không đủ: giá trị động (tổng tiền), vùng chứa (thẻ sản phẩm), icon không nhãn | Gắn test id cho mọi phần tử rồi bỏ hẳn getByRole |
Đặt tên theo ý nghĩa: order-total, cart-item | Theo vị trí hay kiểu dáng: div-3, blue-button |
Quy ước thống nhất: kebab-case, dạng vùng-phần-tử | Mỗi người một kiểu |
| Với danh sách: test id cho loại phần tử, lọc bằng nội dung | Nhúng ID động vào test id rồi phải biết trước ID |
| Ghi vào tiêu chí hoàn thành của ticket frontend | QA tự thêm sau, lệch pha với code |
// playwright.config.ts — nếu frontend dùng thuộc tính khác
use: { testIdAttribute: 'data-qa' }
// Danh sách: một test id cho loại, lọc theo nội dung
const item = page.getByTestId('cart-item').filter({ hasText: 'Bình giữ nhiệt' });
await item.getByRole('button', { name: 'Tăng số lượng' }).click();
await expect(item.getByTestId('line-total')).toHaveText('378.000 ₫');
Ứng dụng đa ngôn ngữ: nếu test phải chạy trên nhiều ngôn ngữ, locator theo chữ hiển thị sẽ gãy. Lựa chọn: cố định một ngôn ngữ cho E2E (thường là tốt nhất), hoặc dùng test id cho phần tử tương tác và chỉ kiểm tra bản dịch ở một bộ test riêng.
Tình huống đặc biệt
| Tình huống | Cách xử lý |
|---|---|
| iframe | page.frameLocator('iframe[title="Thanh toán"]').getByLabel('Số thẻ') — tự chờ iframe tải |
| Shadow DOM | Các locator của Playwright tự xuyên qua shadow root mở; không cần làm gì thêm (XPath thì không xuyên được) |
Dropdown tuỳ biến (không phải <select>) | Bấm mở, rồi getByRole('option', { name }). Với <select> thật: selectOption({ label }) |
| Phần tử chỉ hiện khi hover | await row.hover() rồi bấm nút bên trong |
| Phần tử ngoài màn hình | Hành động tự cuộn tới; không cần scrollIntoView thủ công |
| Danh sách ảo hoá (chỉ render phần đang thấy) | Dùng tìm kiếm/bộ lọc của ứng dụng để đưa mục cần vào tầm nhìn, hoặc cuộn và chờ |
| Popup bất chợt (banner cookie, khảo sát) | page.addLocatorHandler(locator, handler) — tự đóng mỗi khi nó che thao tác |
| Tab/cửa sổ mới | const popup = page.waitForEvent('popup'); await link.click(); const newPage = await popup; |
Công cụ tìm locator: nút Pick locator trong UI Mode/VS Code, hoặc
npx playwright codegen. Chúng đề xuất locator theo đúng thứ tự ưu tiên; hãy xem đề xuất như
điểm khởi đầu, rồi tự thu hẹp phạm vi cho có nghĩa.
🏋️ Bài tập thực hành
(1) Lấy 10 test có sẵn (hoặc dùng codegen ghi 5 luồng) và phân loại mọi locator theo bảng ưu tiên:
đếm bao nhiêu phần trăm thuộc mức 1-2, mức 3, mức 4, và "tránh". (2) Viết lại để ít nhất 80% thuộc mức 1-2.
(3) Với mỗi phần tử không tìm được bằng role, ghi lại thành một lỗi accessibility và đề xuất sửa cho frontend.
(4) Viết tài liệu một trang "Quy ước test id" cho đội: khi nào thêm, đặt tên thế nào, ai chịu trách nhiệm.
(5) Phép thử độ bền: nhờ một đồng nghiệp frontend đổi cấu trúc DOM của một trang (bọc thêm div, đổi class,
đổi thứ tự) mà không đổi hành vi — bộ test cũ gãy bao nhiêu, bộ mới gãy bao nhiêu? (6) Viết test cho một bảng
dữ liệu: tìm đúng hàng theo mã, kiểm tra ba ô, bấm một hành động trong hàng — không dùng nth.
📚 Tài nguyên học tập
-
Playwright — LocatorsToàn bộ API locator, lọc, xâu chuỗi, strictnessDocs
-
Playwright — Best PracticesKhuyến nghị chính thức về locator hướng người dùngDocs
-
Testing Library — Which query should I use?Nguồn gốc triết lý ưu tiên truy vấn theo cách người dùng tìmDocs
-
MDN — ARIA rolesTra cứu vai trò ARIA để dùng getByRole chính xácDocs
-
Playwright — Other locatorsCSS, XPath và các trường hợp nên/không nên dùngDocs
✅ Tự đánh giá hoàn thành
- Mặc định dùng getByRole/getByLabel; chỉ xuống test id khi có lý do
- Định vị trong danh sách/bảng bằng filter và chaining, không dùng nth tuỳ tiện
- Sửa lỗi strict mode bằng thu hẹp phạm vi thay vì .first()
- Đội có quy ước test id thành văn
- Xử lý được iframe, dropdown tuỳ biến, popup bất chợt, và tab mới