跳到主要內容

Locator

定位器是 Playwright 自動等待和重試功能的中心。簡而言之，定位器代表一種隨時在頁面上尋找元素的方式。可以使用 Page.locator() 方法建立定位器。

深入瞭解定位器.

方法​

all​

新增於：v1.29 locator.all

當定位器指向元素清單時，這會傳回定位器陣列，指向其各自的元素。

注意

Locator.all() 不會等待元素符合定位器，而是立即傳回頁面上存在的任何內容。

當元素清單動態變更時，Locator.all() 會產生不可預測且不穩定的結果。

當元素清單穩定但動態載入時，請等待完整清單完成載入，然後再呼叫 Locator.all()。

用法

for (Locator li : page.getByRole("listitem").all())
  li.click();

傳回

allInnerTexts​

新增於：v1.14 locator.allInnerTexts

傳回所有相符節點的 node.innerText 值陣列。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 assertThat(locator).hasText() 和 setUseInnerText 選項，以避免不穩定。請參閱斷言指南以取得更多詳細資訊。

用法

String[] texts = page.getByRole(AriaRole.LINK).allInnerTexts();

傳回

allTextContents​

新增於：v1.14 locator.allTextContents

傳回所有相符節點的 node.textContent 值陣列。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 assertThat(locator).hasText() 以避免不穩定。請參閱斷言指南以取得更多詳細資訊。

用法

String[] texts = page.getByRole(AriaRole.LINK).allTextContents();

傳回

and​

新增於：v1.34 locator.and

建立一個同時符合此定位器和引數定位器的定位器。

用法

以下範例會尋找具有特定標題的按鈕。

Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));

引數

  • locator Locator#

    要比對的其他定位器。

傳回

ariaSnapshot​

新增於：v1.49 locator.ariaSnapshot

擷取給定元素的 aria 快照。請閱讀更多關於 aria 快照和 assertThat(locator).matchesAriaSnapshot() 以取得對應的斷言。

用法

page.getByRole(AriaRole.LINK).ariaSnapshot();

引數

傳回

詳細資訊

此方法擷取給定元素的 aria 快照。快照是一個字串，代表元素及其子元素的狀態。快照可用於斷言測試中元素的狀態，或將其與未來的狀態進行比較。

ARIA 快照使用 YAML 標記語言表示

  • 物件的索引鍵是元素的角色和選用的可存取名稱。
  • 值可以是文字內容或子元素陣列。
  • 通用靜態文字可以使用 text 索引鍵表示。

以下是 HTML 標記和各自的 ARIA 快照

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>
- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

blur​

新增於：v1.28 locator.blur

在元素上呼叫 blur。

用法

Locator.blur();
Locator.blur(options);

引數

傳回

boundingBox​

新增於：v1.14 locator.boundingBox

此方法傳回符合定位器的元素的邊界框，如果元素不可見，則傳回 null。邊界框是相對於主框架視窗 (通常與瀏覽器視窗相同) 計算的。

用法

BoundingBox box = page.getByRole(AriaRole.BUTTON).boundingBox();
page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);

引數

傳回

  • null | BoundingBox#

    • x double

      元素的 x 座標，以像素為單位。

    • y double

      元素的 y 座標，以像素為單位。

    • width double

      元素的寬度，以像素為單位。

    • height double

      元素的高度，以像素為單位。

詳細資訊

捲動會影響傳回的邊界框，與 Element.getBoundingClientRect 類似。這表示 x 和/或 y 可能為負數。

子框架中的元素會傳回相對於主框架的邊界框，這與 Element.getBoundingClientRect 不同。

假設頁面是靜態的，則使用邊界框座標執行輸入是安全的。例如，以下程式碼片段應點擊元素的中心。

check​

新增於：v1.14 locator.check

確保已選取核取方塊或收音機元素。

用法

page.getByRole(AriaRole.CHECKBOX).check();

引數

  • options Locator.CheckOptions (選用)

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • setPosition Position (選用)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。

傳回

詳細資訊

執行以下步驟

  1. 確保元素是核取方塊或收音機輸入。如果不是，此方法會擲出例外。如果元素已選取，此方法會立即返回。
  2. 等待元素上的可操作性檢查，除非設定了 setForce 選項。
  3. 如果需要，將元素捲動到檢視範圍。
  4. 使用 Page.mouse() 在元素中心點擊。
  5. 確保元素現在已選取。如果不是，此方法會擲出例外。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會擲出例外。

當所有步驟組合在指定的 setTimeout 期間未完成時，此方法會擲出 TimeoutError。傳遞零逾時會停用此功能。

clear​

新增於：v1.28 locator.clear

清除輸入欄位。

用法

page.getByRole(AriaRole.TEXTBOX).clear();

引數

傳回

詳細資訊

此方法會等待可操作性檢查、聚焦元素、清除它，並在清除後觸發 input 事件。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會擲出錯誤。但是，如果元素在具有關聯 控制項的 <label> 元素內，則會改為清除控制項。

click​

新增於：v1.14 locator.click

點擊元素。

用法

點擊按鈕

page.getByRole(AriaRole.BUTTON).click();

在畫布上的特定位置按住 Shift 鍵並點擊右鍵

page.locator("canvas").click(new Locator.ClickOptions()
  .setButton(MouseButton.RIGHT)
  .setModifiers(Arrays.asList(KeyboardModifier.SHIFT))
  .setPosition(23, 32));

