自動等待

簡介

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

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()`	元素具有 class 屬性
`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

了解更多在 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.ClickAsync()，Playwright 都會點擊 Sign Up 按鈕：