定位器

簡介

定位器是 Playwright 自動等待和重試能力的核心組件。簡而言之，定位器代表一種隨時在頁面上尋找元素的方法。

快速指南

以下是建議的內建定位器。

Page.GetByRole()：依據明確和隱含的協助工具屬性來定位。
Page.GetByText()：依據文字內容來定位。
Page.GetByLabel()：依據相關聯標籤的文字來定位表單控制項。
Page.GetByPlaceholder()：依據佔位符來定位輸入框。
Page.GetByAltText()：依據替代文字來定位元素，通常是圖片。
Page.GetByTitle()：依據 title 屬性來定位元素。
Page.GetByTestId()：依據其 data-testid 屬性（可以設定其他屬性）來定位元素。

await Page.GetByLabel("User Name").FillAsync("John");

await Page.GetByLabel("Password").FillAsync("secret-password");

await Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" }).ClickAsync();

await Expect(Page.GetByText("Welcome, John!")).ToBeVisibleAsync();

定位元素

Playwright 內建多種定位器。為了使測試具有彈性，我們建議優先使用面向使用者的屬性和明確的合約，例如 Page.GetByRole()。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

<button>Sign in</button>

依據角色 button 和名稱 "登入" 來定位元素。

await Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" }).ClickAsync();

注意

使用程式碼產生器來產生定位器，然後根據您的需求進行編輯。

每次定位器用於動作時，都會在頁面中定位最新的 DOM 元素。在下面的程式碼片段中，底層 DOM 元素將被定位兩次，每次動作之前一次。這表示如果 DOM 在呼叫之間由於重新渲染而發生變更，將會使用對應於定位器的新元素。

var locator = Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" });

await locator.HoverAsync();
await locator.ClickAsync();

請注意，所有建立定位器的方法，例如 Page.GetByLabel()，在定位器和 FrameLocator 類別上也可用，因此您可以將它們串聯起來並反覆縮小您的定位器範圍。

var locator = Page
    .FrameLocator("#my-frame")
    .GetByRole(AriaRole.Button, new() { Name = "Sign in" });

await locator.ClickAsync();

依角色定位

Page.GetByRole() 定位器反映使用者和輔助技術如何感知頁面，例如，某個元素是按鈕還是核取方塊。依角色定位時，通常也應該傳遞可存取名稱，以便定位器精確地指向該元素。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

註冊

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

您可以依據每個元素的隱含角色來定位

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
    .ToBeVisibleAsync();

await Page
    .GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
    .CheckAsync();

await Page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

角色定位器包含按鈕、核取方塊、標題、連結、清單、表格等等，並遵循 W3C 規範，適用於 ARIA 角色、ARIA 屬性和可存取名稱。請注意，許多 html 元素（例如 <button>）都有一個隱含定義的角色，該角色可被角色定位器識別。

請注意，角色定位器不能取代協助工具稽核和符合性測試，而是提供有關 ARIA 指南的早期回饋。

何時使用角色定位器

我們建議優先使用角色定位器來定位元素，因為這是最接近使用者和輔助技術感知頁面的方式。

依標籤定位

大多數表單控制項通常都有專用標籤，可以方便地用於與表單互動。在這種情況下，您可以使用 Page.GetByLabel() 依據其相關聯的標籤來定位控制項。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

密碼

<label>Password <input type="password" /></label>

您可以在依據標籤文字定位輸入框後填寫內容

await Page.GetByLabel("Password").FillAsync("secret");

何時使用標籤定位器

當定位表單欄位時，請使用此定位器。

依佔位符定位

輸入框可能具有佔位符屬性，以提示使用者應輸入的值。您可以使用 Page.GetByPlaceholder() 來定位此類輸入框。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

<input type="email" placeholder="name@example.com" />

您可以在依據佔位符文字定位輸入框後填寫內容

await Page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

何時使用佔位符定位器

當定位沒有標籤但有佔位符文字的表單元素時，請使用此定位器。

依文字定位

依據元素包含的文字尋找元素。使用 Page.GetByText() 時，您可以比對子字串、確切字串或規則運算式。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

歡迎，John

<span>Welcome, John</span>

您可以依據元素包含的文字來定位元素

await Expect(Page.GetByText("Welcome, John")).ToBeVisibleAsync();