引數

  • options Locator.ClickOptions (選用)

    • setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (選用)#

      預設為 left。

    • setClickCount int (選用)#

      預設為 1。請參閱 UIEvent.detail。

    • setDelay double (選用)#

      mousedown 和 mouseup 之間等待的時間（毫秒）。預設為 0。

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選用)#

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。「ControlOrMeta」在 Windows 和 Linux 上解析為「Control」，在 macOS 上解析為「Meta」。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項在未來將預設為 true。

      啟動導覽的動作正在等待這些導覽發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您僅在特殊情況下需要此選項，例如導覽到無法存取的頁面。預設為 false。

    • setPosition Position (選用)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行以下步驟點擊元素

  1. 等待元素上的可操作性檢查，除非設定了 setForce 選項。
  2. 如果需要，將元素捲動到檢視範圍。
  3. 使用 Page.mouse() 在元素中心或指定的 setPosition 中點擊。
  4. 等待啟動的導覽成功或失敗，除非設定了 setNoWaitAfter 選項。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會擲出例外。

當所有步驟組合在指定的 setTimeout 期間未完成時，此方法會擲出 TimeoutError。傳遞零逾時會停用此功能。

contentFrame​

新增於：v1.43 locator.contentFrame

傳回指向與此定位器相同 iframe 的 FrameLocator 物件。

當您在某處取得 Locator 物件，稍後想要與框架內的內容互動時，這非常有用。

對於反向操作，請使用 FrameLocator.owner()。

用法

Locator locator = page.locator("iframe[name=\"embedded\"]");
// ...
FrameLocator frameLocator = locator.contentFrame();
frameLocator.getByRole(AriaRole.BUTTON).click();

傳回

count​

新增於：v1.14 locator.count

傳回符合定位器的元素數量。

斷言計數

如果您需要斷言頁面上的元素數量，請優先使用 assertThat(locator).hasCount() 以避免不穩定。請參閱斷言指南以取得更多詳細資訊。

用法

int count = page.getByRole(AriaRole.LISTITEM).count();

傳回

dblclick​

新增於：v1.14 locator.dblclick

雙擊元素。

用法

Locator.dblclick();
Locator.dblclick(options);

引數

  • options Locator.DblclickOptions (選用)

    • setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (選用)#

      預設為 left。

    • setDelay double (選用)#

      mousedown 和 mouseup 之間等待的時間（毫秒）。預設為 0。

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選用)#

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。「ControlOrMeta」在 Windows 和 Linux 上解析為「Control」，在 macOS 上解析為「Meta」。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • setPosition Position (選用)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行以下步驟雙擊元素

  1. 等待元素上的可操作性檢查，除非設定了 setForce 選項。
  2. 如果需要，將元素捲動到檢視範圍。
  3. 使用 Page.mouse() 在元素中心或指定的 setPosition 中雙擊。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會擲出例外。

當所有步驟組合在指定的 setTimeout 期間未完成時，此方法會擲出 TimeoutError。傳遞零逾時會停用此功能。

注意

element.dblclick() 會發送兩個 click 事件和一個 dblclick 事件。

dispatchEvent​

新增於：v1.14 locator.dispatchEvent

以程式設計方式在符合的元素上發送事件。

用法

locator.dispatchEvent("click");

引數

傳回

詳細資訊

上面的程式碼片段在元素上發送 click 事件。無論元素的顯示狀態如何，都會發送 click。這相當於呼叫 element.click()。

在底層，它會根據給定的 type 建立事件的實例，使用 eventInit 屬性初始化它，並在元素上發送它。事件預設為 composed、cancelable 和 bubble。

由於 eventInit 是事件特定的，請參閱事件文件以取得初始屬性列表

如果您希望將即時物件傳遞到事件中，您也可以將 JSHandle 指定為屬性值

JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
locator.dispatchEvent("dragstart", arg);

dragTo​

新增於：v1.18 locator.dragTo

將來源元素拖曳到目標元素並放下。

用法

Locator source = page.locator("#source");
Locator target = page.locator("#target");

source.dragTo(target);
// or specify exact positions relative to the top-left corners of the elements:
source.dragTo(target, new Locator.DragToOptions()
  .setSourcePosition(34, 7).setTargetPosition(10, 20));

引數

  • target Locator#

    要拖曳到的元素的定位器。

  • options Locator.DragToOptions (選用)

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • setSourcePosition SourcePosition (選用)#

      在此點點擊來源元素，此點相對於元素 padding box 左上角。如果未指定，則使用元素的一些可見點。

    • setTargetPosition TargetPosition (選用)#

      在此點將目標元素放下，此點相對於元素 padding box 左上角。如果未指定，則使用元素的一些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。

傳回

詳細資訊

此方法將定位器拖曳到另一個目標定位器或目標位置。它將首先移動到來源元素，執行 mousedown，然後移動到目標元素或位置並執行 mouseup。

evaluate​

新增於：v1.14 locator.evaluate

在頁面中執行 JavaScript 程式碼，並將符合的元素作為引數。

用法

Locator tweets = page.locator(".tweet .retweets");
assertEquals("10 retweets", tweets.evaluate("node => node.innerText"));

引數

傳回

詳細資訊

傳回 expression 的傳回值，呼叫時會將相符的元素作為第一個引數，並將 arg 作為第二個引數。

如果 expression 傳回 Promise，此方法將等待 Promise 解析並傳回其值。

如果 expression 擲回錯誤或拒絕，此方法將擲回錯誤。

evaluateAll​

新增於：v1.14 locator.evaluateAll

在頁面中執行 JavaScript 程式碼，將所有相符的元素作為引數。

用法

Locator locator = page.locator("div");
boolean moreThanTen = (boolean) locator.evaluateAll("(divs, min) => divs.length > min", 10);

引數

  • expression String#

    要在瀏覽器環境中評估的 JavaScript 表達式。如果表達式評估為函數，則會自動調用該函數。

  • arg EvaluationArgument (選填)#

    傳遞至 expression 的選填引數。

傳回

詳細資訊

傳回 expression 的傳回值，呼叫時會將所有相符元素的陣列作為第一個引數，並將 arg 作為第二個引數。

