自動等待

簡介

Playwright 在對元素執行動作之前會進行一系列可操作性檢查，以確保這些動作能如預期執行。它會自動等待所有相關檢查通過，然後才執行請求的動作。如果必要的檢查在指定的 timeout 時間內未通過，動作將失敗並拋出 TimeoutError。

例如，對於 locator.click()，Playwright 會確保：

以下是每個動作執行的可操作性檢查完整清單：

動作	可見	穩定	接收事件	啟用	可編輯
`locator.check()`	是	是	是	是	-
`locator.click()`	是	是	是	是	-
`locator.dblclick()`	是	是	是	是	-
`locator.set_checked()`	是	是	是	是	-
`locator.tap()`	是	是	是	是	-
`locator.uncheck()`	是	是	是	是	-
`locator.hover()`	是	是	是	-	-
`locator.drag_to()`	是	是	是	-	-
`locator.screenshot()`	是	是	-	-	-
`locator.fill()`	是	-	-	是	是
`locator.clear()`	是	-	-	是	是
`locator.select_option()`	是	-	-	是	-
`locator.select_text()`	是	-	-	-	-
`locator.scroll_into_view_if_needed()`	-	是	-	-	-
`locator.blur()`	-	-	-	-	-
`locator.dispatch_event()`	-	-	-	-	-
`locator.focus()`	-	-	-	-	-
`locator.press()`	-	-	-	-	-
`locator.press_sequentially()`	-	-	-	-	-
`locator.set_input_files()`	-	-	-	-	-

某些動作如 locator.click() 支援 force 選項，可停用非必要的可操作性檢查。例如，向 locator.click() 方法傳遞真值的 force 將不會檢查目標元素是否實際接收點擊事件。

Playwright 包含自動重試斷言，透過等待直到條件符合來消除不穩定性，類似於動作前的自動等待。

斷言	描述
`expect(locator).to_be_attached()`	元素已附加
`expect(locator).to_be_checked()`	核取方塊已勾選
`expect(locator).to_be_disabled()`	元素已停用
`expect(locator).to_be_editable()`	元素可編輯
`expect(locator).to_be_empty()`	容器為空
`expect(locator).to_be_enabled()`	元素已啟用
`expect(locator).to_be_focused()`	元素已聚焦
`expect(locator).to_be_hidden()`	元素不可見
`expect(locator).to_be_in_viewport()`	元素與檢視區相交
`expect(locator).to_be_visible()`	元素可見
`expect(locator).to_contain_text()`	元素包含文字
`expect(locator).to_have_attribute()`	元素具有 DOM 屬性
`expect(locator).to_have_class()`	元素具有 class 屬性
`expect(locator).to_have_count()`	清單具有確切的子元素數量
`expect(locator).to_have_css()`	元素具有 CSS 屬性
`expect(locator).to_have_id()`	元素具有 ID
`expect(locator).to_have_js_property()`	元素具有 JavaScript 屬性
`expect(locator).to_have_text()`	元素符合文字
`expect(locator).to_have_value()`	輸入欄位具有值
`expect(locator).to_have_values()`	選擇框具有已選取的選項
`expect(page).to_have_title()`	頁面具有標題
`expect(page).to_have_url()`	頁面具有 URL
`expect(response).to_be_ok()`	回應狀態為 OK

了解更多在 assertions 指南。

當元素具有非空邊界框且沒有 visibility:hidden 計算樣式時，則被視為可見。

請注意，根據此定義：

當元素在至少連續兩個動畫影格中保持相同的邊界框時，則被視為穩定。

當元素不是停用時，則被視為啟用。

在以下情況下元素停用：

它是具有 [disabled] 屬性的 <button>、<select>、<input>、<textarea>、<option> 或 <optgroup>；
它是屬於具有 [disabled] 屬性的 <fieldset> 中的 <button>、<select>、<input>、<textarea>、<option> 或 <optgroup>；
它是具有 [aria-disabled=true] 屬性的元素的後代。

當元素是啟用的且不是唯讀時，則被視為可編輯。

在以下情況下元素唯讀：

當元素是動作點指標事件的點擊目標時，則被視為接收指標事件。例如，在點 (10;10) 點擊時，Playwright 會檢查是否有其他元素（通常是覆蓋層）會代替捕獲在 (10;10) 的點擊。

例如，考慮一個情境，無論何時呼叫 locator.click()，Playwright 都會點擊 Sign Up 按鈕：