設定精確比對

await Expect(Page
    .GetByText("Welcome, John", new() { Exact = true }))
    .ToBeVisibleAsync();

使用規則運算式比對

await Expect(Page
    .GetByText(new Regex("welcome, john", RegexOptions.IgnoreCase)))
    .ToBeVisibleAsync();

注意

依文字比對始終會正規化空格，即使是精確比對也是如此。例如，它會將多個空格變成一個，將換行符變成空格，並忽略開頭和結尾的空格。

何時使用文字定位器

我們建議使用文字定位器來尋找非互動式元素，例如 div、span、p 等。對於互動式元素，例如 button、a、input 等，請使用角色定位器。

您也可以依文字篩選，這在嘗試尋找清單中的特定項目時非常有用。

依替代文字定位

所有圖片都應具有描述圖片的 alt 屬性。您可以使用 Page.GetByAltText() 依據替代文字來定位圖片。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

<img alt="playwright logo" src="/img/playwright-logo.svg" width="100" />

您可以在依據替代文字定位圖片後點擊圖片

await Page.GetByAltText("playwright logo").ClickAsync();

何時使用 alt 定位器

當您的元素支援替代文字（例如 img 和 area 元素）時，請使用此定位器。

依標題定位

使用 Page.GetByTitle() 定位具有相符 title 屬性的元素。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

25 個問題

<span title='Issues count'>25 issues</span>

您可以在依據標題文字定位問題計數後檢查問題計數

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

何時使用標題定位器

當您的元素具有 title 屬性時，請使用此定位器。

依測試 ID 定位

依測試 ID 進行測試是最具彈性的測試方式，因為即使您的文字或屬性的角色發生變更，測試仍然會通過。QA 和開發人員應定義明確的測試 ID，並使用 Page.GetByTestId() 查詢它們。然而，依測試 ID 進行測試並非面向使用者。如果角色或文字值對您很重要，請考慮使用面向使用者的定位器，例如角色和文字定位器。

例如，考慮以下 DOM 結構。

https://127.0.0.1:3000

<button data-testid="directions">Itinéraire</button>

您可以依據元素的測試 ID 來定位元素

await Page.GetByTestId("directions").ClickAsync();

何時使用 testid 定位器

當您選擇使用測試 ID 方法，或者當您無法依據角色或文字定位時，也可以使用測試 ID。

設定自訂測試 ID 屬性

預設情況下，Page.GetByTestId() 將依據 data-testid 屬性定位元素，但您可以在測試設定中或透過呼叫 Selectors.SetTestIdAttribute() 來設定它。

設定測試 ID 以用於您的測試的自訂資料屬性。

playwright.Selectors.SetTestIdAttribute("data-pw");

在您的 html 中，您現在可以使用 data-pw 作為您的測試 ID，而不是預設的 data-testid。

https://127.0.0.1:3000

<button data-pw="directions">Itinéraire</button>

然後像平常一樣定位元素

await Page.GetByTestId("directions").ClickAsync();

依 CSS 或 XPath 定位

如果您絕對必須使用 CSS 或 XPath 定位器，則可以使用 Page.Locator() 來建立一個定位器，該定位器採用一個選取器，用於描述如何在頁面中尋找元素。Playwright 支援 CSS 和 XPath 選取器，如果您省略 css= 或 xpath= 前綴，它會自動偵測它們。

await Page.Locator("css=button").ClickAsync();
await Page.Locator("xpath=//button").ClickAsync();

await Page.Locator("button").ClickAsync();
await Page.Locator("//button").ClickAsync();

XPath 和 CSS 選取器可能與 DOM 結構或實作相關聯。當 DOM 結構變更時，這些選取器可能會損壞。以下長 CSS 或 XPath 鏈是導致不穩定測試的不良做法範例

await Page.Locator("#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input").ClickAsync();

await Page.Locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").ClickAsync();

何時使用此方法

不建議使用 CSS 和 XPath，因為 DOM 經常變更，導致測試不具彈性。相反地，請嘗試提出一個接近使用者感知頁面的定位器，例如角色定位器或使用測試 ID 定義明確的測試合約。

在 Shadow DOM 中定位

Playwright 中的所有定位器預設都適用於 Shadow DOM 中的元素。例外情況如下：