如果 expression 傳回 Promise，此方法將等待 Promise 解析並傳回其值。

如果 expression 擲回錯誤或拒絕，此方法將擲回錯誤。

evaluateHandle​

新增於：v1.14 locator.evaluateHandle

在頁面中執行 JavaScript 程式碼，將相符的元素作為引數，並傳回帶有結果的 JSHandle。

用法

Locator.evaluateHandle(expression);
Locator.evaluateHandle(expression, arg, options);

引數

傳回

詳細資訊

傳回 expression 的傳回值，以 JSHandle 的形式傳回，呼叫時會將相符的元素作為第一個引數，並將 arg 作為第二個引數。

Locator.evaluate() 和 Locator.evaluateHandle() 之間的唯一區別在於 Locator.evaluateHandle() 傳回 JSHandle。

如果 expression 傳回 Promise，此方法將等待 Promise 解析並傳回其值。

如果 expression 擲回錯誤或拒絕，此方法將擲回錯誤。

請參閱 Page.evaluateHandle() 以取得更多詳細資訊。

fill​

新增於：v1.14 locator.fill

設定輸入欄位的值。

用法

page.getByRole(AriaRole.TEXTBOX).fill("example value");

引數

傳回

詳細資訊

此方法會等待可操作性檢查、聚焦元素、填寫它，並在填寫後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會擲回錯誤。但是，如果元素位於具有相關聯 控制項的 <label> 元素內，則會改為填寫控制項。

若要傳送細微的鍵盤事件，請使用 Locator.pressSequentially()。

filter​

新增於：v1.22 locator.filter

此方法根據選項縮小現有的定位器範圍，例如依文字篩選。它可以串連多次篩選。

用法

Locator rowLocator = page.locator("tr");
// ...
rowLocator
    .filter(new Locator.FilterOptions().setHasText("text in column 1"))
    .filter(new Locator.FilterOptions().setHas(
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("column 2 button"))
    ))
    .screenshot();

引數

  • options Locator.FilterOptions (選填)

    • setHas Locator (選填)#

      將方法結果縮小到包含與此相對定位器相符的元素。例如，具有 text=Playwright 的 article 會比對 <article><div>Playwright</div></article>。

      內部定位器**必須相對於**外部定位器，並且從外部定位器比對開始查詢，而不是從文件根目錄開始查詢。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到具有 div 的 content。但是，尋找具有 article div 的 content 將會失敗，因為內部定位器必須是相對的，並且不應使用 content 外部的任何元素。

      請注意，外部和內部定位器必須屬於相同的框架。內部定位器不得包含 FrameLocator。

    • setHasNot Locator (選填)新增於：v1.33#

      比對不包含與內部定位器相符之元素的元素。內部定位器會針對外部定位器查詢。例如，不具有 div 的 article 會比對 <article><span>Playwright</span></article>。

      請注意，外部和內部定位器必須屬於相同的框架。內部定位器不得包含 FrameLocator。

    • setHasNotText String | Pattern (選填)新增於：v1.33#

      比對在內部某處（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞 string 時，比對不區分大小寫，並搜尋子字串。

    • setHasText String | Pattern (選填)#

      比對在內部某處（可能在子元素或後代元素中）包含指定文字的元素。當傳遞 string 時，比對不區分大小寫，並搜尋子字串。例如，"Playwright" 會比對 <article><div>Playwright</div></article>。

傳回

first​

新增於：v1.14 locator.first

傳回第一個相符元素的定位器。

用法

Locator.first();

傳回

focus​

新增於：v1.14 locator.focus

在相符的元素上呼叫 focus。

用法

Locator.focus();
Locator.focus(options);

引數

傳回

frameLocator​

新增於：v1.17 locator.frameLocator

當使用 iframe 時，您可以建立框架定位器，該定位器將進入 iframe 並允許在該 iframe 中定位元素

用法

Locator locator = page.frameLocator("iframe").getByText("Submit");
locator.click();

引數

  • selector String#

    用於解析 DOM 元素時的選取器。

傳回

getAttribute​

新增於：v1.14 locator.getAttribute

傳回相符元素的屬性值。

判斷提示屬性

如果您需要判斷提示元素的屬性，請優先使用 assertThat(locator).hasAttribute() 以避免不穩定性。請參閱判斷提示指南以取得更多詳細資訊。

用法

Locator.getAttribute(name);
Locator.getAttribute(name, options);

引數

傳回

getByAltText​

新增於：v1.27 locator.getByAltText

允許依其替代文字定位元素。

用法

例如，此方法將依替代文字「Playwright logo」尋找圖片

<img alt='Playwright logo'>
page.getByAltText("Playwright logo").click();

引數

  • text String | Pattern#

    用於定位元素的文字。

  • options Locator.GetByAltTextOptions (選填)

    • setExact boolean (選填)#

      是否尋找完全相符項：區分大小寫和全字串。預設為 false。依正規表示式定位時會忽略。請注意，完全相符項仍會修剪空白字元。

傳回

getByLabel​

新增於：v1.27 locator.getByLabel

允許依相關聯 <label> 或 aria-labelledby 元素的文字，或依 aria-label 屬性來定位輸入元素。

用法

例如，此方法將在下列 DOM 中依標籤「Username」和「Password」尋找輸入

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");

引數

  • text String | Pattern#

    用於定位元素的文字。

  • options Locator.GetByLabelOptions (選填)

    • setExact boolean (選填)#

      是否尋找完全相符項：區分大小寫和全字串。預設為 false。依正規表示式定位時會忽略。請注意，完全相符項仍會修剪空白字元。

傳回

getByPlaceholder​

新增於：v1.27 locator.getByPlaceholder

允許依預留位置文字定位輸入元素。

用法

