相較於直接使用Playwright 的 VSCode Extension - Playwright Test for VSCode 或是 debug 模式，在 CI/CD 環境，以及 Docker 容器內執行測試，我們無法看見瀏覽器真實運作的情形，這是因為 CI/CD 與 Docker 裡預設是 headless 模式，也就是不顯示 GUI (用戶圖形介面) 的模式下運行瀏覽器。

(由於我本身使用的是 Windows 環境，因此以下內容皆以 Windows 為主。)

headless 模式下的不穩定測試

我們在本地端寫好測試腳本後，滿心期待地推上 CI/CD，卻意外地發現在 CI/CD 環境中測試失敗了。其實這種情況並不罕見，有時可能只是單純因為環境差異導致瀏覽器運作速度不同，但有時，真正的兇手卻可能是 headless 模式。

在 headless 模式下，並不會真正開啟瀏覽器視窗，部分功能可能因此無法正常運作。例如以下幾種行為可能會在 headless 模式中失效：

• window.open()
• PDF Viewer (以embed 嵌入 PDF 閱讀器)
• iframe 中的 popup 行為

想要確定測試失敗的根本原因，究竟是 headless 模式的限制，或是其他邏輯或環境因素導致，可能就必須嘗試在 Docker 或 CI/CD 環境裡以 Headed 模式執行測試。

Playwright 的 --headed 指令

在 IDE 的 terminal 執行測試，同樣是 headless 模式，如果我們在本地端，想看見真實瀏覽器，可以在指令後方加上 --headed：

npx playwright test --headed

按下 enter 執行，就能看見 Playwright 啟動真實瀏覽器，就如同 VSCode Extension 執行測試一般。

在 Docker 裡以 --headed 模式測試

然而，如果我們以 docker run ... 啟動 Docker 容器後，在容器裡直接執行 npx playwright test --headed，會無法執行並報錯：

這是因為 Docker 容器本身沒有 GUI 元件，所以必須在容器內啟動虛擬的顯示環境，我們來嘗試看看 Playwright 提供的兩種方法：

1. 預設 headless 為 true，因此在 playwright.config.ts 的 use 裡設定 headless: false，再執行 npx playwright test --headed，這個方法我設定後仍然無法執行 (如果此方法可行，再請留言指正)。
2. 在執行測試指令前面加上xvfb-run (Linux 環境的虛擬顯示伺服器工具)：

   xvfb-run npx playwright test
   

   這時，就可以看見測試順利執行：
   

雖然使用上方指令可以成功以 headed 模式執行 Playwright 測試，但還是 「看不到實體瀏覽器視窗」。

眼見為憑：看見真實瀏覽器

如果只是想確認測試不穩定的原因是由於 headless 模式，使用 xvfb-run 指令就能達成目的。但若還是想看到瀏覽器真的「跳出來」，並且能夠觀察測試實際運作的情形，那我們就必須在環境多做一些能夠顯示瀏覽器的支援。

首先，Docker 容器本身是 Linux 環境，而 Linux 的圖形顯示系統（GUI）：X Server 透過 X Window System（又稱 X11）運作，但容器內又沒有任何的顯示器或是圖形伺服器，再加上 Windows 預設並沒有 X Server，因此我們必須先安裝 Xming 或是 VcXsrv 這類在 Windows 上模擬 Linux X Server 的軟體，這裡就以 VcXsrv 來嘗試看看。

Vcxsrv 基本設定流程

1. Vcxsrv官網 下載並安裝
2. 安裝後會看見 Vcxsrv 與 XLunch 兩個應用程式
3. 開啟 XLunch 應用程式
4. XLunch 啟動時選擇：

   • Multiple windows

   • Display number: 0
     

   • Start no client
     

   • Disable access control
     

     XLunch 設定完成後，在 Windows 桌面下方工具列隱藏圖示就會看見 XLunch 正在啟動狀態。

在 Docker 容器內啟用 headed 模式執行測試

1. 在 Powershell 裡輸入以下指令以啟用 Docker 容器：

   docker run -it --rm -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --ipc=host -v ${pwd}:/src mcr.microsoft.com/playwright:v1.55.1-noble bash
   

   • -e DISPLAY=$DISPLAY 設定容器內的環境變數 DISPLAY，在 Linux 桌機上，$DISPLAY 通常是 0 (與 XLunch 設定為 0 相對應)

   • -v /tmp/.X11-unix:/tmp/.X11-unix 把主機的 X11 Unix socket 掛載進容器，socket 是 X Server 與應用程式之間的通訊通道

     簡單來說 -e DISPLAY=$DISPLAY 設定好 「要把畫面顯示到哪個 X Server（螢幕）上」 ，而 -v /tmp/.X11-unix:/tmp/.X11-unix 則是告訴容器裡的瀏覽器 「透過這個通道，把畫面送給主機的顯示器。」

2. 輸入 npx playwright test --headed，XLunch 會啟動瀏覽器並開始測試：
   
3. 輸入 PWDEBUG=1 npx playwright test --headed，XLunch 會啟動瀏覽器與 Inspector，讓我們可以在 Docker 容器環境中執行 debug 模式測試：
   

依照以上步驟，就能真實看見瀏覽器「跳出來」並且順利執行測試。

如果設定完成後仍顯示未啟動 Xserver 無法執行，可能原因為被防火牆阻擋或是 DISPLAY 指向錯誤，試試看以下兩種方式：

1. 開啟防火牆設定：
   在 Windows 搜尋「防火牆與網路保護」→
   允許應用程式通過防火牆 →
   找到 VcXsrv →
   勾選「私人網路」及「公用網路」
2. 指定主機 IP 位置：
   -e DISPLAY=$DISPLAY 更改為 →
   -e DISPLAY=<你的 IP 位置>:0

到這裡，我們了解了 Playwright 的 headless 模式與它可能帶來的影響，以及如何啟用 headed 模式，甚至破解了 headed 模式卻看不見瀏覽器的情況。接下來，讓我們認識一個實用的第三方套件：Allure Report，它能以直覺且圖形化的方式呈現測試結果，讓團隊成員能更輕鬆地瀏覽、分析與追蹤測試成果。