跳到主要內容

定位器

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

深入了解定位器.

方法​

all​

新增於：v1.29 locator.all

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

注意

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

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

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

用法

for (const li of await page.getByRole('listitem').all())
  await li.click();

返回

allInnerTexts​

新增於：v1.14 locator.allInnerTexts

返回所有匹配節點的 node.innerText 值陣列。

斷言文字

如果您需要在頁面上斷言文字，建議使用 expect(locator).toHaveText() 並搭配 useInnerText 選項，以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

const texts = await page.getByRole('link').allInnerTexts();

返回

allTextContents​

新增於：v1.14 locator.allTextContents

返回所有匹配節點的 node.textContent 值陣列。

斷言文字

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

用法

const texts = await page.getByRole('link').allTextContents();

返回

and​

新增於：v1.34 locator.and

建立一個定位器，該定位器同時匹配此定位器和參數定位器。

用法

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

const button = page.getByRole('button').and(page.getByTitle('Subscribe'));

參數

  • locator Locator#

    要匹配的其他定位器。

返回

ariaSnapshot​

新增於：v1.49 locator.ariaSnapshot

捕獲給定元素的 aria 快照。閱讀更多關於 aria 快照和 expect(locator).toMatchAriaSnapshot() 以獲取相應的斷言。

用法

await page.getByRole('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。

用法

await locator.blur();
await locator.blur(options);

參數

返回

boundingBox​

新增於：v1.14 locator.boundingBox

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

用法

const box = await page.getByRole('button').boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

參數

返回

詳細資訊

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

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

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

check​

新增於：v1.14 locator.check

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

用法

await page.getByRole('checkbox').check();

參數

  • options Object (可選)

    • force boolean (可選)#

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

    • noWaitAfter boolean (可選)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (可選)#

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

    • timeout number (可選)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (可選)#

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

返回

詳細資訊

執行以下步驟

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

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

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

clear​

新增於：v1.28 locator.clear

清除輸入欄位。

用法

await page.getByRole('textbox').clear();

參數

返回

詳細資訊

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

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

click​

新增於：v1.14 locator.click

點擊元素。

用法

點擊按鈕

await page.getByRole('button').click();

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

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

參數

  • options Object (可選)

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

      預設為 left。

    • clickCount number (可選)#

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

    • delay number (可選)#

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

    • force boolean (可選)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可選)#

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

    • noWaitAfter boolean (可選)#

      已棄用

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

      啟動導航的操作正在等待這些導航發生以及頁面開始載入。您可以通過設定此標誌來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法訪問的頁面。預設為 false。

    • position Object (可選)#

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

    • timeout number (可選)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (可選)#

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

返回

詳細資訊

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

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

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

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

contentFrame​

新增於：v1.43 locator.contentFrame

返回一個 FrameLocator 物件，該物件指向與此定位器相同的 iframe。

當您在某處獲得一個 Locator 物件，稍後想要與框架內的內容互動時，此功能很有用。

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

用法

const locator = page.locator('iframe[name="embedded"]');
// ...
const frameLocator = locator.contentFrame();
await frameLocator.getByRole('button').click();

返回

count​

新增於：v1.14 locator.count

返回與定位器匹配的元素數量。

斷言計數

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

用法

const count = await page.getByRole('listitem').count();

返回

dblclick​

新增於：v1.14 locator.dblclick

雙擊元素。

用法

await locator.dblclick();
await locator.dblclick(options);

參數

  • options Object (可選)

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

      預設為 left。

    • delay number (可選)#

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

    • force boolean (可選)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可選)#

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

    • noWaitAfter boolean (可選)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (可選)#

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

    • timeout number (可選)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (可選)#

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

返回

詳細資訊

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

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

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

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

注意

element.dblclick() 會分派兩個 click 事件和一個 dblclick 事件。

dispatchEvent​

新增於：v1.14 locator.dispatchEvent

以程式方式在匹配的元素上分派事件。

用法

await locator.dispatchEvent('click');

參數

返回

詳細資訊

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

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

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

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