例如，請考慮下列 DOM 結構。

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

您可以在依預留位置文字定位輸入後填寫它

page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");

引數

  • text String | Pattern#

    用於定位元素的文字。

  • options Locator.GetByPlaceholderOptions (選填)

    • setExact boolean (選填)#

      是否尋找完全相符項：區分大小寫和全字串。預設為 false。依正規表示式定位時會忽略。請注意，完全相符項仍會修剪空白字元。

傳回

getByRole​

新增於：v1.27 locator.getByRole

允許依其 ARIA 角色、ARIA 屬性和 無障礙名稱來定位元素。

用法

請考慮下列 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();

引數

  • role enum AriaRole { ALERT, ALERTDIALOG, APPLICATION, ARTICLE, BANNER, BLOCKQUOTE, BUTTON, CAPTION, CELL, CHECKBOX, CODE, COLUMNHEADER, COMBOBOX, COMPLEMENTARY, CONTENTINFO, DEFINITION, DELETION, DIALOG, DIRECTORY, DOCUMENT, EMPHASIS, FEED, FIGURE, FORM, GENERIC, GRID, GRIDCELL, GROUP, HEADING, IMG, INSERTION, LINK, LIST, LISTBOX, LISTITEM, LOG, MAIN, MARQUEE, MATH, METER, MENU, MENUBAR, MENUITEM, MENUITEMCHECKBOX, MENUITEMRADIO, NAVIGATION, NONE, NOTE, OPTION, PARAGRAPH, PRESENTATION, PROGRESSBAR, RADIO, RADIOGROUP, REGION, ROW, ROWGROUP, ROWHEADER, SCROLLBAR, SEARCH, SEARCHBOX, SEPARATOR, SLIDER, SPINBUTTON, STATUS, STRONG, SUBSCRIPT, SUPERSCRIPT, SWITCH, TAB, TABLE, TABLIST, TABPANEL, TERM, TEXTBOX, TIME, TIMER, TOOLBAR, TOOLTIP, TREE, TREEGRID, TREEITEM }#

    必要的 aria 角色。

  • options Locator.GetByRoleOptions (選填)

    • setChecked boolean (選填)#

      通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。

      深入瞭解 aria-checked。

    • setDisabled boolean (選填)#

      通常由 aria-disabled 或 disabled 設定的屬性。

      注意

      與大多數其他屬性不同，disabled 會透過 DOM 階層繼承。深入瞭解 aria-disabled。

    • setExact boolean (選填)新增於：v1.28#

      是否完全比對 setName：區分大小寫和全字串。預設為 false。setName 為正規表示式時會忽略。請注意，完全相符項仍會修剪空白字元。

    • setExpanded boolean (選填)#

      通常由 aria-expanded 設定的屬性。

      深入瞭解 aria-expanded。

    • setIncludeHidden boolean (選填)#

      控制是否比對隱藏元素的選項。依預設，角色選取器只比對非隱藏元素，如 ARIA 定義。

      深入瞭解 aria-hidden。

    • setLevel int (選填)#

      數字屬性，通常存在於角色 heading、listitem、row、treeitem 中，<h1>-<h6> 元素具有預設值。

      深入瞭解 aria-level。

    • setName String | Pattern (選填)#

      比對無障礙名稱的選項。依預設，比對不區分大小寫，並搜尋子字串，使用 setExact 來控制此行為。

      深入瞭解無障礙名稱。

    • setPressed boolean (選填)#

      通常由 aria-pressed 設定的屬性。

      深入瞭解 aria-pressed。

    • setSelected boolean (選填)#

      通常由 aria-selected 設定的屬性。

      深入瞭解 aria-selected。

傳回

詳細資訊

角色選取器**不會取代**無障礙功能稽核和一致性測試，而是提供有關 ARIA 指南的早期意見反應。

許多 html 元素具有隱含定義的角色，角色選取器可以識別該角色。您可以在此處找到所有支援的角色。ARIA 指南**不建議**透過將 role 和/或 aria-* 屬性設定為預設值來複製隱含角色和屬性。

getByTestId​

新增於：v1.27 locator.getByTestId

依測試 ID 定位元素。

用法

請考慮下列 DOM 結構。

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

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

page.getByTestId("directions").click();

引數

傳回

詳細資訊

依預設，data-testid 屬性用作測試 ID。如有必要，請使用 Selectors.setTestIdAttribute() 來設定不同的測試 ID 屬性。

getByText​

新增於：v1.27 locator.getByText

允許定位包含給定文字的元素。

另請參閱 Locator.filter()，它允許依另一個條件（例如無障礙角色）進行比對，然後依文字內容篩選。

用法

請考慮下列 DOM 結構

<div>Hello <span>world</span></div>
<div>Hello</div>

您可以依文字子字串、完全字串或正規表示式進行定位

// Matches <span>
page.getByText("world");

// Matches first <div>
page.getByText("Hello world");

// Matches second <div>
page.getByText("Hello", new Page.GetByTextOptions().setExact(true));

// Matches both <div>s
page.getByText(Pattern.compile("Hello"));

// Matches second <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

引數

  • text String | Pattern#

    用於定位元素的文字。

  • options Locator.GetByTextOptions (選填)

    • setExact boolean (選填)#

      是否尋找完全相符項：區分大小寫和全字串。預設為 false。依正規表示式定位時會忽略。請注意，完全相符項仍會修剪空白字元。

傳回

詳細資訊

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

類型為 button 和 submit 的輸入元素會依其 value 而不是文字內容比對。例如，依文字 "Log in" 定位會比對 <input type=button value="Log in">。

getByTitle​

新增於：v1.27 locator.getByTitle

允許依其 title 屬性定位元素。

用法

請考慮下列 DOM 結構。

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

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

