跳到主要內容

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 值陣列。

斷言文字

如果您需要在頁面上斷言文字，請優先使用具有 use_inner_text 選項的 expect(locator).to_have_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

確保已選取核取方塊或單選按鈕元素。

用法

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

參數

  • force bool (可選)#

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

  • no_wait_after bool (可選)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (可選)#

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

  • 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。傳遞零逾時會停用此功能。

clear​

新增於：v1.28 locator.clear

清除輸入欄位。

用法

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

參數

返回值

詳細資訊

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

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會擲回錯誤。但是，如果元素位於具有相關聯 control 的 <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 (可選)#

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

  • 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。傳遞零逾時會停用此功能。

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 (可選)#

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

  • 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。傳遞零逾時會停用此功能。

注意

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 (可選)#

    點擊來源元素上的這一點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。

  • target_position Dict (可選)#

    在目標元素上的這一點放下，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。

  • 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 程式碼，並將符合的元素作為引數。

用法

tweets = page.locator(".tweet .retweets")
assert tweets.evaluate("node => node.innerText") == "10 retweets"

參數

返回值

詳細資訊

傳回 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)

參數

返回值

詳細資訊

傳回 expression 的傳回值，型別為 JSHandle，此函式會以符合條件的元素作為第一個參數呼叫，並以 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")

參數

返回值

詳細資訊

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

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

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

filter​

新增於：v1.22 locator.filter

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

用法

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 (選填)#

    將方法的結果縮小到包含符合此相對 locator 的元素。例如，article 包含 text=Playwright 會符合 <article><div>Playwright</div></article>。

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

    請注意，外部和內部 locator 必須屬於同一個 frame。內部 locator 不得包含 FrameLocator。

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

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

    請注意，外部和內部 locator 必須屬於同一個 frame。內部 locator 不得包含 FrameLocator。

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

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

  • has_text str | Pattern (選填)#

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

返回值

focus​

新增於：v1.14 locator.focus

在符合條件的元素上呼叫 focus。

用法

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

參數

返回值

frame_locator​

新增於：v1.17 locator.frame_locator

當處理 iframe 時，您可以建立 frame locator，以進入 iframe 並允許在該 iframe 中定位元素

用法

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

參數

  • selector str#

    解析 DOM 元素時要使用的 selector。

返回值

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 文字定位元素。

用法

例如，此方法會依據 alt 文字 "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 (選填)#

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

    深入了解 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 selector **無法取代** 協助工具稽核和一致性測試，但可以提供關於 ARIA 指南的早期回饋。

許多 html 元素具有隱含的 定義 role，role selector 可以識別它。您可以在這裡找到所有支援的 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 (選填)#

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

  • timeout float (選填)#

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

  • trial bool (選填)#

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

返回值

詳細資訊

此方法透過執行以下步驟，將滑鼠懸停在元素上方

  1. 等待元素上的 actionability 檢查，除非設定 force 選項。
  2. 如果需要，將元素捲動到檢視畫面中。
  3. 使用 page.mouse 將滑鼠懸停在元素的中心，或指定的 position。

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

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

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。

斷言文字

如果您需要在頁面上斷言文字，請優先使用具有 use_inner_text 選項的 expect(locator).to_have_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，則會拋出錯誤。但是，如果元素位於具有關聯 control 的 <label> 元素內，則會傳回該 control 的值。

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

傳回元素是否隱藏，與visible相反。

斷言可見性

如果您需要斷言元素是否隱藏，建議使用 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 的子樹中尋找符合指定選擇器的元素。它也接受篩選選項，類似於 locator.filter() 方法。

深入了解定位器.

用法

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

參數

  • selector_or_locator 字串 | Locator#

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

  • has Locator (選填)#

    將方法的結果縮小到包含符合此相對 locator 的元素。例如，article 包含 text=Playwright 會符合 <article><div>Playwright</div></article>。

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

    請注意，外部和內部 locator 必須屬於同一個 frame。內部 locator 不得包含 FrameLocator。

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

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

    請注意，外部和內部 locator 必須屬於同一個 frame。內部 locator 不得包含 FrameLocator。

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

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

  • has_text 字串 | 模式 (Pattern) (選填)#

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

返回值

nth​

新增於：v1.14 locator.nth

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

用法

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

參數

返回值

or_​

新增於：v1.33 locator.or_

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

請注意，當兩個 locator 都比對到內容時，產生的 locator 將有多個比對結果，可能導致 locator 嚴格性違規。

用法

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

注意

如果「New email」按鈕和安全對話方塊都出現在螢幕上，「or」locator 將同時比對到它們，可能拋出「嚴格模式違規」錯誤。在這種情況下，您可以使用 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#

    要比對的替代 locator。

返回值

press​

新增於：v1.14 locator.press

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

用法

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

參數

  • key 字串#

    要按下的按鍵名稱或要產生的字元，例如 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 字串#

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

  • 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

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

用法

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

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

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

參數

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

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

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

    預設為 "allow"，保持動畫不變。

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

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

  • mask 列表[Locator] (選填)#

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

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

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

  • omit_background bool (選填)#

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

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

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

  • quality int (選填)#

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

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

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

    預設為 "device"。

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

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

  • timeout float (選填)#

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

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

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

返回值

詳細資訊

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

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

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

scroll_into_view_if_needed​

新增於：v1.14 locator.scroll_into_view_if_needed

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

請參閱 scrolling 以取得其他捲動方式。

用法

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</div>
  <option value="green">Green</div>
  <option value="blue">Blue</div>
</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 | 列表[ElementHandle] (選填)#

    要選取的選項元素。可選。

  • index int | 列表[int] (選填)#

    要依索引選取的選項。可選。

  • value 字串 | 列表[字串] (選填)#

    要依值選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有給定的選項，否則只會選取符合傳遞選項的第一個選項。可選。

  • label 字串 | 列表[字串] (選填)#

    要依標籤選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有給定的選項，否則只會選取符合傳遞選項的第一個選項。可選。

返回值

詳細資訊

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

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

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

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

select_text​

新增於：v1.14 locator.select_text

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

如果元素在具有關聯 control 的 <label> 元素內，則會聚焦於 control 並在 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 (選填)#

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

  • 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 元素。但是，如果元素位於具有關聯 控制項的 <label> 元素內，則會改為以控制項為目標。

tap​

新增於：v1.14 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 (選填)#

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

  • timeout float (選填)#

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

  • trial bool (選填)#

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

返回值

詳細資訊

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

  1. 等待元素上的可操作性檢查，除非設定了 force 選項。
  2. 如果需要，將元素捲動到檢視畫面中。
  3. 使用 page.touchscreen 點擊元素的中心，或指定的 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 (選填)#

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

  • 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

當定位器指定的元素滿足 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

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

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

對於反向操作，請使用 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.first

返回值

last​

新增於：v1.14 locator.last

傳回指向最後一個匹配元素的定位器。

用法

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

返回值

page​

新增於：v1.19 locator.page

此定位器所屬的頁面。

用法

locator.page

返回值

已棄用​

element_handle​

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

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

將給定的定位器解析為第一個匹配的 DOM 元素。如果沒有匹配的元素，則等待一個。如果多個元素匹配定位器，則擲回錯誤。

用法

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

參數

返回值

element_handles​

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

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

將給定的定位器解析為所有匹配的 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() 方法變更。

返回值