考慮以下範例，其中包含自訂 Web 元件

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

您可以像陰影根目錄完全不存在一樣進行定位。

點擊 <div>詳細資訊</div>

await page.GetByText("Details").ClickAsync();

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

await page
    .Locator("x-details", new() { HasText = "Details" })
    .ClickAsync();

<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> 包含文字 "詳細資訊"

await Expect(Page.Locator("x-details")).ToContainTextAsync("Details");

篩選定位器

考慮以下 DOM 結構，我們想要點擊第二個產品卡片的購買按鈕。我們有幾個選項可以篩選定位器以取得正確的定位器。

https://127.0.0.1:3000

產品 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() 方法依文字篩選定位器。它將在元素內部的某個位置（可能在子元素中）搜尋特定的字串，不區分大小寫。您也可以傳遞規則運算式。

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasText = "Product 2" })
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

使用規則運算式

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasTextRegex = new Regex("Product 2") })
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

依據不包含文字篩選

或者，依據不包含文字篩選

// 5 in-stock items
await Expect(Page.getByRole(AriaRole.Listitem).Filter(new() { HasNotText = "Out of stock" }))
    .ToHaveCountAsync(5);

依子系/後代篩選

定位器支援一個選項，僅選取具有或不具有符合另一個定位器的後代的元素。因此，您可以依據任何其他定位器進行篩選，例如 Locator.GetByRole()、Locator.GetByTestId()、Locator.GetByText() 等。

https://127.0.0.1:3000

產品 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>

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Heading, new() {
            Name = "Product 2"
        })
    })
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

我們也可以斷言產品卡片以確保只有一個

await Expect(Page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Heading, new() { Name = "Product 2" })
    }))
    .ToHaveCountAsync(1);

篩選定位器必須相對於原始定位器，並且從原始定位器比對開始查詢，而不是從文件根目錄開始查詢。因此，以下程式碼將無法運作，因為篩選定位器從 <ul> 清單元素開始比對，而該元素位於原始定位器比對的 <li> 清單項目之外

// ✖ WRONG
await Expect(Page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        Has = page.GetByRole(AriaRole.List).GetByRole(AriaRole.Heading, new() { Name = "Product 2" })
    }))
    .ToHaveCountAsync(1);

依據不包含子系/後代篩選

我們也可以依據不包含內部相符元素進行篩選。

await Expect(Page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() {
        HasNot = page.GetByRole(AriaRole.Heading, new() { Name = "Product 2" })
    }))
    .ToHaveCountAsync(1);

請注意，內部定位器從外部定位器開始比對，而不是從文件根目錄開始比對。

定位器運算子

在定位器內比對

您可以串聯建立定位器的方法，例如 Page.GetByText() 或 Locator.GetByRole()，以將搜尋範圍縮小到頁面的特定部分。

在此範例中，我們先建立一個名為 product 的定位器，方法是定位其 listitem 角色。然後我們依文字篩選。我們可以再次使用 product 定位器依角色按鈕取得並點擊它，然後使用斷言來確保只有一個文字為 "產品 2" 的產品。

var product = page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasText = "Product 2" });

await product
    .GetByRole(AriaRole.Button, new() { Name = "Add to cart" })
    .ClickAsync();

您也可以將兩個定位器串聯在一起，例如，在特定對話方塊內尋找 "儲存" 按鈕

var saveButton = page.GetByRole(AriaRole.Button, new() { Name = "Save" });
// ...
var dialog = page.GetByTestId("settings-dialog");
await dialog.Locator(saveButton).ClickAsync();

同時比對兩個定位器

Locator.And() 方法透過比對額外的定位器來縮小現有定位器的範圍。例如，您可以結合 Page.GetByRole() 和 Page.GetByTitle()，同時依角色和標題進行比對。

var button = page.GetByRole(AriaRole.Button).And(page.GetByTitle("Subscribe"));

比對兩個替代定位器之一

如果您想要鎖定兩個或多個元素之一，並且您不知道將會是哪一個，請使用 Locator.Or() 來建立一個定位器，該定位器比對任何一個或兩個替代方案。