assertThat(page.getByTitle("Issues count")).hasText("25 issues");

引數

  • text String | Pattern#

    用於定位元素的文字。

  • options Locator.GetByTitleOptions (選填)

    • setExact boolean (選填)#

      是否尋找完全相符項：區分大小寫和全字串。預設為 false。依正規表示式定位時會忽略。請注意，完全相符項仍會修剪空白字元。

傳回

highlight​

新增於：v1.20 locator.highlight

在螢幕上醒目提示對應的元素。適用於偵錯，請勿提交使用 Locator.highlight() 的程式碼。

用法

Locator.highlight();

傳回

hover​

新增於：v1.14 locator.hover

懸停在相符的元素上方。

用法

page.getByRole(AriaRole.LINK).hover();

引數

  • options Locator.HoverOptions (選填)

    • setForce boolean (選填)#

      是否略過可操作性檢查。預設為 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。「ControlOrMeta」在 Windows 和 Linux 上解析為「Control」，在 macOS 上解析為「Meta」。

    • setNoWaitAfter boolean (選填)新增於：v1.28#

      已棄用

      此選項無效。

      此選項無效。

    • setPosition Position (選填)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選填)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選填)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行下列步驟懸停在元素上方

  1. 等待元素上的可操作性檢查，除非設定 setForce 選項。
  2. 如果需要，將元素捲動到檢視範圍。
  3. 使用 Page.mouse() 懸停在元素的中心，或指定的 setPosition。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會擲出例外。

當所有組合步驟在指定的 setTimeout 期間未完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

innerHTML​

新增於：v1.14 locator.innerHTML

傳回 element.innerHTML。

用法

Locator.innerHTML();
Locator.innerHTML(options);

引數

傳回

innerText​

新增於：v1.14 locator.innerText

傳回 element.innerText。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 assertThat(locator).hasText() 和 setUseInnerText 選項，以避免不穩定。請參閱斷言指南以取得更多詳細資訊。

用法

Locator.innerText();
Locator.innerText(options);

引數

傳回

inputValue​

新增於：v1.14 locator.inputValue

傳回符合條件的 <input>、<textarea> 或 <select> 元素的數值。

斷言數值

如果您需要斷言輸入值，建議優先使用 assertThat(locator).hasValue() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

String value = page.getByRole(AriaRole.TEXTBOX).inputValue();

引數

傳回

詳細資訊

如果元素不是 input、textarea 或 select，則會擲回錯誤。但是，如果元素位於具有相關聯 control 的 <label> 元素內，則會傳回 control 的數值。

isChecked​

新增於：v1.14 locator.isChecked

傳回元素是否被勾選。如果元素不是核取方塊或單選按鈕輸入，則會擲回錯誤。

斷言勾選狀態

如果您需要斷言核取方塊已被勾選，建議優先使用 assertThat(locator).isChecked() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

boolean checked = page.getByRole(AriaRole.CHECKBOX).isChecked();

引數

傳回

isDisabled​

新增於：v1.14 locator.isDisabled

傳回元素是否為停用狀態，與啟用狀態相反。

斷言停用狀態

如果您需要斷言元素為停用狀態，建議優先使用 assertThat(locator).isDisabled() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

boolean disabled = page.getByRole(AriaRole.BUTTON).isDisabled();

引數

傳回

isEditable​

新增於：v1.14 locator.isEditable

傳回元素是否為可編輯狀態。如果目標元素不是 <input>、<textarea>、<select>、[contenteditable] 且沒有允許 [aria-readonly] 的 role，則此方法會擲回錯誤。

斷言可編輯狀態

如果您需要斷言元素為可編輯狀態，建議優先使用 assertThat(locator).isEditable() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

boolean editable = page.getByRole(AriaRole.TEXTBOX).isEditable();

引數

傳回

isEnabled​

新增於：v1.14 locator.isEnabled

傳回元素是否為啟用狀態。

斷言啟用狀態

如果您需要斷言元素為啟用狀態，建議優先使用 assertThat(locator).isEnabled() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

boolean enabled = page.getByRole(AriaRole.BUTTON).isEnabled();

引數

傳回

isHidden​

新增於：v1.14 locator.isHidden

傳回元素是否為隱藏狀態，與可見狀態相反。

斷言可見性

如果您需要斷言元素為隱藏狀態，建議優先使用 assertThat(locator).isHidden() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

boolean hidden = page.getByRole(AriaRole.BUTTON).isHidden();

引數

  • options Locator.IsHiddenOptions （選填）

    • setTimeout double （選填）#

      已棄用

      此選項會被忽略。Locator.isHidden() 不會等待元素變成隱藏狀態，並立即傳回。

傳回

isVisible​

新增於：v1.14 locator.isVisible

傳回元素是否為可見狀態。

斷言可見性

如果您需要斷言元素為可見狀態，建議優先使用 assertThat(locator).isVisible() 以避免不穩定性。請參閱 assertions guide 以取得更多詳細資訊。

用法

boolean visible = page.getByRole(AriaRole.BUTTON).isVisible();

引數

  • options Locator.IsVisibleOptions （選填）

    • setTimeout double （選填）#

      已棄用

      此選項會被忽略。Locator.isVisible() 不會等待元素變成可見狀態，並立即傳回。

傳回

last​

新增於：v1.14 locator.last

傳回最後一個符合條件的元素的 locator。

用法

Locator banana = page.getByRole(AriaRole.LISTITEM).last();

傳回

locator​

新增於：v1.14 locator.locator

此方法會在 locator 的子樹狀結構中尋找符合指定選擇器的元素。它也接受篩選選項，類似於 Locator.filter() 方法。

深入瞭解定位器.

用法

Locator.locator(selectorOrLocator);
Locator.locator(selectorOrLocator, options);

