跳到主要內容

Locator

定位器是 Playwright 自動等待和重試能力的核心部分。簡而言之，定位器代表一種在任何時刻在頁面上尋找元素的方式。可以使用 page.locator() 方法建立定位器。

了解更多關於定位器的資訊.

方法​

all​

新增於：v1.29 locator.all

當定位器指向元素列表時，這會返回一個定位器陣列，指向它們各自的元素。

注意

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

當元素列表動態變更時，locator.all() 將產生不可預測且不穩定的結果。

當元素列表穩定但動態載入時，請等待完整列表載入完成後再呼叫 locator.all()。

用法

for li in page.get_by_role('listitem').all():
  li.click();

返回

all_inner_texts​

新增於：v1.14 locator.all_inner_texts

返回所有符合節點的 node.innerText 值陣列。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 expect(locator).to_have_text() 並搭配 use_inner_text 選項，以避免不穩定性。請參閱斷言指南以了解更多詳細資訊。

用法

texts = page.get_by_role("link").all_inner_texts()

返回

all_text_contents​

新增於：v1.14 locator.all_text_contents

返回所有符合節點的 node.textContent 值陣列。

斷言文字

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

用法

texts = page.get_by_role("link").all_text_contents()

返回

and_​

新增於：v1.34 locator.and_

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

用法

以下範例找到一個具有特定標題的按鈕。

button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))

參數

  • locator Locator#

    要符合的其他定位器。

返回

aria_snapshot​

新增於：v1.49 locator.aria_snapshot

擷取給定元素的 aria 快照。閱讀更多關於 aria 快照以及 expect(locator).to_match_aria_snapshot() 的資訊，以了解對應的斷言。

用法

page.get_by_role("link").aria_snapshot()

參數

返回

詳細資訊

此方法擷取給定元素的 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(**kwargs)

參數

返回

bounding_box​

新增於：v1.14 locator.bounding_box

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

用法

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

參數

返回

  • NoneType | Dict#

    • x float

      元素在像素中的 x 座標。

    • y float

      元素在像素中的 y 座標。

    • width float

      元素在像素中的寬度。

    • height float

      元素在像素中的高度。

詳細資訊

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

來自子框架的元素返回相對於主框架的邊界框，與 Element.getBoundingClientRect 不同。

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

check​

新增於：v1.14 locator.check

確保已選取核取方塊或 radio 元素。

用法

page.get_by_role("checkbox").check()