const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await locator.dispatchEvent('dragstart', { dataTransfer });

dragTo​

新增於：v1.18 locator.dragTo

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

用法

const source = page.locator('#source');
const target = page.locator('#target');

await source.dragTo(target);
// or specify exact positions relative to the top-left corners of the elements:
await source.dragTo(target, {
  sourcePosition: { x: 34, y: 7 },
  targetPosition: { x: 10, y: 20 },
});

參數

  • target Locator#

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

  • options Object (可選)

    • force boolean (可選)#

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

    • noWaitAfter boolean (可選)#

      已棄用

      此選項無效。

      此選項無效。

    • sourcePosition Object (可選)#

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

    • targetPosition Object (可選)#

      在此點放下到目標元素上，相對於元素填充框的左上角。如果未指定，則使用元素的某些可見點。

    • timeout number (可選)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (可選)#

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

返回

詳細資訊

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

evaluate​

新增於：v1.14 locator.evaluate

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

用法

const tweets = page.locator('.tweet .retweets');
expect(await tweets.evaluate(node => node.innerText)).toBe('10 retweets');

參數

返回

詳細資訊

傳回 pageFunction 的傳回值，該函式會以符合的元素作為第一個引數，並以 arg 作為第二個引數來呼叫。

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

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

evaluateAll​

新增於：v1.14 locator.evaluateAll

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

用法

const locator = page.locator('div');
const moreThanTen = await locator.evaluateAll((divs, min) => divs.length > min, 10);

參數

返回

詳細資訊

傳回 pageFunction 的傳回值，該函式會以所有符合元素的陣列作為第一個引數，並以 arg 作為第二個引數來呼叫。

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

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

evaluateHandle​

新增於：v1.14 locator.evaluateHandle

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

用法

await locator.evaluateHandle(pageFunction);
await locator.evaluateHandle(pageFunction, arg, options);

參數

返回

詳細資訊

將 pageFunction 的傳回值作為 JSHandle 傳回，該函式會以符合的元素作為第一個引數，並以 arg 作為第二個引數來呼叫。

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

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

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

有關更多詳細資訊，請參閱 page.evaluateHandle()。

fill​

新增於：v1.14 locator.fill

設定輸入欄位的值。

用法

await page.getByRole('textbox').fill('example value');

參數

返回

詳細資訊

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

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

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

filter​

新增於：v1.22 locator.filter

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

用法

const rowLocator = page.locator('tr');
// ...
await rowLocator
    .filter({ hasText: 'text in column 1' })
    .filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
    .screenshot();

參數

  • options Object (可選)

    • has Locator (選填)#

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

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

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

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

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

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

    • hasNotText string | RegExp (選填)新增於：v1.33#

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

    • hasText string | RegExp (選填)#

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

返回

first​

新增於：v1.14 locator.first

傳回第一個匹配元素的定位器。

用法

locator.first();

返回

focus​

新增於：v1.14 locator.focus

在匹配的元素上呼叫 focus。

用法

await locator.focus();
await locator.focus(options);

參數

返回

frameLocator​

新增於：v1.17 locator.frameLocator

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

用法

const locator = page.frameLocator('iframe').getByText('Submit');
await locator.click();

參數

  • selector string#

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

返回

getAttribute​

新增於：v1.14 locator.getAttribute

傳回匹配元素的屬性值。

斷言屬性

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

用法

await locator.getAttribute(name);
await locator.getAttribute(name, options);

參數

返回

getByAltText​

新增於：v1.27 locator.getByAltText

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

用法

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

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

參數

  • text string | RegExp#

    用於定位元素的文字。

  • options Object (可選)

    • exact 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">
await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

參數

  • text string | RegExp#

    用於定位元素的文字。

  • options Object (可選)

    • exact boolean (選填)#

      是否尋找完全匹配：區分大小寫和全字串。預設為 false。以規則運算式定位時會忽略。請注意，完全匹配仍然會修剪空白字元。

返回

getByPlaceholder​

新增於：v1.27 locator.getByPlaceholder

允許依據 placeholder 文字定位輸入元素。

