定位器
簡介
Locator 是 Playwright 自動等待和重試功能的核心部分。簡而言之，locators 代表了一種在任何時刻在頁面上找到元素的方法。
快速指南
這些是推薦的內建定位器。
- Page.getByRole() 以明確和隱含的可及性屬性來定位。
- Page.getByText() 以文本內容來定 位。
- Page.getByLabel() 以關聯標籤的文本來定位表單控制項。
- Page.getByPlaceholder() 以佔位符來定位輸入框。
- Page.getByAltText() 以文本替代來定位元素，通常是圖像。
- Page.getByTitle() 以標題屬性來定位元素。
- Page.getByTestId() 以
data-testid屬性來定位元素（其他屬性可以配置）。
page.getByLabel("User Name").fill("John");
page.getByLabel("Password").fill("secret-password");
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
.click();
assertThat(page.getByText("Welcome, John!")).isVisible();
定位元素
Playwright 內建多個定位器。為了讓測試更具韌性，我們建議優先考慮面向使用者的屬性和明確的合約，例如 Page.getByRole()。
例如，考慮以下的 DOM 結構。
<button>Sign in</button>
找到角色為 button 且名稱為 "Sign in" 的元素。
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
.click();
使用 程式碼產生器 來生成定位器，然後根據需要進行編輯。
每次使用定位器執行動作時，會在頁面中定位最新的 DOM 元素。在下面的程式碼片段中，基礎的 DOM 元素將被定位兩次，每次動作前各一次。這意味著如果在呼叫之間由於重新渲染而導致 DOM 發生變化，將使用與定位器對應的新元素。
Locator locator = page.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName("Sign in"))
locator.hover();
locator.click();
請注意，所有建立定位器的方法，例如 Page.getByLabel()，也可在 Locator 和 FrameLocator 類別上使用，因此您可以鏈接它們並逐步縮小您的定位器範圍。
Locator locator = page
.frameLocator("#my-frame")
.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"));
locator.click();
根據角色定位
Page.getByRole() 定位器反映了使用者和輔助技術如何感知頁面，例如某個元素是按鈕還是複選框。當按角色定位時，你通常應該傳遞可訪問的名稱，以便定位器能夠精確定位到具體的元素。
例如，考慮以下的 DOM 結構。
註冊
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
您可以通過其隱含角色定位每個元素:
assertThat(page
.getByRole(AriaRole.HEADING,
new Page.GetByRoleOptions().setName("Sign up")))
.isVisible();
page.getByRole(AriaRole.CHECKBOX,
new Page.GetByRoleOptions().setName("Subscribe"))
.check();
page.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName(
Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
.click();
角色定位器包括按鈕、複選框、標題、連結、清 單、表格等，並遵循 W3C 的 ARIA 角色、ARIA 屬性和可訪問名稱規範。請注意，許多 html 元素如 <button> 具有隱式定義的角色，這些角色被角色定位器識別。
請注意，角色定位器不會取代可及性審計和符合性測試，而是提供有關 ARIA 指南的早期反饋。
我們建議優先使用角色定位器來定位元素，因為這是最接近用戶和輔助技術感知頁面的方式。
Locate by label
大多數表單控制項通常都有專用標籤，可以方便地與表單互動。在這種情況下，你可以使用 Page.getByLabel() 根據其關聯標籤來定位控制項。
例如，考慮以下的 DOM 結構。
<label>Password <input type="password" /></label>
您可以在找到標籤文字後填寫輸入:
page.getByLabel("Password").fill("secret");
當定位表單欄位時，使用此定位器。
Locate by placeholder
輸入可能有一個 placeholder 屬性來提示使用者應該輸入什麼值。你可以使用 Page.getByPlaceholder() 來定位這樣的輸入。
例如，考慮以下的 DOM 結構。
<input type="email" placeholder="name@example.com" />
您可以在找到佔位符文字後填寫輸入:
page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
當定位沒有標籤但有佔位符文本的表單元素時，使用此定位器。
根據文字定位
找到包含特定文字的元素。使用 Page.getByText() 時，你可以透過子字串、精確字串或正則表達式來匹配。
例如，考慮以下的 DOM 結構。
<span>Welcome, John</span>
您可以通過其包含的文本來定位該元素:
assertThat(page.getByText("Welcome, John")).isVisible();
設置精確匹配:
assertThat(page
.getByText("Welcome, John", new Page.GetByTextOptions().setExact(true)))
.isVisible();
與正則表達式匹配:
assertThat(page
.getByText(Pattern.compile("welcome, john$", Pattern.CASE_INSENSITIVE)))
.isVisible();
匹配文本時總是會正規化空白，即使是精確匹配。例如，它會將多個空格變成一個，將換行符變成空格，並忽略前後的空白。
我們建議使用文字定位器來查找非互動元素，如 div、span、p 等。對於互動元素，如 button、a、input 等，請使用角色定位器。
你也可以 filter by text 這在嘗試在列表中找到特定項目時很有用。
Locate by alt text
所有圖片應該有一個 alt 屬性來描述圖片。你可以使用 Page.getByAltText() 根據文字替代項來定位圖片。
例如，考慮以下的 DOM 結構。
<img alt="playwright logo" src="/img/playwright-logo.svg" width="100" />
您可以在找到文字替代後點擊圖片:
page.getByAltText("playwright logo").click();
當你的元素支援 alt 文字時，例如 img 和 area 元素，請使用此定位器。
根據標題定位
找到具有匹配標題屬性的元素，使用 Page.getByTitle()。
例如，考慮以下的 DOM 結構。
<span title='Issues count'>25 issues</span>
您可以在通過標題文字定位後檢查問題數量:
assertThat(page.getByTitle("Issues count")).hasText("25 issues");
當你的元素具有 title 屬性時，使用此定位器。
依據測試 ID 定位
測試 id 是最具彈性的測試方式，因為 即使您的文字或屬性的角色發生變化，測試仍然會通過。QA 和開發人員應該定義明確的測試 id 並使用 Page.getByTestId() 進行查詢。然而，通過測試 id 進行測試並不是面向使用者的。如果角色或文字值對您很重要，請考慮使用面向使用者的定位器，例如 role 和 text locators。
例如，考慮以下的 DOM 結構。
<button data-testid="directions">Itinéraire</button>
你可以通過測試 ID 定位該元素:
page.getByTestId("directions").click();
設定自訂測試 id 屬性
預設情況下，Page.getByTestId() 將根據 data-testid 屬性定位元素，但您可以在測試配置中進行配置，或通過呼叫 Selectors.setTestIdAttribute() 來配置。
將測試 ID 設定為使用自訂資料屬性進行測試。
playwright.selectors().setTestIdAttribute("data-pw");
在你的 html 中，你現在可以使用 data-pw 作為你的測試 id，而不是預設的 data-testid。
<button data-pw="directions">Itinéraire</button>
然後像平常一樣定位該元素:
page.getByTestId("directions").click();
使用 CSS 或 XPath 定位
如果你絕對必須使用 CSS 或 XPath 定位器，你可以使用 Page.locator() 建立一個定位器，該定位器使用選擇器來描述如何在頁面中找到元素。Playwright 支援 CSS 和 XPath 選擇器，如果你省略了 css= 或 xpath= 前綴，它會自動檢測它們。
page.locator("css=button").click();
page.locator("xpath=//button").click();
page.locator("button").click();
page.locator("//button").click();
XPath 和 CSS 選擇器可以與 DOM 結構 或實現綁定。當 DOM 結構改變時，這些選擇器可能會失效。下面的長 CSS 或 XPath 鏈是一個導致測試不穩定的不良實踐範例:
page.locator(
"#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input"
).click();
page.locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").click();
在 Shadow DOM 中定位
所有在 Playwright 中的定位器 預設 都適用於 Shadow DOM 中的元素。例外情況如下:
- 使用 XPath 定位不會穿透 shadow roots。
- Closed-mode shadow roots 不受支持。
考慮以下帶有自定義網頁元件的範例:
<x-details role=button aria-expanded=true aria-controls=inner-details>
<div>Title</div>
#shadow-root
<div id=inner-details>Details</div>
</x-details>
你可以像根本沒有 shadow root 一樣定位。
要點擊 <div>Details</div>:
page.getByText("Details").click();
<x-details role=button aria-expanded=true aria-controls=inner-details>
<div>Title</div>
#shadow-root
<div id=inner-details>Details</div>
</x-details>
要點擊 <x-details>:
page.locator("x-details", new Page.LocatorOptions().setHasText("Details"))
.click();
<x-details role=button aria-expanded=true aria-controls=inner-details>
<div>Title</div>
#shadow-root
<div id=inner-details>Details</div>
</x-details>
為了確保 <x-details> 包含文字 "Details":
assertThat(page.locator("x-details")).containsText("Details");
過濾定位器
考慮以下 DOM 結構，我們想要點擊第二個產品卡的購買按鈕。我們有幾個選項來過濾定位器以獲取正確的定位器。
產品 1
產品 2
<ul>
<li>
<h3>Product 1</h3>
<button>Add to cart</button>
</li>
<li>
<h3>Product 2</h3>
<button>Add to cart</button>
</li>
</ul>
以文字篩選
定位器可以通過 Locator.filter() 方法根據文本過濾。它將在元素內部的某個地方（可能在後代元素中）搜索特定字元串，不區分大小寫。你也可以傳遞正則表達式。
page.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions().setHasText("Product 2"))
.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName("Add to cart"))
.click();
使用正規表示式:
page.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions()
.setHasText(Pattern.compile("Product 2")))
.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName("Add to cart"))
.click();
篩選沒有文字的
或者，篩選 不包含 文字:
// 5 in-stock items
assertThat(page.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions().setHasNotText("Out of stock")))
.hasCount(5);
根據子項/後代篩選
定位器支持一個選項，只選擇具有或不具有匹配另一個定位器的後代元素。因此，您可以通過任何其他定位器進行篩選，例如 Locator.getByRole、Locator.getByTestId、Locator.getByText 等等。
產品 1
產品 2
<ul>
<li>
<h3>Product 1</h3>
<button>Add to cart</button>
</li>
<li>
<h3>Product 2</h3>
<button>Add to cart</button>
</li>
</ul>
page.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions()
.setHas(page.GetByRole(AriaRole.HEADING, new Page.GetByRoleOptions()
.setName("Product 2"))))
.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName("Add to cart"))
.click()
我們也可以斷言產品卡片以確保只有一個:
assertThat(page
.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions()
.setHas(page.GetByRole(AriaRole.HEADING,
new Page.GetByRoleOptions().setName("Product 2"))))
.hasCount(1);
篩選定位器必須是相對於原始定位器，並從原始定位器匹配開始查詢，而不是從文件根目錄開始。因此，以下將無法運作，因為篩選定位器從 <ul> 列表元素開始匹配，而該元素位於原始定位器匹配的 <li> 列表項之外：
// ✖ WRONG
assertThat(page
.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions()
.setHas(page.GetByRole(AriaRole.LIST)
.GetByRole(AriaRole.HEADING,
new Page.GetByRoleOptions().setName("Product 2"))))
.hasCount(1);
篩選沒有子元素/後代的元素
我們也可以過濾掉沒有匹配元素的內容。
assertThat(page
.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions().setHasNot(page.getByText("Product 2")))
.hasCount(1);
請注意，內部定位器是從外部開始匹配的，而不是從文件根目錄開始。
定位器運算子
在定位器內匹配
您可以鏈接建立定位器的方法，如 Page.getByText() 或 Locator.getByRole()，以縮小搜尋頁面的特定部分。
在這個範例中，我們首先透過定位其角色為 listitem 來建立一個名為 product 的定位器。然後我們透過文字進行篩選。我們可以再次使用 product 定位器來透過角色取得按鈕並點擊它，然後使用斷言來確保只有一個產品的文字為 "Product 2"。
Locator product = page
.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions().setHasText("Product 2"));
product
.getByRole(AriaRole.BUTTON,
new Locator.GetByRoleOptions().setName("Add to cart"))
.click();
您也可以將兩個定位器連接在一起，例如在特定對話框中找到“Save”按鈕:
Locator saveButton = page.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName("Save"));
// ...
Locator dialog = page.getByTestId("settings-dialog");
dialog.locator(saveButton).click();
同時匹配兩個定位器
方法 Locator.and() 通過匹配額外的定位器來縮小現有定位器的範圍。例如，你可以結合 Page.getByRole() 和 Page.getByTitle() 來同時按角色和標題進行匹配。
Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));
匹配兩個替代定位器之一
如果你想要定位其中一個或多個元素，並且你不知道會是哪一個，使用 Locator.or() 來建立一個匹配所有替代方案的定位器。
例如，考慮一個情境，你想點擊 "New email" 按鈕，但有時會出現一個安全設定對話框。在這種情況下，你可以等待 "New email" 按鈕或對話框並據此行動。
如果螢幕上同時出現 "New email" 按鈕和安全對話框，"or" 定位器將匹配它們兩者，可能會拋出 "strict mode violation" 錯誤。在這種情況下，你可以使用 Locator.first() 來只匹配其中一個。
Locator newEmail = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("New"));
Locator dialog = page.getByText("Confirm security settings");
assertThat(newEmail.or(dialog).first()).isVisible();
if (dialog.isVisible())
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Dismiss")).click();
newEmail.click();
僅匹配可見元素
通常最好找到 更可靠的方法來唯一識別元素，而不是檢查可見性。
考慮一個有兩個按鈕的頁面，第一個是不可見的，第二個是可見的。
<button style='display: none'>Invisible</button>
<button>Visible</button>
-
這將會找到兩個按鈕並拋出一個嚴格性違規錯誤:
page.locator("button").click(); -
這將只會找到第二個按鈕，因為它是可見的，然後點擊它。
page.locator("button").locator("visible=true").click();
列表
計算清單中的項目數量
你可以斷言定位器以計算清單中的項目。
例如，考慮以下的 DOM 結構:
- 蘋果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
使用 count 斷言來確保清單有 3 個項目。
assertThat(page.getByRole(AriaRole.LISTITEM).hasCount(3);
斷言清單中的所有文字
你可以斷言定位器以找到清單中的所有文字。
例如，考慮以下的 DOM 結構:
- 蘋果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
使用 assertThat(locator).hasText() 確保清單中有 "apple"、"banana" 和 "orange"。
assertThat(page
.getByRole(AriaRole.LISTITEM))
.hasText(new String[] { "apple", "banana", "orange" });
取得特定項目
有很多方法可以在清單中獲取特定項目。
取得文字
使用 Page.getByText() 方法根據其文本內容在列表中定位一個元素，然後點擊它。
例如，考慮以下的 DOM 結構:
- 蘋果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
根據其文本內容找到一個項目並點擊它。
page.getByText("orange").click();
根據文字篩選
使用 Locator.filter() 來定位清單中的特定項目。
例如，考慮以下的 DOM 結構:
- 蘋果
- 香蕉
- 橙子
<ul>
<li>apple</li>
<li>banana</li>
<li>orange</li>
</ul>
找到角色為 "listitem" 的項目，然後按 "orange" 的文字過濾，然後點擊它。
page.getByRole(AriaRole.LISTITEM)
.filter(new Locator.FilterOptions().setHasText("orange"))
.click();
Get by test id
使用 Page.getByTestId() 方法來定位列表中的元素。如果你還沒有測試 ID，你可能需要修改 HTML 並添加測試 ID。
例如，考慮以下的 DOM 結構:
- 蘋果
- 香蕉
- 橙子
<ul>
<li data-testid='apple'>apple</li>
<li data-testid='banana'>banana</li>
<li data-testid='orange'>orange</li>
</ul>
找到測試 ID 為 "orange" 的項目，然後點擊它。
page.getByTestId("orange").click();
取得第 n 個物件
如果你有一個相同元素的列表，且區分它們的唯一方法是順序，你可以從列表中選擇一個特定元素，使用 Locator.first()、Locator.last() 或 Locator.nth()。
Locator banana = page.getByRole(AriaRole.LISTITEM).nth(1);
然而，請謹慎使用此方法。通常情況下，頁面可能會變更，而定位器將指向與您預期完全不同的元素。相反，請嘗試提出一個獨特的定位器，以通過嚴格標準。
鏈接過濾器
當你有具有各種相似性的元素時，你可以使用 Locator.filter() 方法來選擇正確的元素。你也可以串聯多個篩選器來縮小選擇範圍。
例如，考慮以下的 DOM 結構:
- John
- Mary
- John
- Mary
<ul>
<li>
<div>John</div>
<div><button>Say hello</button></div>
</li>
<li>
<div>Mary</div>
<div><button>Say hello</button></div>
</li>
<li>
<div>John</div>
<div><button>Say goodbye</button></div>
</li>
<li>
<div>Mary</div>
<div><button>Say goodbye</button></div>
</li>
</ul>
要截取包含 "Mary" 和 "Say goodbye" 的行的螢幕截圖:
Locator rowLocator = page.getByRole(AriaRole.LISTITEM);
rowLocator
.filter(new Locator.FilterOptions().setHasText("Mary"))
.filter(new Locator.FilterOptions()
.setHas(page.getByRole(
AriaRole.BUTTON,
new Page.GetByRoleOptions().setName("Say goodbye"))))
.screenshot(new Page.ScreenshotOptions().setPath("screenshot.png"));
你現在應該在你的專案根目錄中有一個 "screenshot.png" 文件。
罕見的使用案例
對清單中的每個元素做些事情
迭代元素:
for (Locator row : page.getByRole(AriaRole.LISTITEM).all())
System.out.println(row.textContent());
使用常規 for 迴圈進行迭代:
Locator rows = page.getByRole(AriaRole.LISTITEM);
int count = rows.count();
for (int i = 0; i < count; ++i)
System.out.println(rows.nth(i).textContent());
在頁面中評估
程式碼內的 Locator.evaluateAll() 執行在頁面中，你可以在那裡呼叫任意 DOM apis。
Locator rows = page.getByRole(AriaRole.LISTITEM);
Object texts = rows.evaluateAll(
"list => list.map(element => element.textContent)");
嚴格性
定位器是嚴格的。這意味著所有對定位器的操作，如果匹配多個目標 DOM 元素，將拋出異常。例如，如果 DOM 中有多個按鈕，則以下呼叫將拋出異常:
如果超過一個則拋出錯誤
page.getByRole(AriaRole.BUTTON).click();
另一方面，Playwright 理解當你執行多元素操作時，因此當定位器解析為多個元素時，以下呼叫可以完美運作。
多個元素運作良好
page.getByRole(AriaRole.BUTTON).count();
您可以通過告訴 Playwright 當多個元素匹配時使用哪個元素來明確選擇退出嚴格性檢查，通過 Locator.first()、Locator.last() 和 Locator.nth()。這些方法不推薦，因為當您的頁面更改時，Playwright 可能會點擊您未打算點擊的元素。相反，請遵循上述最佳實踐來建立唯一識別目標元素的定位器。
更多定位器
不常用的定位器請參閱其他定位器指南。