參數

  • force bool (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。

返回

詳細資訊

執行以下步驟

  1. 確保元素是核取方塊或 radio 輸入。如果不是，此方法會拋出錯誤。如果元素已選取，此方法會立即返回。
  2. 等待元素的可操作性檢查，除非設定 force 選項。
  3. 如果需要，將元素捲動到視野中。
  4. 使用 page.mouse 在元素中心點擊。
  5. 確保元素現在已選取。如果不是，此方法會拋出錯誤。

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

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

clear​

新增於：v1.28 locator.clear

清除輸入欄位。

用法

page.get_by_role("textbox").clear()

參數

返回

詳細資訊

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

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

click​

新增於：v1.14 locator.click

點擊元素。

用法

點擊按鈕

page.get_by_role("button").click()

在畫布上的特定位置按 Shift 鍵 + 滑鼠右鍵點擊

page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

參數

  • button "left" | "right" | "middle" (選填)#

    預設為 left。

  • click_count int (選填)#

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

  • delay float (選填)#

    mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設值為 0。

  • force bool (選填)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項未來將預設為 true。

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

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 設定為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

返回

詳細資訊

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

  1. 等待元素的可操作性檢查，除非設定 force 選項。
  2. 如果需要，將元素捲動到視野中。
  3. 使用 page.mouse 在元素中心點擊，或在指定的 position。
  4. 等待啟動的導航成功或失敗，除非設定 no_wait_after 選項。

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

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

count​

新增於：v1.14 locator.count

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

斷言數量

如果您需要在頁面上斷言元素數量，請優先使用 expect(locator).to_have_count() 以避免不穩定性。請參閱斷言指南以了解更多詳細資訊。

用法

count = page.get_by_role("listitem").count()

返回

dblclick​

新增於：v1.14 locator.dblclick

雙擊元素。

用法

locator.dblclick()
locator.dblclick(**kwargs)

參數

  • button "left" | "right" | "middle" (選填)#

    預設為 left。

  • delay float (選填)#

    mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設值為 0。

  • force bool (選填)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 設定為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

返回

詳細資訊

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

  1. 等待元素的可操作性檢查，除非設定 force 選項。
  2. 如果需要，將元素捲動到視野中。
  3. 使用 page.mouse 在元素中心雙擊，或在指定的 position。

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

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

注意

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

dispatch_event​

新增於：v1.14 locator.dispatch_event

以程式方式在符合的元素上觸發事件。

用法

locator.dispatch_event("click")

參數

返回

詳細資訊

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

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

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

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

data_transfer = page.evaluate_handle("new DataTransfer()")
locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

drag_to​

新增於：v1.18 locator.drag_to

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

用法

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

source.drag_to(target)
# or specify exact positions relative to the top-left corners of the elements:
source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

參數

  • target Locator#

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

  • force bool (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • source_position Dict (選填)#

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

  • target_position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。

返回

詳細資訊

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

evaluate​

新增於：v1.14 locator.evaluate

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

用法

參數

返回

詳細資訊

返回 expression 的返回值，以符合的元素作為第一個引數調用，並以 arg 作為第二個引數。

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

如果 expression 拋出錯誤或拒絕，此方法會拋出錯誤。

evaluate_all​

新增於：v1.14 locator.evaluate_all

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

用法

locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

參數

  • expression str#

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

  • arg EvaluationArgument (選填)#

    傳遞至 expression 的選填參數。

返回

詳細資訊

傳回 expression 的傳回值，此函式會以所有匹配的元素陣列作為第一個參數，並以 arg 作為第二個參數來呼叫。

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

如果 expression 拋出錯誤或拒絕，此方法也會拋出錯誤。

evaluate_handle​

新增於：v1.14 locator.evaluate_handle

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

用法

locator.evaluate_handle(expression)
locator.evaluate_handle(expression, **kwargs)

參數

返回

詳細資訊

以 JSHandle 形式傳回 expression 的傳回值，此函式會以匹配的元素作為第一個參數，並以 arg 作為第二個參數來呼叫。

locator.evaluate() 和 locator.evaluate_handle() 之間唯一的區別在於，locator.evaluate_handle() 傳回 JSHandle。

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

如果 expression 拋出錯誤或拒絕，此方法也會拋出錯誤。

更多詳細資訊，請參閱 page.evaluate_handle()。

fill​

新增於：v1.14 locator.fill

為輸入欄位設定值。

用法

page.get_by_role("textbox").fill("example value")

參數

返回

詳細資訊

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

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

若要傳送細緻的鍵盤事件，請使用 locator.press_sequentially()。

filter​

新增於：v1.22 locator.filter

此方法根據選項縮小現有的定位器範圍，例如依文字篩選。它可以鏈式調用以進行多次篩選。

用法

row_locator = page.locator("tr")
# ...
row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

參數

  • has Locator (選填)#

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

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

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

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

    匹配不包含與內部定位器匹配的元素的元素。內部定位器是針對外部定位器查詢的。例如，不包含 div 的 article 會匹配 <article><span>Playwright</span></article>。

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

  • has_not_text str | Pattern (選填)新增於：v1.33#

    匹配在內部某處（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞 [字串] 時，匹配會忽略大小寫並搜尋子字串。

  • has_text str | Pattern (選填)#

    匹配在內部某處（可能在子元素或後代元素中）包含指定文字的元素。當傳遞 [字串] 時，匹配會忽略大小寫並搜尋子字串。例如，"Playwright" 會匹配 <article><div>Playwright</div></article>。

  • visible bool (選填)新增於：v1.51#

    僅匹配可見或不可見的元素。

返回

focus​

新增於：v1.14 locator.focus

在匹配的元素上呼叫 focus。

用法

locator.focus()
locator.focus(**kwargs)

參數

返回

frame_locator​

新增於：v1.17 locator.frame_locator

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

用法

locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

參數

  • selector str#

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

返回

get_attribute​

新增於：v1.14 locator.get_attribute

傳回匹配元素的屬性值。

斷言屬性

如果您需要斷言元素的屬性，建議優先使用 expect(locator).to_have_attribute() 以避免不穩定性。有關更多詳細資訊，請參閱 斷言指南。

用法

locator.get_attribute(name)
locator.get_attribute(name, **kwargs)

參數

返回

get_by_alt_text​

新增於：v1.27 locator.get_by_alt_text

允許通過元素的替代文字 (alt text) 定位元素。

用法

例如，此方法將通過替代文字 "Playwright logo" 找到圖片

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

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配項：區分大小寫且完全符合字串。預設為 false。當通過正則表達式定位時，此選項會被忽略。請注意，完全匹配仍然會修剪空白。

返回

get_by_label​

新增於：v1.27 locator.get_by_label

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

用法

例如，此方法將在以下 DOM 中通過標籤 "Username" 和 "Password" 找到輸入框

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

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配項：區分大小寫且完全符合字串。預設為 false。當通過正則表達式定位時，此選項會被忽略。請注意，完全匹配仍然會修剪空白。

返回

get_by_placeholder​

新增於：v1.27 locator.get_by_placeholder

允許通過 placeholder 文字定位輸入元素。

用法

例如，考慮以下 DOM 結構。

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

您可以在通過 placeholder 文字定位輸入框後填寫內容

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

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配項：區分大小寫且完全符合字串。預設為 false。當通過正則表達式定位時，此選項會被忽略。請注意，完全匹配仍然會修剪空白。

返回

get_by_role​

新增於：v1.27 locator.get_by_role

允許通過其 ARIA role、ARIA 屬性 和 易讀名稱 定位元素。

用法

考慮以下 DOM 結構。

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

您可以通過每個元素的隱含 role 定位它們

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

參數

  • role "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 role。

  • checked bool (選填)#

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

    瞭解更多關於 aria-checked 的資訊。

  • disabled bool (選填)#

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

    注意

    與大多數其他屬性不同，disabled 是通過 DOM 階層繼承的。瞭解更多關於 aria-disabled 的資訊。

  • exact bool (選填)新增於：v1.28#

    是否完全匹配 name：區分大小寫且完全符合字串。預設為 false。當 name 是正則表達式時，此選項會被忽略。請注意，完全匹配仍然會修剪空白。

  • expanded bool (選填)#

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

    瞭解更多關於 aria-expanded 的資訊。

  • include_hidden bool (選填)#

    控制是否匹配隱藏元素的選項。預設情況下，只有非隱藏元素（如 ARIA 定義）會被 role 選擇器匹配。

    瞭解更多關於 aria-hidden 的資訊。

  • level int (選填)#

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

    瞭解更多關於 aria-level 的資訊。

  • name str | Pattern (選填)#

    用於匹配 易讀名稱 的選項。預設情況下，匹配會忽略大小寫並搜尋子字串，使用 exact 來控制此行為。

    瞭解更多關於 易讀名稱 的資訊。

  • pressed bool (選填)#

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

    瞭解更多關於 aria-pressed 的資訊。

  • selected bool (選填)#

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

    瞭解更多關於 aria-selected 的資訊。

返回

詳細資訊

Role 選擇器**不能取代**可訪問性審核和一致性測試，而是提供關於 ARIA 指南的早期回饋。

許多 html 元素都有隱含 定義的 role，role 選擇器可以識別它。您可以在這裡找到所有 支援的 role。ARIA 指南**不建議**通過將 role 和/或 aria-* 屬性設定為預設值來重複隱含的 role 和屬性。

get_by_test_id​

新增於：v1.27 locator.get_by_test_id

通過測試 ID 定位元素。

用法

考慮以下 DOM 結構。

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

您可以通過元素的測試 ID 定位它

page.get_by_test_id("directions").click()

參數

返回

詳細資訊

預設情況下，data-testid 屬性用作測試 ID。如有必要，請使用 selectors.set_test_id_attribute() 配置不同的測試 ID 屬性。

get_by_text​

新增於：v1.27 locator.get_by_text

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

另請參閱 locator.filter()，它允許通過其他條件（如可訪問的 role）進行匹配，然後通過文字內容進行篩選。

用法

考慮以下 DOM 結構

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

您可以通過文字子字串、完全匹配字串或正則表達式進行定位

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配項：區分大小寫且完全符合字串。預設為 false。當通過正則表達式定位時，此選項會被忽略。請注意，完全匹配仍然會修剪空白。

返回

詳細資訊

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

類型為 button 和 submit 的輸入元素會通過它們的 value 而不是文字內容進行匹配。例如，通過文字 "Log in" 定位會匹配 <input type=button value="Log in">。

get_by_title​

新增於：v1.27 locator.get_by_title

允許通過元素的 title 屬性定位元素。

用法

考慮以下 DOM 結構。

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

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

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

參數

  • text str | Pattern#

    用於定位元素的文字。

  • exact bool (選填)#

    是否尋找完全匹配項：區分大小寫且完全符合字串。預設為 false。當通過正則表達式定位時，此選項會被忽略。請注意，完全匹配仍然會修剪空白。

返回

highlight​

新增於：v1.20 locator.highlight

在螢幕上突出顯示相應的元素。用於除錯很有用，不要提交使用 locator.highlight() 的程式碼。

用法

locator.highlight()

返回

hover​

新增於：v1.14 locator.hover

懸停在匹配的元素之上。

用法

page.get_by_role("link").hover()

參數

  • force bool (選填)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)新增於：v1.28#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 設定為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

返回

詳細資訊

此方法通過執行以下步驟懸停在元素之上

  1. 等待元素上的 可操作性 檢查，除非設定了 force 選項。
  2. 如果需要，將元素捲動到視野中。
  3. 使用 page.mouse 懸停在元素的中心，或指定的 position。

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

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

inner_html​

新增於：v1.14 locator.inner_html

傳回 element.innerHTML。

用法

locator.inner_html()
locator.inner_html(**kwargs)

參數

返回

inner_text​

新增於：v1.14 locator.inner_text

傳回 element.innerText。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 expect(locator).to_have_text() 並搭配 use_inner_text 選項，以避免不穩定性。請參閱斷言指南以了解更多詳細資訊。

用法

locator.inner_text()
locator.inner_text(**kwargs)

參數

返回

input_value​

新增於：v1.14 locator.input_value

傳回匹配的 <input> 或 <textarea> 或 <select> 元素的值。

斷言值

如果您需要斷言輸入值，建議優先使用 expect(locator).to_have_value() 以避免不穩定性。有關更多詳細資訊，請參閱 斷言指南。

用法

value = page.get_by_role("textbox").input_value()

參數

返回

詳細資訊

如果元素不是 input、textarea 或 select，則拋出錯誤。但是，如果元素位於具有關聯 控制項 的 <label> 元素內，則傳回該控制項的值。

is_checked​

新增於：v1.14 locator.is_checked

傳回元素是否被選中。如果元素不是複選框或單選輸入框，則拋出錯誤。

斷言選中狀態

如果您需要斷言複選框是否被選中，建議優先使用 expect(locator).to_be_checked() 以避免不穩定性。有關更多詳細資訊，請參閱 斷言指南。

用法

checked = page.get_by_role("checkbox").is_checked()

參數

返回

is_disabled​

新增於：v1.14 locator.is_disabled

傳回元素是否被禁用，與 enabled 相反。

斷言禁用狀態

如果您需要斷言元素是否被禁用，建議優先使用 expect(locator).to_be_disabled() 以避免不穩定性。有關更多詳細資訊，請參閱 斷言指南。

用法

disabled = page.get_by_role("button").is_disabled()

參數

返回

is_editable​

新增於：v1.14 locator.is_editable

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

斷言可編輯狀態

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

用法

editable = page.get_by_role("textbox").is_editable()

參數

返回

is_enabled​

新增於：v1.14 locator.is_enabled

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

斷言啟用狀態

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

用法

enabled = page.get_by_role("button").is_enabled()

參數

返回

is_hidden​

新增於：v1.14 locator.is_hidden

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

斷言可見性

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

用法

hidden = page.get_by_role("button").is_hidden()

參數

  • timeout float (選填)#

    已棄用

    此選項會被忽略。locator.is_hidden() 不會等待元素變成隱藏狀態，而是立即返回。

返回

is_visible​

新增於：v1.14 locator.is_visible

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

斷言可見性

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

用法

visible = page.get_by_role("button").is_visible()

參數

  • timeout float (選填)#

    已棄用

    此選項會被忽略。locator.is_visible() 不會等待元素變成可見狀態，而是立即返回。

返回

locator​

新增於：v1.14 locator.locator

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

了解更多關於定位器的資訊.

用法

locator.locator(selector_or_locator)
locator.locator(selector_or_locator, **kwargs)

參數

  • selector_or_locator str | Locator#

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

  • has Locator (選填)#

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

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

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

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

    匹配不包含與內部定位器匹配的元素的元素。內部定位器是針對外部定位器查詢的。例如，不包含 div 的 article 會匹配 <article><span>Playwright</span></article>。

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

  • has_not_text str | Pattern (選填)新增於：v1.33#

    匹配在內部某處（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞 [字串] 時，匹配會忽略大小寫並搜尋子字串。

  • has_text str | Pattern (選填)#

    匹配在內部某處（可能在子元素或後代元素中）包含指定文字的元素。當傳遞 [字串] 時，匹配會忽略大小寫並搜尋子字串。例如，"Playwright" 會匹配 <article><div>Playwright</div></article>。

返回

nth​

新增於：v1.14 locator.nth

返回指向第 n 個匹配元素的定位器。它是從零開始的索引，nth(0) 選擇第一個元素。

用法

banana = page.get_by_role("listitem").nth(2)

參數

返回

or_​

新增於：v1.33 locator.or_

創建一個定位器，匹配符合兩個定位器之一或兩者的所有元素。

請注意，當兩個定位器都匹配到內容時，產生的定位器將有多個匹配項，可能會導致定位器嚴格性違規。

用法

考慮這樣一個情境：您想要點擊「New email」（新郵件）按鈕，但有時會彈出安全設定對話框。在這種情況下，您可以等待「New email」按鈕或對話框出現，然後採取相應的措施。

注意

如果「New email」按鈕和安全對話框都出現在螢幕上，「or」定位器將同時匹配它們，可能會拋出「嚴格模式違規」錯誤。在這種情況下，您可以使用 locator.first 僅匹配其中一個。

new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if (dialog.is_visible()):
  page.get_by_role("button", name="Dismiss").click()
new_email.click()

參數

  • locator Locator#

    要匹配的替代定位器。

返回

press​

新增於：v1.14 locator.press

聚焦匹配的元素並按下按鍵組合。

用法

page.get_by_role("textbox").press("Backspace")

參數

  • key str#

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

  • delay float (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項未來將預設為 true。

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

返回

詳細資訊

聚焦元素，然後使用 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" 等快捷鍵。當使用修飾鍵指定時，修飾鍵會被按下並保持按住狀態，同時按下後續的按鍵。

press_sequentially​

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

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

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

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

用法

locator.press_sequentially("hello") # types instantly
locator.press_sequentially("world", delay=100) # types slower, like a user

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

locator = page.get_by_label("Password")
locator.press_sequentially("my password")
locator.press("Enter")

參數

  • text str#

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

  • delay float (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

返回

screenshot​

新增於：v1.14 locator.screenshot

拍攝符合定位器的元素的螢幕截圖。

用法

page.get_by_role("link").screenshot()

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

page.get_by_role("link").screenshot(animations="disabled", path="link.png")

參數

  • animations "disabled" | "allow" (選填)#

    當設定為 "disabled" 時，會停止 CSS 動畫、CSS 過渡和 Web 動畫。動畫會根據其持續時間獲得不同的處理：

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

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

  • caret "hide" | "initial" (選填)#

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

  • mask List[Locator] (選填)#

    指定在拍攝螢幕截圖時應遮罩的定位器。遮罩元素將被粉紅色方框 #FF00FF（可通過 mask_color 自訂）覆蓋，完全遮蓋其邊界框。遮罩也適用於不可見的元素，請參閱僅匹配可見元素以停用該功能。

  • mask_color str (選填)新增於：v1.35#

    指定遮罩元素的覆蓋框顏色，採用 CSS 顏色格式。預設顏色為粉紅色 #FF00FF。

  • omit_background bool (選填)#

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

  • path Union[str, pathlib.Path] (選填)#

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

  • quality int (選填)#

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

  • scale "css" | "device" (選填)#

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

    預設為 "device"。

  • style str (選填)新增於：v1.41#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • type "png" | "jpeg" (選填)#

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

返回

詳細資訊

此方法捕獲頁面的螢幕截圖，裁剪為符合定位器的特定元素的大小和位置。如果元素被其他元素覆蓋，則實際上不會在螢幕截圖上可見。如果元素是可滾動容器，則只有當前滾動的內容將在螢幕截圖上可見。

此方法等待可操作性檢查，然後在拍攝螢幕截圖之前將元素滾動到視窗中。如果元素從 DOM 中分離，則此方法會拋出錯誤。

返回包含捕獲的螢幕截圖的緩衝區。

scroll_into_view_if_needed​

新增於：v1.14 locator.scroll_into_view_if_needed

此方法等待可操作性檢查，然後嘗試將元素滾動到視窗中，除非根據 IntersectionObserver 的 ratio 定義，元素已完全可見。

請參閱滾動以獲取其他滾動方式。

用法

locator.scroll_into_view_if_needed()
locator.scroll_into_view_if_needed(**kwargs)

參數

返回

select_option​

新增於：v1.14 locator.select_option

在 <select> 中選擇選項。

用法

<select multiple>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>
# single selection matching the value or label
element.select_option("blue")
# single selection matching the label
element.select_option(label="blue")
# multiple selection for blue, red and second option
element.select_option(value=["red", "green", "blue"])

參數

  • force bool (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • element ElementHandle | List[ElementHandle] (選填)#

    要選擇的選項元素。選填。

  • index int | List[int] (選填)#

    要通過索引選擇的選項。選填。

  • value str | List[str] (選填)#

    要通過值選擇的選項。如果 <select> 具有 multiple 屬性，則會選擇所有給定的選項，否則只會選擇第一個符合其中一個傳遞選項的選項。選填。

  • label str | List[str] (選填)#

    要通過標籤選擇的選項。如果 <select> 具有 multiple 屬性，則會選擇所有給定的選項，否則只會選擇第一個符合其中一個傳遞選項的選項。選填。

返回

詳細資訊

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

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

返回已成功選擇的選項值陣列。

一旦所有提供的選項都已被選擇，則觸發 change 和 input 事件。

select_text​

新增於：v1.14 locator.select_text

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

如果元素位於具有關聯 control 的 <label> 元素內，則聚焦並選擇 control 中的文字。

用法

locator.select_text()
locator.select_text(**kwargs)

參數

返回

set_checked​

新增於：v1.15 locator.set_checked

設定核取方塊或單選按鈕元素的狀態。

用法

page.get_by_role("checkbox").set_checked(True)

參數

  • checked bool#

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

  • force bool (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。

返回

詳細資訊

此方法通過執行以下步驟來勾選或取消勾選元素：

  1. 確保匹配的元素是核取方塊或單選輸入框。如果不是，此方法會拋出錯誤。
  2. 如果元素已處於正確的勾選狀態，此方法會立即返回。
  3. 等待對匹配元素進行可操作性檢查，除非設定了 force 選項。如果元素在檢查期間分離，則會重試整個操作。
  4. 如果需要，將元素捲動到視野中。
  5. 使用 page.mouse 在元素中心點擊。
  6. 確保元素現在已勾選或取消勾選。如果不是，此方法會拋出錯誤。

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

set_input_files​

新增於：v1.14 locator.set_input_files

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

用法

# Select one file
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# Select multiple files
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# Select a directory
page.get_by_label("Upload directory").set_input_files('mydir')

# Remove all the selected files
page.get_by_label("Upload file").set_input_files([])

# Upload buffer from memory
page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

參數

返回

詳細資訊

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

此方法預期 Locator 指向一個 input 元素。但是，如果元素位於具有關聯 control 的 <label> 元素內，則會改為以 control 為目標。

tap​

新增於：v1.14 locator.tap

對符合 locator 的元素執行 tap 手勢。如需透過手動分派觸控事件來模擬其他手勢的範例，請參閱模擬舊版觸控事件頁面。

用法

locator.tap()
locator.tap(**kwargs)

參數

  • force bool (選填)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 設定為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

返回

詳細資訊

此方法透過執行下列步驟來 tap 元素

  1. 等待元素上的可操作性檢查，除非設定了 force 選項。
  2. 如果需要，將元素捲動到視野中。
  3. 使用 page.touchscreen 來 tap 元素的中心，或指定的 position。

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

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

注意

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

text_content​

新增於：v1.14 locator.text_content

傳回 node.textContent。

斷言文字

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

用法

locator.text_content()
locator.text_content(**kwargs)

參數

返回

uncheck​

新增於：v1.14 locator.uncheck

確保已取消勾選核取方塊或選項按鈕元素。

用法

page.get_by_role("checkbox").uncheck()

參數

  • force bool (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • position Dict (選填)#

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial bool (選填)#

    設定後，此方法僅執行可操作性檢查並跳過動作。預設值為 false。適用於等待元素準備好執行動作，而無需實際執行它。

返回

詳細資訊

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

  1. 確保元素是核取方塊或選項輸入。如果不是，此方法會擲回錯誤。如果元素已取消勾選，此方法會立即傳回。
  2. 等待元素上的可操作性檢查，除非設定了 force 選項。
  3. 如果需要，將元素捲動到視野中。
  4. 使用 page.mouse 在元素中心點擊。
  5. 確保元素現在已取消勾選。如果不是，此方法會擲回錯誤。

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

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

wait_for​

新增於：v1.16 locator.wait_for

當 locator 指定的元素滿足 state 選項時傳回。

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

用法

order_sent = page.locator("#order-sent")
order_sent.wait_for()

參數

  • state "attached" | "detached" | "visible" | "hidden" (選填)#

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

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

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

返回

屬性​

content_frame​

新增於：v1.43 locator.content_frame

傳回指向與此 locator 相同 iframe 的 FrameLocator 物件。

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

對於反向操作，請使用 frame_locator.owner。

用法

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

返回

first​

新增於：v1.14 locator.first

傳回第一個符合元素的 locator。

用法

locator.first

返回

last​

新增於：v1.14 locator.last

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

用法

banana = page.get_by_role("listitem").last

返回

page​

新增於：v1.19 locator.page

此 locator 所屬的頁面。

用法

locator.page

返回

已棄用​

element_handle​

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

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

將給定的 locator 解析為第一個符合的 DOM 元素。如果沒有符合的元素，則等待一個。如果有多個元素符合 locator，則擲回錯誤。

用法

locator.element_handle()
locator.element_handle(**kwargs)

參數

返回

element_handles​

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

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

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

用法

locator.element_handles()

返回

type​

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

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

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

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

用法

參數

  • text str#

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

  • delay float (選填)#

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

  • no_wait_after bool (選填)#

    已棄用

    此選項沒有作用。

    此選項沒有作用。

  • timeout float (選填)#

    最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

返回