用法

例如，考慮以下 DOM 結構。

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

您可以在依據 placeholder 文字定位輸入框後填寫它

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

參數

  • text string | RegExp#

    用於定位元素的文字。

  • options Object (可選)

    • exact boolean (選填)#

      是否尋找完全匹配：區分大小寫和全字串。預設為 false。以規則運算式定位時會忽略。請注意，完全匹配仍然會修剪空白字元。

返回

getByRole​

新增於：v1.27 locator.getByRole

允許依據其 ARIA 角色、ARIA 屬性 和 易於存取的名稱 定位元素。

用法

考慮以下 DOM 結構。

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

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

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).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 角色。

  • options Object (可選)

    • checked boolean (選填)#

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

      深入瞭解 aria-checked。

    • disabled boolean (選填)#

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

      注意

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

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

      是否完全匹配 name：區分大小寫和全字串。預設為 false。當 name 為規則運算式時會忽略。請注意，完全匹配仍然會修剪空白字元。

    • expanded boolean (選填)#

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

      深入瞭解 aria-expanded。

    • includeHidden boolean (選填)#

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

      深入瞭解 aria-hidden。

    • level number (選填)#

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

      深入瞭解 aria-level。

    • name string | RegExp (選填)#

      用於匹配易於存取的名稱的選項。預設情況下，匹配不區分大小寫，並搜尋子字串，使用 exact 來控制此行為。

      深入瞭解 易於存取的名稱。

    • pressed boolean (選填)#

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

      深入瞭解 aria-pressed。

    • selected 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 定位它

await page.getByTestId('directions').click();

參數

返回

詳細資訊

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

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

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', { exact: true });

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

// Matches second <div>
page.getByText(/^hello$/i);

參數

  • text string | RegExp#

    用於定位元素的文字。

  • options Object (可選)

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

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

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

參數

  • text string | RegExp#

    用於定位元素的文字。

  • options Object (可選)

    • exact boolean (選填)#

      是否尋找完全匹配：區分大小寫和全字串。預設為 false。以規則運算式定位時會忽略。請注意，完全匹配仍然會修剪空白字元。

返回

highlight​

新增於：v1.20 locator.highlight

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

用法

await locator.highlight();

返回

hover​

新增於：v1.14 locator.hover

將滑鼠懸停在匹配的元素上。

用法

await page.getByRole('link').hover();

參數

  • options Object (可選)

    • force boolean (選填)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (選填)#

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

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

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

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

    • timeout number (選填)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (選填)#

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

返回

詳細資訊

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

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

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

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

innerHTML​

新增於：v1.14 locator.innerHTML

傳回 element.innerHTML。

用法

await locator.innerHTML();
await locator.innerHTML(options);

參數

返回

innerText​

新增於：v1.14 locator.innerText

傳回 element.innerText。

斷言文字

如果您需要在頁面上斷言文字，建議使用 expect(locator).toHaveText() 並搭配 useInnerText 選項，以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

await locator.innerText();
await locator.innerText(options);

參數

返回

inputValue​

新增於：v1.14 locator.inputValue

傳回符合的 <input> 或 <textarea> 或 <select> 元素的值。

斷言值

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

用法

const value = await page.getByRole('textbox').inputValue();

參數

返回

詳細資訊

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

isChecked​

新增於：v1.14 locator.isChecked

傳回元素是否已選取。如果元素不是核取方塊或單選按鈕輸入，則拋出錯誤。

斷言選取狀態

如果您需要斷言核取方塊是否已選取，建議優先使用 expect(locator).toBeChecked()，以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

const checked = await page.getByRole('checkbox').isChecked();

參數

返回

isDisabled​

新增於：v1.14 locator.isDisabled

傳回元素是否已停用，與已啟用相反。

斷言停用狀態

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

用法

const disabled = await page.getByRole('button').isDisabled();

參數

返回

isEditable​

新增於：v1.14 locator.isEditable

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

斷言可編輯狀態

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

用法

const editable = await page.getByRole('textbox').isEditable();

