核心概念篇的最後一站。前面五篇各講一件事：定位、斷言、等待、錄製、失敗分析。這篇的工具，會把那五件事同時放到同一個畫面上。

很多讀者是在這裡，第一次冒出「我其實看得懂」的感覺。

後面有七個練習，第一個就是重新開一個乾淨的練習專案。你就算前面幾篇沒跟著做，也能直接從這裡開始。

一、先理解：UI 模式是什麼

平常你用 npx playwright test 跑測試，終端機只給你一行綠字或紅字。中間瀏覽器做了什麼，你看不到，因為 Playwright 預設用無頭模式（headless mode）跑，連視窗都不會開。

手動測試出身的人，最強的能力就是看畫面。無頭模式正好把這件事拿掉了。

UI 模式把它還給你。整個執行過程都被錄下來，你可以停在任何一個動作上，看那一刻的畫面。

圖 1：一般執行與 UI 模式的差別，在於測試過程看不看得見

官方文件的三個關鍵詞

官網對 UI 模式的說明只有一句話，但裡面有三個詞值得記住：

二、練習 1：從零建一個練習專案

先理解

我們要一個乾淨的資料夾，裡面有 Playwright 幫忙產生的範例測試。這個範例每個人跑出來都一樣，後面所有練習都用它，你可以隨便亂改，改壞了刪掉重建就好。

動手
步驟 1　先確認電腦上有 Node.js。打開終端機，輸入：

node -v

→ 你會看到：印出版本號，例如 v22.14.0。官網建議用 20.x、22.x 或 24.x 的最新版。
如果印出 command not found，先到 nodejs.org 下載 LTS 版安裝，裝完把終端機關掉重開，再輸入一次。

步驟 2　建一個新資料夾，並且切進去。

mkdir playwright-uimode
cd playwright-uimode

Windows 在 PowerShell 裡這兩個指令一樣可以用。

步驟 3　執行初始化指令。

npm init playwright@latest

→ 你會看到：它會問你四個問題，一題一題出現。

步驟 4　四個問題這樣回答。除了第三題，其他直接按 Enter 用預設值就好。

→ 你會看到：開始下載瀏覽器。網路速度不同，這步可能要三到十分鐘，畫面上會跑進度。

步驟 5　裝完之後，看一下產生了什麼。輸入：

ls

Windows 用 dir。

→ 你會看到：下面這些檔案和資料夾。

playwright.config.ts      # 測試組態
package.json
package-lock.json
tests/
  example.spec.ts         # 最小範例測試

這是官網文件列出的標準結構，你的畫面應該一樣。我們只會用到 tests/example.spec.ts。

步驟 6　先用一般方式跑一次，體會一下那個黑盒子的感覺。

npx playwright test

→ 你會看到：終端機跑一陣子，最後印出 6 passed。兩個測試乘以三個瀏覽器，所以是 6。過程中你什麼畫面都沒看到。

這就是這篇要解決的問題
剛剛那 6 個測試，瀏覽器確實開了、點了、驗了，但整個過程你一眼都沒看到。
如果它們紅了，你手上就只有終端機那幾行字。下一個練習就是把畫面找回來。

三、練習 2：打開 UI 模式，認識畫面

動手
步驟 1　確認你還在 playwright-uimode 這個資料夾裡，然後輸入：

npx playwright test --ui

→ 你會看到：第一次大約等三到十秒，接著跳出一個獨立視窗。

步驟 2　先別急著點。對照下面這張圖，把五個區域的位置認一遍。

圖 2：UI 模式的版面。左邊挑測試，右邊看這個測試發生過什麼事

記一句話就好：左邊挑測試，右邊看這個測試發生過什麼事。

步驟 3　在側邊欄上方的篩選列，把專案篩選成只留 chromium。
→ 你會看到：測試清單變乾淨了。預設的組態會在三個瀏覽器上各跑一次，練習階段只看一個比較不亂。

開不起來的話

用 --ui-host=0.0.0.0 的時候注意
加了這個參數之後，同一個網路裡的其他機器也連得到你的 UI 模式，而追蹤裡可能含有測試帳密。在公司網路上用之前先想一下這件事。

四、練習 3：跑一個測試，逐步看它做了什麼

先看看要跑的是什麼

剛剛產生的 tests/example.spec.ts 裡面有兩個測試。我們用第二個：

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // 點擊開始使用連結。
  await page.getByRole('link', { name: 'Get started' }).click();

  // 期望頁面有名為 Installation 的標題。
  await expect(page.getByRole('heading',
    { name: 'Installation' })).toBeVisible();
});

這段就是官網「撰寫測試」那頁的範例，你剛剛產生的檔案裡應該一模一樣。

翻成中文只有三句話：打開 Playwright 官網、點 Get started 這個連結、確認 Installation 這個標題有出現。

動手

