自動等待

簡介

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

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

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

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

動作	可見	穩定	接收事件	已啟用	可編輯
Locator.CheckAsync()	是	是	是	是	-
Locator.ClickAsync()	是	是	是	是	-
Locator.DblClickAsync()	是	是	是	是	-
Locator.SetCheckedAsync()	是	是	是	是	-
Locator.TapAsync()	是	是	是	是	-
Locator.UncheckAsync()	是	是	是	是	-
Locator.HoverAsync()	是	是	是	-	-
Locator.DragToAsync()	是	是	是	-	-
Locator.ScreenshotAsync()	是	是	-	-	-
Locator.FillAsync()	是	-	-	是	是
Locator.ClearAsync()	是	-	-	是	是
Locator.SelectOptionAsync()	是	-	-	是	-
Locator.SelectTextAsync()	是	-	-	-	-
Locator.ScrollIntoViewIfNeededAsync()	-	是	-	-	-
Locator.BlurAsync()	-	-	-	-	-
Locator.DispatchEventAsync()	-	-	-	-	-
Locator.FocusAsync()	-	-	-	-	-
Locator.PressAsync()	-	-	-	-	-
Locator.PressSequentiallyAsync()	-	-	-	-	-
Locator.SetInputFilesAsync()	-	-	-	-	-

強制執行動作

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

斷言

Playwright 包含自動重試斷言，可藉由等待直到條件滿足來消除不穩定性，類似於動作前的自動等待。

斷言	描述
Expect(Locator).ToBeAttachedAsync()	元素已附加
Expect(Locator).ToBeCheckedAsync()	核取方塊已核取
Expect(Locator).ToBeDisabledAsync()	元素已停用
Expect(Locator).ToBeEditableAsync()	元素可編輯
Expect(Locator).ToBeEmptyAsync()	容器為空
Expect(Locator).ToBeEnabledAsync()	元素已啟用
Expect(Locator).ToBeFocusedAsync()	元素已聚焦
Expect(Locator).ToBeHiddenAsync()	元素不可見
Expect(Locator).ToBeInViewportAsync()	元素與視窗相交
Expect(Locator).ToBeVisibleAsync()	元素可見
Expect(Locator).ToContainTextAsync()	元素包含文字
Expect(Locator).ToHaveAttributeAsync()	元素具有 DOM 屬性
Expect(Locator).ToHaveClassAsync()	元素具有類別屬性
Expect(Locator).ToHaveCountAsync()	清單具有確切數量的子元素
Expect(Locator).ToHaveCSSAsync()	元素具有 CSS 屬性
Expect(Locator).ToHaveIdAsync()	元素具有 ID
Expect(Locator).ToHaveJSPropertyAsync()	元素具有 JavaScript 屬性
Expect(Locator).ToHaveTextAsync()	元素符合文字
Expect(Locator).ToHaveValueAsync()	輸入具有值
Expect(Locator).ToHaveValuesAsync()	選取具有選取的選項
Expect(Page).ToHaveTitleAsync()	頁面具有標題
Expect(Page).ToHaveURLAsync()	頁面具有 URL
Expect(Response).ToBeOKAsync()	回應具有 OK 狀態

在斷言指南中瞭解更多資訊。

可見

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

請注意，根據此定義

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

穩定

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

已啟用

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

當元素符合以下條件時，即為已停用

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

可編輯

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

當元素符合以下條件時，即為唯讀

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

接收事件

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

例如，考慮以下情境，無論何時呼叫 Locator.ClickAsync()，Playwright 都將點擊 Sign Up 按鈕

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