自動等待

簡介

Playwright 在執行動作前，會先對元素執行一系列的可操作性檢查，以確保這些動作能如預期般運作。它會自動等待所有相關檢查通過，然後才執行請求的動作。如果在給定的 timeout 內，所需的檢查未通過，則動作將失敗並顯示 TimeoutError。

例如，對於 Locator.click()，Playwright 將確保

• 定位器解析為恰好一個元素
• 元素為可見
• 元素為穩定，即不會動畫或已完成動畫
• 元素接收事件，即不會被其他元素遮蔽
• 元素為已啟用

以下是針對每個動作執行的完整可操作性檢查列表

動作	可見	穩定	接收事件	已啟用	可編輯
Locator.check()	是	是	是	是	-
Locator.click()	是	是	是	是	-
Locator.dblclick()	是	是	是	是	-
Locator.setChecked()	是	是	是	是	-
Locator.tap()	是	是	是	是	-
Locator.uncheck()	是	是	是	是	-
Locator.hover()	是	是	是	-	-
Locator.dragTo()	是	是	是	-	-
Locator.screenshot()	是	是	-	-	-
Locator.fill()	是	-	-	是	是
Locator.clear()	是	-	-	是	是
Locator.selectOption()	是	-	-	是	-
Locator.selectText()	是	-	-	-	-
Locator.scrollIntoViewIfNeeded()	-	是	-	-	-
Locator.blur()	-	-	-	-	-
Locator.dispatchEvent()	-	-	-	-	-
Locator.focus()	-	-	-	-	-
Locator.press()	-	-	-	-	-
Locator.pressSequentially()	-	-	-	-	-
Locator.setInputFiles()	-	-	-	-	-

強制動作

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

斷言

Playwright 包含自動重試斷言，它會等待直到條件滿足，從而消除不穩定性，這與動作前的自動等待類似。

斷言	描述
assertThat(locator).isAttached()	元素已附加
assertThat(locator).isChecked()	核取方塊已勾選
assertThat(locator).isDisabled()	元素已停用
assertThat(locator).isEditable()	元素可編輯
assertThat(locator).isEmpty()	容器為空
assertThat(locator).isEnabled()	元素已啟用
assertThat(locator).isFocused()	元素已聚焦
assertThat(locator).isHidden()	元素不可見
assertThat(locator).isInViewport()	元素與視窗相交
assertThat(locator).isVisible()	元素可見
assertThat(locator).containsText()	元素包含文字
assertThat(locator).hasAttribute()	元素具有 DOM 屬性
assertThat(locator).hasClass()	元素具有類別屬性
assertThat(locator).hasCount()	列表具有確切的子項目數量
assertThat(locator).hasCSS()	元素具有 CSS 屬性
assertThat(locator).hasId()	元素具有 ID
assertThat(locator).hasJSProperty()	元素具有 JavaScript 屬性
assertThat(locator).hasText()	元素符合文字
assertThat(locator).hasValue()	輸入框具有值
assertThat(locator).hasValues()	選取器已選取選項
assertThat(page).hasTitle()	頁面具有標題
assertThat(page).hasURL()	頁面具有 URL
assertThat(response).isOK()	回應具有 OK 狀態

請參閱斷言指南以了解更多資訊。

可見

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

請注意，根據此定義

• 零尺寸的元素不被視為可見。
• 具有 display:none 的元素不被視為可見。
• 具有 opacity:0 的元素被視為可見。

穩定

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

已啟用

當元素未停用時，即被視為已啟用。

在以下情況下，元素會被停用

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

可編輯

當元素已啟用且非唯讀時，即被視為可編輯。

在以下情況下，元素會被唯讀

• 它是具有 [readonly] 屬性的 <select>、<input> 或 <textarea>；
• 它具有 [aria-readonly=true] 屬性以及支援它的 aria 角色。

接收事件

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

例如，考慮以下情境，無論何時調用 Locator.click()，Playwright 都會點擊 Sign Up 按鈕

• 頁面正在檢查使用者名稱是否唯一，且 Sign Up 按鈕已停用；
• 與伺服器檢查後，停用的 Sign Up 按鈕被另一個現在已啟用的按鈕取代。