參數

返回

isEnabled​

新增於：v1.14 locator.isEnabled

傳回元素是否已啟用。

斷言啟用狀態

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

用法

const enabled = await page.getByRole('button').isEnabled();

參數

返回

isHidden​

新增於：v1.14 locator.isHidden

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

斷言可見性

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

用法

const hidden = await page.getByRole('button').isHidden();

參數

返回

isVisible​

新增於：v1.14 locator.isVisible

傳回元素是否可見。

斷言可見性

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

用法

const visible = await page.getByRole('button').isVisible();

參數

返回

last​

新增於：v1.14 locator.last

傳回指向最後一個符合元素的定位器。

用法

const banana = await page.getByRole('listitem').last();

返回

locator​

新增於：v1.14 locator.locator

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

深入了解定位器.

用法

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

參數

  • selectorOrLocator string | Locator#

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

  • options Object (可選)

    • has Locator (選用)#

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

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

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

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

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

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

    • hasNotText string | RegExp (選填)新增於：v1.33#

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

    • hasText string | RegExp (選用)#

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

返回

nth​

新增於：v1.14 locator.nth

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

用法

const banana = await page.getByRole('listitem').nth(2);

參數

返回

or​

新增於：v1.33 locator.or

建立一個定位器，比對符合兩個定位器之一或兩者的所有元素。

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

用法

考慮這樣一個情境：您想要點擊「New email」按鈕，但有時會顯示安全性設定對話方塊。在這種情況下，您可以等待「New email」按鈕或對話方塊，並採取相應的行動。

注意

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

const newEmail = page.getByRole('button', { name: 'New' });
const dialog = page.getByText('Confirm security settings');
await expect(newEmail.or(dialog).first()).toBeVisible();
if (await dialog.isVisible())
  await page.getByRole('button', { name: 'Dismiss' }).click();
await newEmail.click();

參數

  • locator Locator#

    要比對的替代定位器。

返回

page​

新增於：v1.19 locator.page

此定位器所屬的頁面。

用法

locator.page();

返回

press​

新增於：v1.14 locator.press

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

用法

await page.getByRole('textbox').press('Backspace');

參數

  • key string#

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

  • options Object (可選)

    • delay number (選用)#

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

    • noWaitAfter boolean (選用)#

      已棄用

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

      啟動導航的操作正在等待這些導航發生以及頁面開始載入。您可以通過設定此標誌來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法訪問的頁面。預設為 false。

    • timeout number (選用)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 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()。

用法

await locator.pressSequentially('Hello'); // Types instantly
await locator.pressSequentially('World', { delay: 100 }); // Types slower, like a user

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

const locator = page.getByLabel('Password');
await locator.pressSequentially('my password');
await locator.press('Enter');

