自動等待

簡介

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 選項，該選項會停用非必要的可操作性檢查，例如傳遞真值 force 給 locator.click() 方法將不會檢查目標元素是否實際接收到點擊事件。

斷言

Playwright 包含自動重試的斷言，通過等待條件滿足來消除不穩定性，類似於在操作前自動等待。

Assertion	Description
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()	元素有類別屬性
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 樣式時被認為是可見的。

請注意，根據此定義:

• 零大小的元素不會被認為是可見的。
• display:none 的元素不會被認為是可見的。
• opacity:0 的元素會被認為是可見的。

穩定

當元素在至少兩個連續的動畫幀中保持相同的邊界框時，則認為該元素是穩定的。

啟用

Element 被認為是啟用的，除非它是具有 disabled 屬性的 <button>、<select>、<input> 或 <textarea>。

可編輯

元素在 enabled 且未設置 readonly 屬性時被視為可編輯。

接收事件

元素被認為正在接收指標事件，當它是在操作點的指標事件的命中目標時。例如，當點擊點在 (10;10) 時，Playwright 會檢查是否有其他元素 (通常是覆蓋層) 會捕捉到 (10;10) 的點擊。

例如，考慮一個場景，無論何時進行 locator.click 呼叫，Playwright 都會點擊 Sign Up 按鈕：

• 頁面正在檢查用戶名是否唯一且Sign Up按鈕被停用;
• 與伺服器檢查後，被停用的Sign Up按鈕被替換為另一個現在啟用的按鈕。