例如，考慮一種情況，您想要點擊 "新電子郵件" 按鈕，但有時會改為顯示安全性設定對話方塊。在這種情況下，您可以等待 "新電子郵件" 按鈕或對話方塊，並採取相應的行動。

注意

如果 "新電子郵件" 按鈕和安全性對話方塊都出現在螢幕上，則 "or" 定位器將會比對它們兩個，可能會擲回「嚴格模式違規」錯誤。在這種情況下，您可以使用 Locator.First 僅比對其中一個。

var newEmail = page.GetByRole(AriaRole.Button, new() { Name = "New" });
var dialog = page.GetByText("Confirm security settings");
await Expect(newEmail.Or(dialog).First).ToBeVisibleAsync();
if (await dialog.IsVisibleAsync())
  await page.GetByRole(AriaRole.Button, new() { Name = "Dismiss" }).ClickAsync();
await newEmail.ClickAsync();

僅比對可見元素

注意

通常最好找到一種更可靠的方法來唯一識別元素，而不是檢查可見性。

考慮一個頁面，其中包含兩個按鈕，第一個不可見，第二個可見。

<button style='display: none'>Invisible</button>
<button>Visible</button>

這將會尋找兩個按鈕並擲回嚴格模式違規錯誤
```
await page.Locator("button").ClickAsync();
```
這只會尋找第二個按鈕，因為它是可見的，然後點擊它。
```
await page.Locator("button").Locator("visible=true").ClickAsync();
```

清單

計算清單中的項目數

您可以斷言定位器以計算清單中的項目數。

例如，考慮以下 DOM 結構

https://127.0.0.1:3000

蘋果
香蕉
橘子

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

使用計數斷言來確保清單有 3 個項目。

await Expect(Page.GetByRole(AriaRole.Listitem)).ToHaveCountAsync(3);

斷言清單中的所有文字

您可以斷言定位器以尋找清單中的所有文字。

例如，考慮以下 DOM 結構

https://127.0.0.1:3000

蘋果
香蕉
橘子

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

使用 Expect(Locator).ToHaveTextAsync() 來確保清單具有文字 "蘋果"、"香蕉" 和 "橘子"。

await Expect(Page
    .GetByRole(AriaRole.Listitem))
    .ToHaveTextAsync(new string[] {"apple", "banana", "orange"});

取得特定項目

有很多方法可以取得清單中的特定項目。

依文字取得

使用 Page.GetByText() 方法依據清單中的元素的文字內容來定位元素，然後點擊它。

例如，考慮以下 DOM 結構

https://127.0.0.1:3000

蘋果
香蕉
橘子

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

依據項目的文字內容定位項目並點擊它。

await page.GetByText("orange").ClickAsync();

依文字篩選

使用 Locator.Filter() 來定位清單中的特定項目。

例如，考慮以下 DOM 結構

https://127.0.0.1:3000

蘋果
香蕉
橘子

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

依據 "listitem" 角色定位項目，然後依據 "橘子" 文字篩選，然後點擊它。

await page
    .GetByRole(AriaRole.Listitem)
    .Filter(new() { HasText = "orange" })
    .ClickAsync();

依測試 ID 取得

使用 Page.GetByTestId() 方法來定位清單中的元素。如果尚未擁有測試 ID，您可能需要修改 html 並新增測試 ID。

例如，考慮以下 DOM 結構

https://127.0.0.1:3000

蘋果
香蕉
橘子

<ul>
  <li data-testid='apple'>apple</li>
  <li data-testid='banana'>banana</li>
  <li data-testid='orange'>orange</li>
</ul>

依據其 "橘子" 測試 ID 定位項目，然後點擊它。

await page.GetByTestId("orange").ClickAsync();

依第 n 個項目取得

如果您有一個相同的元素清單，而區分它們的唯一方法是順序，則可以使用 Locator.First、Locator.Last 或 Locator.Nth() 從清單中選擇特定元素。

var banana = await page.GetByRole(AriaRole.Listitem).Nth(1);

但是，請謹慎使用此方法。頁面通常可能會變更，而定位器將指向與您預期的元素完全不同的元素。相反地，請嘗試提出一個唯一的定位器，該定位器將通過嚴格模式條件。

串聯篩選器

當您有多個具有各種相似之處的元素時，可以使用 Locator.Filter() 方法來選取正確的元素。您也可以串聯多個篩選器來縮小選取範圍。