引數

  • selectorOrLocator String | Locator#

    用於解析 DOM 元素的選擇器或 locator。

  • options Locator.LocatorOptions （選填）

    • setHas Locator （選填）#

      將方法結果縮小到包含與此相對定位器相符的元素。例如，具有 text=Playwright 的 article 會比對 <article><div>Playwright</div></article>。

      內部定位器**必須相對於**外部定位器，並且從外部定位器比對開始查詢，而不是從文件根目錄開始查詢。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到具有 div 的 content。但是，尋找具有 article div 的 content 將會失敗，因為內部定位器必須是相對的，並且不應使用 content 外部的任何元素。

      請注意，外部和內部定位器必須屬於相同的框架。內部定位器不得包含 FrameLocator。

    • setHasNot Locator (選填)新增於：v1.33#

      比對不包含與內部定位器相符之元素的元素。內部定位器會針對外部定位器查詢。例如，不具有 div 的 article 會比對 <article><span>Playwright</span></article>。

      請注意，外部和內部定位器必須屬於相同的框架。內部定位器不得包含 FrameLocator。

    • setHasNotText String | Pattern (選填)新增於：v1.33#

      比對在內部某處（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞 string 時，比對不區分大小寫，並搜尋子字串。

    • setHasText String | Pattern （選填）#

      比對在內部某處（可能在子元素或後代元素中）包含指定文字的元素。當傳遞 string 時，比對不區分大小寫，並搜尋子字串。例如，"Playwright" 會比對 <article><div>Playwright</div></article>。

傳回

nth​

新增於：v1.14 locator.nth

傳回第 n 個符合條件的元素的 locator。它是從零開始的，nth(0) 選擇第一個元素。

用法

Locator banana = page.getByRole(AriaRole.LISTITEM).nth(2);

引數

傳回

or​

新增於：v1.33 locator.or

建立一個 locator，比對符合兩個 locator 中任一或全部的元素。

請注意，當兩個 locator 都比對到內容時，產生的 locator 將會有多個符合項，可能會導致 locator strictness 違規。

用法

考慮一種情境，您想要點擊「New email」按鈕，但有時會出現安全性設定對話方塊。在這種情況下，您可以等待「New email」按鈕或對話方塊，然後採取相應的動作。

注意

如果「New email」按鈕和安全性對話方塊都出現在螢幕上，「or」locator 將會比對到它們兩個，可能會擲回「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();

引數

  • locator Locator#

    要比對的替代 locator。

傳回

page​

新增於：v1.19 locator.page

此 locator 所屬的頁面。

用法

Locator.page();

傳回

press​

新增於：v1.14 locator.press

聚焦符合條件的元素，並按下按鍵組合。

用法

page.getByRole(AriaRole.TEXTBOX).press("Backspace");

引數

  • key String#

    要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。

  • options Locator.PressOptions （選填）

    • setDelay double （選填）#

      keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。

    • setNoWaitAfter boolean （選填）#

      已棄用

      此選項在未來將預設為 true。

      啟動導覽的動作正在等待這些導覽發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您僅在特殊情況下需要此選項，例如導覽到無法存取的頁面。預設為 false。

    • setTimeout double （選填）#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

傳回

詳細資訊

聚焦元素，然後使用 Keyboard.down() 和 Keyboard.up()。

key 可以指定 keyboardEvent.key 值或要產生文字的單一字元。 key 值的超集可以在這裡找到。 按鍵範例：

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp 等。

也支援以下修改快捷鍵：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析為 Control，在 macOS 上解析為 Meta。

按住 Shift 鍵將會輸入與 key 對應的大寫文字。

如果 key 是單一字元，則區分大小寫，因此值 a 和 A 將會產生不同的文字。

也支援諸如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 等快捷鍵。當使用修飾鍵指定時，在按下後續按鍵時，修飾鍵會被按下並保持按住狀態。

pressSequentially​

新增於：v1.38 locator.pressSequentially
提示

在大多數情況下，您應該改用 Locator.fill()。只有在頁面上有特殊的鍵盤處理時，才需要逐個按下按鍵。

聚焦元素，然後針對文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。

若要按下特殊按鍵，例如 Control 或 ArrowDown，請使用 Locator.press()。

用法

locator.pressSequentially("Hello"); // Types instantly
locator.pressSequentially("World", new Locator.pressSequentiallyOptions().setDelay(100)); // Types slower, like a user

在文字欄位中輸入文字，然後提交表單的範例

Locator locator = page.getByLabel("Password");
locator.pressSequentially("my password");
locator.press("Enter");

引數

  • text String#

    要依序按下到聚焦元素中的字元字串。

  • options Locator.PressSequentiallyOptions （選填）

    • setDelay double （選填）#

      按鍵按下之間等待的時間，以毫秒為單位。預設為 0。

    • setNoWaitAfter boolean （選填）#

      已棄用

      此選項無效。

      此選項無效。

    • setTimeout double （選填）#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

傳回

screenshot​

新增於：v1.14 locator.screenshot

拍攝符合 locator 的元素的螢幕截圖。

用法

page.getByRole(AriaRole.LINK).screenshot();

停用動畫並將螢幕截圖儲存到檔案

page.getByRole(AriaRole.LINK).screenshot(new Locator.ScreenshotOptions()
    .setAnimations(ScreenshotAnimations.DISABLED)
    .setPath(Paths.get("example.png")));