步驟 1　在左邊側邊欄展開 example.spec.ts，找到 get started link 這個測試。

步驟 2　滑鼠移到它的名稱上，右邊會冒出一個三角形，點下去。
→ 你會看到：測試開始跑，跑完名稱前面出現綠點。右邊區域填滿了內容。

步驟 3　看 C 區的 Actions 分頁，從上往下數。
→ 你會看到：大約三到四個動作：goto、click、expect。每一列右邊還有花了多少時間。

步驟 4　點第一個動作 goto。
→ 你會看到：中間出現 Playwright 官網首頁的畫面。

步驟 5　點第二個動作 click，然後切換中間上方的 Before 和 After 兩個分頁。
→ 你會看到：Before 是首頁，After 是點下去之後跳轉的安裝說明頁。兩張一比，就知道這一步做了什麼。

步驟 6　點第三個動作 expect，再看下方的 Source 分頁。
→ 你會看到：Source 會把這個動作對應的那一行程式碼標起來。程式和畫面就是在這裡接上的。

圖 3：點一個動作，Actions、畫面、程式碼三個地方會同時對上

步驟 7　回頭把三個動作各點一次，每點一次，用自己的話講出它在做什麼。
→ 你會看到：講得出來就過關。講不出來的那步，就是下一段要問 AI 的題目。

講不出來就問
把那一行完整貼給 Claude Code，順便說明你的背景，得到的解釋會好很多：
「這一行 await page.getByRole('link', { name: 'Get started' }).click() 是在做什麼？請用我看得懂的話解釋，我是手動測試背景，不熟 JavaScript。」

五、練習 4：用時間軸倒帶

先理解

右邊最上面那條彩色橫條就是時間軸，等於這趟執行的錄影進度條。導覽和動作用不同顏色標出來，失敗時還會有一條紅線標在錯誤發生的位置。

圖 4：時間軸的三種用法

動手

步驟 1　滑鼠在時間軸上左右移動，不要點，只是移過去。
→ 你會看到：中間的畫面跟著變，像在拖影片進度條。這就是官網說的時光旅行。

步驟 2　在時間軸上雙擊某一段。
→ 你會看到：時間軸放大到那個動作的時間範圍，看得更細。

步驟 3　拖動時間軸上的滑桿，圈出一小段範圍。
→ 你會看到：Actions、Console、Network 都只剩下這段範圍內的紀錄。整趟有五十筆請求時，這招很省事。

六、練習 5：故意弄壞，然後把它查出來

先理解
測試會紅，讀懂為什麼紅才是重點。這個練習我們自己把測試弄壞，因為知道答案，你可以專心練查的流程。
動手：弄壞它

步驟 1　用編輯器打開 tests/example.spec.ts，把 click 那一行的 'Get started' 改成 'Get started now'。

await page.getByRole('link', { name: 'Get started now' }).click();

只多加兩個字，畫面上其實沒有這個連結。

步驟 2　存檔，回到 UI 模式，再跑一次這個測試。
→ 你會看到：測試跑很久（大約半分鐘）才失敗，名稱前面變成紅色。

動手：查出原因

步驟 3　看時間軸。
→ 你會看到：最後有一段特別長，而且有一條紅線標出錯誤的位置。這條線很細，而且在這個例子裡剛好落在時間軸最右邊的盡頭，貼著邊界，常常看不出來。看不到沒關係，下面三步指的是同一個位置。

步驟 4　點下方的 Errors 分頁，把錯誤訊息讀一次。
→ 你會看到：大意是逾時，在等一個 getByRole('link', { name: 'Get started now' }) 的元素。

步驟 5　回到 Actions 分頁，點紅色那個動作，看中間的畫面。
→ 你會看到：畫面還停在 Playwright 首頁，根本沒跳轉。也就是說，這一步從頭到尾沒點成功。

步驟 6　點下方的 Log 分頁。
→ 你會看到：一行一行寫著它在等什麼：等待定位器、找不到符合的元素、繼續重試。這就是第 8 篇講的自動等待，它在畫面上長這樣。

步驟 7　點下方的 Call 分頁。
→ 你會看到：它明白告訴你這個動作用的定位器是什麼、跑了多久。定位器寫的是 Get started now，畫面上的連結卻是 Get started。

步驟 8　下判斷。
結論是定位器描述的名字，跟畫面上那個連結對不起來，所以 Playwright 一直等一個不存在的元素，等到逾時。

步驟 9　把 'Get started now' 改回 'Get started'，存檔，再跑一次。
→ 你會看到：測試已經通過了。

這個流程可以帶走

上面九步濃縮成四句：看時間軸找到出事的位置，讀 Errors 拿線索，點那一步看畫面確認發生什麼，再開 Log 和 Call 找證據。

提醒：失敗的地方不一定是出問題的地方

