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

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.

LocatorsgetByRoleStrictnessTest ID
📌 Vì sao module này quan trọng

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ênLocatorDùng choVì sao
1getByRole('button', { name: 'Lưu' })Mọi phần tử tương tác: nút, link, ô nhập, checkbox, tiêu đề, hàng bảngKhớ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
2getByLabel('Email')Trường biểu mẫuGắn với nhãn hiển thị
2getByPlaceholder, getByText, getByAltText, getByTitleTrường không nhãn; nội dung tĩnh; ảnhVẫn là thứ người dùng thấy
3getByTestId('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
4locator('css=...')Trường hợp đặc biệt, phạm vi hẹpGắn với cấu trúc DOM — dễ gãy
TránhXPath, 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.

💡 Không tìm được bằng role? Đó là một phát hiện

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ử:

  1. Thu hẹp phạm vi bằng vùng chứa có nghĩa (hàng, dialog, section).
  2. Lọc bằng filter({ hasText }).
  3. Tên chính xác hơn: exact: true.
  4. Test id nếu thật sự không có gì phân biệt.
  5. .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ênKhô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ãnGắn test id cho mọi phần tử rồi bỏ hẳn getByRole
Đặt tên theo ý nghĩa: order-total, cart-itemTheo 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 dungNhú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 frontendQA 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ốngCách xử lý
iframepage.frameLocator('iframe[title="Thanh toán"]').getByLabel('Số thẻ') — tự chờ iframe tải
Shadow DOMCá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 hoverawait row.hover() rồi bấm nút bên trong
Phần tử ngoài màn hìnhHà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ớiconst 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

Tái cấu trúc locator và đo độ bền

(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

✅ 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