你手動測試時其實一直在「等」,只是沒意識到:頁面轉圈,你自然停一下再點。程式沒有這種直覺,它快得不像話,網頁還沒好就伸手去點,然後失敗。上一代工具讓很多人栽在「等多久」這題上,Playwright 把它大致解掉了。但你還是要懂原理,因為看懂 Timeout 錯誤靠的就是它。

上一代的痛:寫死的等待

早年的做法,是在動作之間塞一行「睡 5 秒」:sleep(5000)。硬等五秒,再做下一步。

圖 1:寫死等待兩頭輸,自動等待剛剛好

問題在網頁的速度不固定。網頁 2 秒就好,你白等 3 秒;幾百個測試累積下來,一輪要跑幾小時。偏偏某天網頁 7 秒才好,5 秒不夠,測試又誤判失敗。

團隊的反應通常是把秒數越調越大。結果測試越跑越慢,還是時不時亂紅。很多公司的自動化,就是這樣慢慢做爛的。

Playwright 的做法:自動等到「可以動」才動

Playwright 每個動作執行前,會自動檢查「這個動作要操作的那個元素」——例如你要點的那顆按鈕——是不是已經可以操作。檢查四個條件,用商店想最容易分:一件商品要能被買走,得先到貨、然後上架、伸手搆得到、而且正在販售。網頁元素也是同一串:

• 到貨了嗎?——按鈕已經被載進這個網頁了嗎?頁面還在載入時,它可能連進貨都還沒。關鍵觀念:到貨不等於看得到——網頁裡很多東西早就載進來了,只是先藏著。

• 上架了嗎?——載進來了,但有顯示出來嗎?收合選單裡的按鈕就是典型:早就到貨,還躺在倉庫裡藏著,選單一展開,才算上架給人看。

• 搆得到嗎?——上架了,但 cookie 同意橫幅疊在它前面,伸手碰到的是橫幅。它會等遮擋消失。

• 開賣了嗎?——搆得到,但表單沒填完時送出鈕反灰,像掛著「暫停販售」的牌子。它會等按鈕解禁。

四關都過,立刻動手;有一關卡住,就持續重試,最多等到一個上限(預設 30 秒),超過才放棄並回報 Timeout。之後看到 Timeout,也可以反過來用這四問排查:還沒到貨?沒上架?被擋住?還是停售中?

拿一個常見場景走一次:頁面點了「查詢」之後會轉圈圈三秒,結果才出現。上一代的寫法要自己抓「睡幾秒」;Playwright 的寫法直接驗結果,expect(結果區塊).toBeVisible() 會自己等圈圈轉完、結果現身,一秒好就等一秒,三秒好就等三秒。等待這件事,從你的問題變成框架的問題。

效果是:網頁快,測試就快;網頁慢,測試就等到剛剛好。你完全不用寫任何等待的程式,這件事內建就處理掉了。

看到這個寫法,要警覺

正因為自動等待是內建的,如果你在 AI 產出的測試裡看到 page.waitForTimeout(3000) 這種「硬睡 3 秒」的寫法,就該追問。

它偶爾有正當理由,例如等一個畫面上完全沒有訊號的背景動作。但更常見的情況是「不知道在等什麼,先睡一下再說」,那就是上一代的老路。直接問:

你可以這樣對 Claude Code 說:

這裡為什麼用 waitForTimeout?有沒有明確的訊號可以等,例如某個元素出現、某個請求完成?如果真的沒有,請加上註解說明原因。

Timeout 錯誤怎麼判讀:先分三種

即使有自動等待,你還是會遇到 Timeout:等了 30 秒,元素還是不能操作。這是初學者最常見的錯誤,別急,它只有三種可能:

圖 2:Timeout 的三種可能與對應處理

• 定位錯了。元素其實在畫面上,但定位方式找不到它。處理:請 AI 檢查 locator,或用第 11 篇的工具現場確認。

• 功能真的壞了。元素本來就該出現,卻沒出現。恭喜,測試抓到 bug 了,Timeout 就是它報警的方式。照缺陷流程處理。

• 單純太慢。測試環境慢、資料量大,30 秒真的不夠。查明原因之後,才考慮調整上限。

特別提醒第二種的存在。很多人看到 Timeout 就反射性地把上限調大,那等於把警報器的音量轉小。正確順序是先弄清楚原因,確認只是環境慢,才動上限。

斷言也會自動重試

還有一個容易忽略的細節:expect 斷言同樣會重試。expect(訊息).toBeVisible() 的意思不是「當下看一眼」,而是「持續看,最多看 5 秒」。

這解決了很多時序問題:訊息晚半秒才出現,測試不會誤判。這也是為什麼上一篇強調用 Playwright 的斷言寫法,它們自帶這層保護。

今天的練習

• 回想第 3 篇你弄壞等待看到的 Timeout,現在用三分類重新判讀它屬於哪一種。(答案:第三種的人為版,上限被你改成 1 毫秒,等再快也不夠。)
• 檢查你目前所有測試,搜尋有沒有 waitForTimeout。有的話,用上面的指令問 AI 能不能改掉。
• 跟同事聊天題:「你們的自動化怎麼處理等待?」如果答案還是 sleep 加秒數,你已經知道能帶給團隊的第一個改善點了。