剛剛的例子很單純，倒下的那一步就是病因。實際工作上常常不是這樣。
舉個例子。表單測試在「點送出」那步失敗，訊息說找不到送出鈕。往前倒帶會發現，填 Email 那步就已經跳出格式錯誤的紅字，送出鈕一直是反灰的。要修的是測試資料，按鈕的定位沒問題。

圖 5：測試停在第 5 步，真正的病因藏在第 3 步

所以查的時候，不要只盯著紅色那一步。沿時間軸往前找，畫面第一次跟你預期不一樣的地方，通常才是病因。

七、練習 6：用選擇定位器查寫法

先理解
第 6 篇留了一個問題：這個元素到底要怎麼描述？官網叫「選擇定位器」的功能，就是現場答案。滑鼠移到哪裡，它就告訴你 Playwright 會怎麼寫。

圖 6：選擇定位器的四個動作

動手
步驟 1　先跑一次測試，讓中間的畫面有東西。點任何一個動作都可以。

步驟 2　點畫面上方工具列的 Pick locator 按鈕。

圖 7：選擇定位器 (Pick locator)

步驟 3　滑鼠移到畫面上任何一個元素，先不要點。試試看 Playwright 官網上方的搜尋框或選單。
→ 你會看到：元素被框起來，旁邊即時顯示它的定位器寫法。

圖 8：游標移到所選的 UI 元素

步驟 4　點一下那個元素。
→ 你會看到：定位器被填進上方的輸入框。

步驟 5　試著在輸入框裡改改看，例如把名字改成畫面上沒有的字。
→ 你會看到：改成對的，元素會被標出來；改成錯的，就標不到。等於邊寫邊驗。

步驟 6　改到滿意，按旁邊的複製按鈕，貼進你的測試。

順手學一招：先查好定位再請 AI 寫測試

定位是 AI 最容易寫歪的地方，因為它看不到你的畫面。你先查好餵給它，準確度會差很多：

幫我寫一個測試：點 Get started，驗證出現 Installation 標題。
連結的定位器用 getByRole('link', { name: 'Get started' })，
標題用 getByRole('heading', { name: 'Installation' })。
這兩個我已經在 UI 模式驗過會命中。

八、練習 7：開啟觀看模式

先理解
修測試最累的是等待。改完存檔、切終端機、打指令、等結果，一輪走完，你已經忘記自己剛剛改了什麼。
觀看模式把這一輪縮到幾秒：檔案一存檔就自動重跑。

圖 9：觀看模式把修改到看見結果的距離縮到幾秒鐘

動手
步驟 1　在側邊欄，把滑鼠移到 get started link 這個測試上，點它旁邊的眼睛圖示。
→ 你會看到：眼睛亮起來，代表這個測試正在被監看。

步驟 2　回到編輯器，把 'Get started' 再改成 'Get started now'，存檔。
→ 你會看到：不必回終端機，UI 模式自己跑起來，幾秒後變紅。

步驟 3　改回 'Get started'，存檔。
→ 你會看到：又自己跑一次，變綠。這個節奏就是修測試時最順的狀態。

步驟 4　練習完記得把眼睛關掉，免得之後每次存檔都在跑。

兩個小提醒
想同時監看幾個測試，就把它們的眼睛都點開。想全部監看，點側邊欄最上面的眼睛。
測試很多的時候不要監看全部，每次存檔都重跑全部會愈跑愈慢。

搭配 Claude Code 的用法
螢幕左邊擺 Claude Code，右邊擺 UI 模式。請它改一版、它存檔、UI 模式自動跑、你看結果、回頭告訴它下一句。整個來回壓在幾秒之內。

這個手感跟你手動測試「改完馬上驗」是一樣的，只是驗的動作被自動化接走了。

九、核心概念篇小結

到這裡，基本功已經齊了。盤點一下：

圖 10：核心概念篇的六塊基本功

• 定位（第 6 篇）：會用「像不像使用者描述畫面」判斷 AI 選的定位穩不穩。
• 斷言（第 7 篇）：會找 expect、翻成中文、用三個問題檢查夠不夠。
• 等待（第 8 篇）：懂自動等待，看到逾時會分三種情況判讀。
• 錄製（第 9 篇）：會用「錄流程 + AI 補斷言」的工作流。
• 失敗（第 10 篇）：知道去 trace 找證據，判斷是產品還是測試的問題。
• 透明（本篇）：有 UI 模式這個外殼，執行過程看得見。

這六項合起來，就是看得懂、判斷得了。接下來的實戰篇，就是拿它上場。

💡 自我檢核
動手的：打開 UI 模式，挑一個測試逐步播放，每一步都能用自己的話說出它在做什麼，也說得出它用的定位器（開 Call 分頁對答案）。
口頭的：不看資料，向同事解釋「為什麼 Playwright 的測試比十年前的自動化穩定？」講得出語意化定位和自動等待這兩件事，核心概念篇就算學進去了。