引數

  • options Locator.ScreenshotOptions （選填）

    • setAnimations enum ScreenshotAnimations { DISABLED, ALLOW } （選填）#

      當設定為 "disabled" 時，會停止 CSS 動畫、CSS 轉換和 Web Animations。動畫會根據其持續時間獲得不同的處理方式

      • 有限動畫會快轉到完成，因此它們會觸發 transitionend 事件。
      • 無限動畫會取消到初始狀態，然後在螢幕截圖後重新播放。

      預設為 "allow"，保持動畫不受影響。

    • setCaret enum ScreenshotCaret { HIDE, INITIAL } （選填）#

      當設定為 "hide" 時，螢幕截圖將會隱藏文字游標。當設定為 "initial" 時，文字游標行為將不會變更。預設為 "hide"。

    • setMask List<Locator> （選填）#

      指定在拍攝螢幕截圖時應遮罩的 locator。遮罩元素將會被粉紅色方塊 #FF00FF（可透過 setMaskColor 自訂）覆蓋，完全遮蓋其邊界框。

    • setMaskColor String （選填）新增於：v1.35#

      指定遮罩元素的覆蓋方塊顏色，以 CSS 色彩格式表示。預設顏色為粉紅色 #FF00FF。

    • setOmitBackground boolean （選填）#

      隱藏預設的白色背景，並允許拍攝具有透明度的螢幕截圖。不適用於 jpeg 影像。預設為 false。

    • setPath Path （選填）#

      儲存影像的檔案路徑。螢幕截圖類型將會從檔案副檔名推斷。如果 setPath 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則影像將不會儲存到磁碟。

    • setQuality int （選填）#

      影像的品質，介於 0-100 之間。不適用於 png 影像。

    • setScale enum ScreenshotScale { CSS, DEVICE } （選填）#

      當設定為 "css" 時，螢幕截圖的每個 CSS 像素將會有單一像素。對於高 DPI 裝置，這將使螢幕截圖保持較小。使用 "device" 選項將會為每個裝置像素產生單一像素，因此高 DPI 裝置的螢幕截圖將會大兩倍甚至更大。

      預設為 "device"。

    • setStyle String （選填）新增於：v1.41#

      在製作螢幕截圖時要套用的樣式表文字。您可以在此處隱藏動態元素、使元素不可見或變更其屬性，以協助您建立可重複的螢幕截圖。此樣式表會穿透 Shadow DOM 並套用至內部框架。

    • setTimeout double （選填）#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setType enum ScreenshotType { PNG, JPEG } （選填）#

      指定螢幕截圖類型，預設為 png。

傳回

詳細資訊

此方法會擷取頁面的螢幕截圖，裁剪為符合 locator 的特定元素的大小和位置。如果元素被其他元素覆蓋，則實際上不會在螢幕截圖上看到它。如果元素是可捲動的容器，則只有目前捲動的內容才會在螢幕截圖上可見。

此方法會等待 actionability 檢查，然後在拍攝螢幕截圖之前將元素捲動到檢視畫面中。如果元素從 DOM 中分離，則此方法會擲回錯誤。

傳回包含擷取螢幕截圖的緩衝區。

scrollIntoViewIfNeeded​

新增於：v1.14 locator.scrollIntoViewIfNeeded

此方法會等待 actionability 檢查，然後嘗試將元素捲動到檢視畫面中，除非它完全可見，如 IntersectionObserver 的 ratio 所定義。

請參閱 scrolling 以取得捲動的替代方法。

用法

Locator.scrollIntoViewIfNeeded();
Locator.scrollIntoViewIfNeeded(options);

引數

傳回

selectOption​

新增於：v1.14 locator.selectOption

在 <select> 中選取選項。

用法

<select multiple>
  <option value="red">Red</div>
  <option value="green">Green</div>
  <option value="blue">Blue</div>
</select>
// single selection matching the value or label
element.selectOption("blue");
// single selection matching the label
element.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection for blue, red and second option
element.selectOption(new String[] {"red", "green", "blue"});

引數

  • values null | String | ElementHandle | String[] | SelectOption | ElementHandle[] | SelectOption[]#

    • setValue String （選填）

      依 option.value 比對。選填。

    • setLabel String （選填）

      依 option.label 比對。選填。

    • setIndex int （選填）

      依索引比對。選填。

    要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有符合條件的選項，否則只會選取符合其中一個傳遞選項的第一個選項。字串值會比對值和標籤。如果所有指定的屬性都符合，則選項會被視為符合條件。
  • options Locator.SelectOptionOptions （選填）

傳回

詳細資訊

此方法會等待 actionability 檢查，等待直到所有指定的選項都出現在 <select> 元素中，然後選取這些選項。

如果目標元素不是 <select> 元素，此方法會拋出錯誤。但是，如果元素位於具有關聯 控制項 (control) 的 <label> 元素內，則會改用該控制項。

傳回已成功選取的選項值的陣列。

一旦所有提供的選項都已選取，便會觸發 change 和 input 事件。

selectText​

新增於：v1.14 locator.selectText

此方法會等待 可操作性 檢查，然後聚焦元素並選取其所有文字內容。

如果元素位於具有關聯 控制項 (control) 的 <label> 元素內，則會聚焦並選取該控制項中的文字。

用法

Locator.selectText();
Locator.selectText(options);

引數

傳回

setChecked​

新增於：v1.15 locator.setChecked

設定核取方塊或 радіо 元素的狀態。

用法

page.getByRole(AriaRole.CHECKBOX).setChecked(true);

引數

  • checked boolean#

    是否核取或取消核取核取方塊。

  • options Locator.SetCheckedOptions (選用)

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • setPosition Position (選用)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。

傳回

詳細資訊

此方法會透過執行下列步驟來核取或取消核取元素

  1. 確保相符的元素是核取方塊或 радіо 輸入。否則，此方法會拋出錯誤。
  2. 如果元素已處於正確的核取狀態，此方法會立即傳回。
  3. 等待相符元素上的 可操作性 檢查，除非設定了 setForce 選項。如果在檢查期間元素被分離，則會重試整個動作。
  4. 如果需要，將元素捲動到檢視範圍。
  5. 使用 Page.mouse() 在元素中心點擊。
  6. 確保元素現在已核取或取消核取。否則，此方法會拋出錯誤。