參數

  • text string#

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

  • options Object (可選)

    • delay number (選用)#

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

    • noWaitAfter boolean (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • timeout number (選用)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回

screenshot​

新增於：v1.14 locator.screenshot

擷取符合定位器的元素的螢幕截圖。

用法

await page.getByRole('link').screenshot();

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

await page.getByRole('link').screenshot({ animations: 'disabled', path: 'link.png' });

參數

  • options Object (可選)

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

      設定為 "disabled" 時，會停止 CSS 動畫、CSS 過場效果和 Web Animations。動畫會根據其持續時間而有不同的處理方式

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

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

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

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

    • mask Array<Locator> (選用)#

      指定在擷取螢幕截圖時應遮罩的定位器。遮罩元素將會覆蓋一個粉紅色方塊 #FF00FF（由 maskColor 自訂），完全覆蓋其邊界框。

    • maskColor string (選用)新增於：v1.35#

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

    • omitBackground boolean (選用)#

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

    • path string (選用)#

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

    • quality number (選用)#

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

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

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

      預設為 "device"。

    • style string (選用)新增於：v1.41#

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

    • timeout number (選用)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

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

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

返回

詳細資訊

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

此方法會等待可操作性檢查，然後在擷取螢幕截圖之前將元素捲動到檢視區。如果元素與 DOM 分離，則此方法會拋出錯誤。

傳回包含擷取螢幕截圖的 buffer。

scrollIntoViewIfNeeded​

新增於：v1.14 locator.scrollIntoViewIfNeeded

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

請參閱捲動以了解其他捲動方式。

用法

await locator.scrollIntoViewIfNeeded();
await 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({ label: 'Blue' });

// multiple selection for red, green and blue options
element.selectOption(['red', 'green', 'blue']);

參數

  • values null | string | ElementHandle | Array<string> | Object | Array<ElementHandle> | Array<Object>#

    • value string (選用)

      依 option.value 比對。選用。

    • label string (選用)

      依 option.label 比對。選用。

    • index number (選填)

      依索引值比對。選填。

    要選取的選項。如果 <select> 標籤具有 multiple 屬性，則會選取所有符合條件的選項，否則只會選取第一個符合任一傳入選項的選項。字串值會同時比對值和標籤。如果所有指定的屬性都符合，則選項會被視為符合。
  • options Object (可選)

返回

詳細資訊

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

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

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

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

selectText​

新增於：v1.14 locator.selectText

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

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

用法

await locator.selectText();
await locator.selectText(options);

參數

返回

setChecked​

新增於版本：v1.15 locator.setChecked

設定核取方塊或 radio 元素的狀態。

用法

await page.getByRole('checkbox').setChecked(true);

參數

  • checked boolean#

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

  • options Object (可選)

    • force boolean (選填)#

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

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

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

    • timeout number (選填)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (選填)#

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

返回

詳細資訊

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

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

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

setInputFiles​

新增於：v1.14 locator.setInputFiles

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

用法

// Select one file
await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf'));

// Select multiple files
await page.getByLabel('Upload files').setInputFiles([
  path.join(__dirname, 'file1.txt'),
  path.join(__dirname, 'file2.txt'),
]);

// Select a directory
await page.getByLabel('Upload directory').setInputFiles(path.join(__dirname, 'mydir'));

// Remove all the selected files
await page.getByLabel('Upload file').setInputFiles([]);

// Upload buffer from memory
await page.getByLabel('Upload file').setInputFiles({
  name: 'file.txt',
  mimeType: 'text/plain',
  buffer: Buffer.from('this is test')
});

參數

返回

詳細資訊

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

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

tap​

新增於：v1.14 locator.tap

對符合 locator 的元素執行點擊手勢。

用法

await locator.tap();
await locator.tap(options);

參數

  • options Object (可選)

    • force boolean (選填)#

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

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (選填)#

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

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

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

    • timeout number (選填)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (選填)#

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

返回

詳細資訊

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

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

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

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

注意

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

textContent​

新增於：v1.14 locator.textContent

傳回 node.textContent。

斷言文字

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

用法

await locator.textContent();
await locator.textContent(options);

參數

返回

uncheck​

新增於：v1.14 locator.uncheck

確保核取方塊或 radio 元素處於未核取狀態。

用法

await page.getByRole('checkbox').uncheck();

參數

  • options Object (可選)

    • force boolean (選填)#

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

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • position Object (選填)#

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

    • timeout number (選填)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

    • trial boolean (選填)#

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

返回

詳細資訊

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

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

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

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

waitFor​

新增於版本：v1.16 locator.waitFor

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

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

用法

const orderSent = page.locator('#order-sent');
await orderSent.waitFor();

參數

  • options Object (可選)

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

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

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

    • timeout number (選填)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回

已棄用​

elementHandle​

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

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

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

用法

await locator.elementHandle();
await locator.elementHandle(options);

參數

返回

elementHandles​

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

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

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

用法

await locator.elementHandles();

返回

type​

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

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

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

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

用法

參數

  • text string#

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

  • options Object (可選)

    • delay number (選填)#

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

    • noWaitAfter boolean (選填)#

      已棄用

      此選項無效。

      此選項無效。

    • timeout number (選填)#

      最大時間（毫秒）。預設值為 0 - 無超時。預設值可以通過配置中的 actionTimeout 選項更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回