跳轉到

2.1 定位器基礎：getBy 系列用法#

定位器（Locator）是什麼？#

要操作頁面上的元素，先要「定位」到它。Locator 是代表「找到元素的計畫」，元素遲到也不會報錯（會自動等待，見 3.3）。

const button = page.getByRole("button", { name: "送出" });

首選：getBy 系列（依語意定位）#

Playwright 官方建議依「使用者怎麼看這個元素」來定位：

// 依角色定位（按鈕、連結、標題...）——最推薦
page.getByRole("button", { name: "送出" });
page.getByRole("link", { name: "登入" });
page.getByRole("heading", { name: "歡迎" });

// 依標籤文字定位（表單欄位最推薦）
page.getByLabel("電子郵件");
page.getByLabel("密碼");

// 依 placeholder 定位
page.getByPlaceholder("請輸入搜尋關鍵字");

// 依文字內容定位
page.getByText("購物車是空的");

// 依 alt / title 屬性定位
page.getByAltText("公司標誌");
page.getByTitle("關閉");

為什麼 getByRole 最推薦？#

  1. 最接近使用者的感知：視障使用者的螢幕閱讀器就是靠 role 找元素的
  2. 強迫你寫出無障礙（a11y）良好的頁面：測試找不到元素，代表語意有問題
  3. 最穩定：不依賴 class 名稱或 DOM 結構

鏈式縮小範圍#

頁面上有多個相似元素時，先縮小範圍再定位：

// 在「登入表單」這個區塊內找送出按鈕
page.getByRole("form", { name: "登入" })
    .getByRole("button", { name: "送出" });

// 清單中的特定項目
page.getByRole("listitem").filter({ hasText: "蘋果" });

舊式定位（能不用就不用）#

page.locator("#submit");           // 依 id——穩定，但 id 常改
page.locator(".btn-primary");      // 依 class——❌ 樣式類名常改，測試跟著壞
page.locator("div > button");      // 依 CSS 結構——❌ DOM 一改就壞

鐵律：優先 getByRole / getByLabel，其次 getByText，最後才考慮 CSS。依 class 和 DOM 結構定位的測試，改一次版面就壞一次。