Locators 定位器
Locator（定位器）是 Playwright 用來描述「如何在頁面上找到某個元素」的物件，是幾乎所有測試操作的起點。理解 Locator 的設計理念，是寫出穩定測試最重要的第一步。
為什麼不直接用 CSS Selector？
早期的網頁自動化工具（例如 Selenium）多半直接用 CSS 或 XPath 選取元素，一旦改版、樣式重構，測試就容易失效。Playwright 建議優先使用語意化定位器（Role-based Locators），模擬使用者真正「看」網頁的方式，例如「找一個名叫 Submit 的按鈕」，而不是「找 class 叫 .btn-primary-v2 的元素」。這樣測試更貼近使用者行為，也更不容易因為樣式調整而壞掉。
常用 Locator 方法（依優先順序）
// 1. 依角色與可存取名稱（最推薦，貼近使用者與無障礙輔助工具的認知）
page.getByRole('button', { name: 'Submit' });
page.getByRole('heading', { name: 'Welcome' });
// 2. 依表單標籤文字
page.getByLabel('Email address');
// 3. 依 placeholder
page.getByPlaceholder('name@example.com');
// 4. 依可見文字
page.getByText('登入成功');
// 5. 依 data-testid（不隨畫面文字、樣式改變而變動，適合團隊自行約定）
page.getByTestId('login-button');
getByRole 是官方最推薦的方式：它對應瀏覽器的無障礙樹（Accessibility Tree），同時驗證了元素的語意是否正確，等於順便做了基本的無障礙檢查。
過濾與組合定位器
Locator 可以像 CSS Selector 一樣層層縮小範圍：
// 在特定區塊內尋找
page.locator('#products').getByRole('button', { name: '加入購物車' });
// 依文字內容過濾同類型元素
page.getByRole('listitem').filter({ hasText: 'iPhone' });
// 組合多個條件
page.getByRole('row').filter({ has: page.getByText('已完成') });
Locator 是「延遲查找」的
宣告一個 Locator（例如 const button = page.getByRole('button')）並不會立刻查詢 DOM，而是等到呼叫 .click()、.fill() 等操作方法時才真正尋找元素。這代表 Locator 可以重複使用，每次操作都會重新抓取最新的畫面狀態，也是 自動等待機制 能夠運作的基礎。
const addToCart = page.getByRole('button', { name: '加入購物車' });
await addToCart.click();
// 即使畫面重新渲染，重複使用 addToCart 仍會抓到當下最新的元素
await addToCart.click();
處理多個符合的元素
當 Locator 對應到多個元素時，可用索引或轉為陣列處理：
const rows = page.getByRole('row');
await expect(rows).toHaveCount(5);
await rows.nth(0).click(); // 第一個
await rows.first().click(); // 同 nth(0)
await rows.last().click(); // 最後一個
下一步
掌握定位器後，接著看 互動操作與斷言，學習如何用這些定位器模擬操作並驗證結果。