例如，考慮以下 DOM 結構

https://127.0.0.1:3000

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" 和 "說再見" 的列的螢幕截圖

var rowLocator = page.GetByRole(AriaRole.Listitem);

await rowLocator
    .Filter(new() { HasText = "Mary" })
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Button, new() { Name = "Say goodbye" })
    })
    .ScreenshotAsync(new() { Path = "screenshot.png" });

您現在應該在專案的根目錄中擁有一個 "screenshot.png" 檔案。

罕見的使用案例

對清單中的每個元素執行某些操作

反覆運算元素

foreach (var row in await page.GetByRole(AriaRole.Listitem).AllAsync())
  Console.WriteLine(await row.TextContentAsync());

使用常規 for 迴圈反覆運算

var rows = page.GetByRole(AriaRole.Listitem);
var count = await rows.CountAsync();
for (int i = 0; i < count; ++i)
  Console.WriteLine(await rows.Nth(i).TextContentAsync());

在頁面中評估

Locator.EvaluateAllAsync() 內的程式碼在頁面中執行，您可以在其中呼叫任何 DOM API。

var rows = page.GetByRole(AriaRole.Listitem);
var texts = await rows.EvaluateAllAsync(
    "list => list.map(element => element.textContent)");

嚴格模式

定位器是嚴格的。這表示如果有多個元素符合條件，則對隱含某些目標 DOM 元素的定位器執行的所有操作都會擲回例外狀況。例如，如果 DOM 中有多個按鈕，則以下呼叫會擲回例外狀況

如果有多個則擲回錯誤

await page.GetByRole(AriaRole.Button).ClickAsync();

另一方面，Playwright 了解您何時執行多元素操作，因此當定位器解析為多個元素時，以下呼叫可以正常運作。

使用多個元素時可正常運作

await page.GetByRole(AriaRole.Button).CountAsync();

您可以透過告知 Playwright 在多個元素符合條件時要使用哪個元素，明確選擇退出嚴格模式檢查，方法是透過 Locator.First、Locator.Last 和 Locator.Nth()。不建議使用這些方法，因為當您的頁面變更時，Playwright 可能會點擊您不想要的元素。相反地，請遵循上述最佳實務來建立唯一識別目標元素的定位器。

簡介​

快速指南​

定位元素​

依角色定位​

註冊

依標籤定位​

依佔位符定位​

依文字定位​

依替代文字定位​

依標題定位​

依測試 ID 定位​

設定自訂測試 ID 屬性​

依 CSS 或 XPath 定位​

在 Shadow DOM 中定位​

篩選定位器​

產品 1

產品 2

依文字篩選​

依據不包含文字篩選​

依子系/後代篩選​

產品 1

產品 2

依據不包含子系/後代篩選​

定位器運算子​

在定位器內比對​

同時比對兩個定位器​

比對兩個替代定位器之一​

僅比對可見元素​

清單​

計算清單中的項目數​

斷言清單中的所有文字​

取得特定項目​

依文字取得​

依文字篩選​

依測試 ID 取得​

依第 n 個項目取得​

串聯篩選器​

罕見的使用案例​

對清單中的每個元素執行某些操作​

在頁面中評估​

嚴格模式​

如果有多個則擲回錯誤​

使用多個元素時可正常運作​

更多定位器​

簡介

快速指南

定位元素

依角色定位

依標籤定位

依佔位符定位

依文字定位

依替代文字定位

依標題定位

依測試 ID 定位

設定自訂測試 ID 屬性

依 CSS 或 XPath 定位

在 Shadow DOM 中定位

篩選定位器

依文字篩選

依據不包含文字篩選

依子系/後代篩選

依據不包含子系/後代篩選

定位器運算子

在定位器內比對

同時比對兩個定位器

比對兩個替代定位器之一

僅比對可見元素

清單

計算清單中的項目數

斷言清單中的所有文字

取得特定項目

依文字取得

依文字篩選

依測試 ID 取得

依第 n 個項目取得

串聯篩選器

罕見的使用案例

對清單中的每個元素執行某些操作

在頁面中評估

嚴格模式

如果有多個則擲回錯誤

使用多個元素時可正常運作

更多定位器