當所有步驟組合起來未在指定的 setTimeout 期間完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

setInputFiles​

新增於：v1.14 locator.setInputFiles

將檔案或多個檔案上傳到 <input type=file>。對於具有 [webkitdirectory] 屬性的輸入，僅支援單一目錄路徑。

用法

// Select one file
page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

// Select multiple files
page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

// Select a directory
page.getByLabel("Upload directory").setInputFiles(Paths.get("mydir"));

// Remove all the selected files
page.getByLabel("Upload file").setInputFiles(new Path[0]);

// Upload buffer from memory
page.getByLabel("Upload file").setInputFiles(new FilePayload(
  "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

引數

傳回

詳細資訊

將檔案輸入的值設定為這些檔案路徑或檔案。如果某些 filePaths 是相對路徑，則會相對於目前的工作目錄解析它們。對於空陣列，則會清除選取的檔案。

此方法預期 Locator 指向 輸入元素。但是，如果元素位於具有關聯 控制項 (control) 的 <label> 元素內，則會改為目標控制項。

tap​

新增於：v1.14 locator.tap

對符合定位器的元素執行點擊手勢。

用法

Locator.tap();
Locator.tap(options);

引數

  • options Locator.TapOptions (選用)

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選用)#

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。「ControlOrMeta」在 Windows 和 Linux 上解析為「Control」，在 macOS 上解析為「Meta」。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • setPosition Position (選用)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法會透過執行下列步驟來點擊元素

  1. 等待元素上的 可操作性 檢查，除非設定了 setForce 選項。
  2. 如果需要，將元素捲動到檢視範圍。
  3. 使用 Page.touchscreen() 點擊元素的中心，或指定的 setPosition。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會擲出例外。

當所有步驟組合起來未在指定的 setTimeout 期間完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

注意

element.tap() 需要瀏覽器內容的 hasTouch 選項設定為 true。

textContent​

新增於：v1.14 locator.textContent

傳回 node.textContent。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 assertThat(locator).hasText() 以避免不穩定。請參閱斷言指南以取得更多詳細資訊。

用法

Locator.textContent();
Locator.textContent(options);

引數

傳回

uncheck​

新增於：v1.14 locator.uncheck

確保核取方塊或 радіо 元素已取消核取。

用法

page.getByRole(AriaRole.CHECKBOX).uncheck();

引數

  • options Locator.UncheckOptions (選用)

    • setForce boolean (選用)#

      是否略過可操作性檢查。預設為 false。

    • setNoWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • setPosition Position (選用)#

      要使用的點，相對於元素 padding box 的左上角。如果未指定，則使用元素的某些可見點。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

    • setTrial boolean (選用)#

      設定後，此方法僅執行可操作性檢查並略過動作。預設為 false。在不執行動作的情況下，等待元素準備好動作很有用。

傳回

詳細資訊

此方法會透過執行下列步驟來取消核取元素

  1. 確保元素是核取方塊或 радіо 輸入。否則，此方法會拋出錯誤。如果元素已取消核取，此方法會立即傳回。
  2. 等待元素上的 可操作性 檢查，除非設定了 setForce 選項。
  3. 如果需要，將元素捲動到檢視範圍。
  4. 使用 Page.mouse() 在元素中心點擊。
  5. 確保元素現在已取消核取。否則，此方法會拋出錯誤。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會擲出例外。

當所有步驟組合起來未在指定的 setTimeout 期間完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

waitFor​

新增於：v1.16 locator.waitFor

當定位器指定的元素滿足 setState 選項時傳回。

如果目標元素已滿足條件，則此方法會立即傳回。否則，會等待最多 setTimeout 毫秒，直到滿足條件為止。

用法

Locator orderSent = page.locator("#order-sent");
orderSent.waitFor();

引數

  • options Locator.WaitForOptions (選用)

    • setState enum WaitForSelectorState { ATTACHED, DETACHED, VISIBLE, HIDDEN } (選用)#

      預設為 'visible'。可以是下列其中一項

      • 'attached' - 等待元素出現在 DOM 中。
      • 'detached' - 等待元素未出現在 DOM 中。
      • 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，並且不被視為可見。
      • 'hidden' - 等待元素從 DOM 中分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。

    • setTimeout double (選用)#

      最大時間（毫秒）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更預設值。

傳回

已棄用​

elementHandle​

新增於：v1.14 locator.elementHandle
不建議使用

始終偏好使用 Locator 和 Web 斷言，而不是 ElementHandle，因為後者本質上具有競爭性。

將給定的定位器解析為第一個相符的 DOM 元素。如果沒有相符的元素，則等待一個。如果有多個元素符合定位器，則拋出錯誤。

用法

Locator.elementHandle();
Locator.elementHandle(options);

引數

傳回

elementHandles​

新增於：v1.14 locator.elementHandles
不建議使用

始終偏好使用 Locator 和 Web 斷言，而不是 ElementHandle，因為後者本質上具有競爭性。

將給定的定位器解析為所有相符的 DOM 元素。如果沒有相符的元素，則傳回空清單。

用法

Locator.elementHandles();

傳回

type​

新增於：v1.14 locator.type
已棄用

在大多數情況下，您應該改用 Locator.fill()。只有當頁面上有特殊的鍵盤處理時，才需要逐個按下按鍵 - 在這種情況下，請使用 Locator.pressSequentially()。

聚焦元素，然後針對文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。

若要按下特殊按鍵，例如 Control 或 ArrowDown，請使用 Locator.press()。

用法

引數

  • text String#

    要輸入到聚焦元素中的文字。

  • options Locator.TypeOptions (選用)

傳回