如何在 Docker 執行 Playwright 自動化測試腳本

上周微軟的 Playwright 團隊推出了 v1.48 版本，我的實戰 E2E 測試：使用 Playwright 測試框架課程有位學員在我們的 Discord 課程專屬頻道中反應，說他沒辦法成功執行 Playwright 腳本，請我幫忙看看。因為要執行學員的程式，而我通常不喜歡在本機執行程式 (安全考量)，所以我就藉此玩了一下 Playwright 新版的 Docker 容器，順手寫了份筆記給大家參考。

representing Docker and Playwright automation testing

你可以透過 Docker Desktop 或 Podman 來執行 Playwright 容器，我們這篇文章就以 Docker Desktop 為例進行講解。

先下載 Docker 容器映像

首先，由微軟主導的 Playwright 專案也維護了一份 Playwright 的映象檔，但是他並不是維護在 Docker Hub 上面，而是在微軟自家的 Microsoft Artifact Registry 上面。

要獲取 Playwright 最新版的 Docker 容器映像，可以到以下網址查看所有的 Tags：

https://mcr.microsoft.com/en-us/product/playwright/tags

所以如果你想要下載 Playwright v1.48.0 的容器映像，就可以選用一個需要的 Tag 來用，目前 v1.48.0 有以下 Tags 可用：

v1.48.0
v1.48.0-amd64
v1.48.0-arm64
v1.48.0-noble
v1.48.0-noble-amd64
v1.48.0-noble-arm64
v1.48.0-jammy
v1.48.0-jammy-amd64
v1.48.0-jammy-arm64
v1.48.0-focal
v1.48.0-focal-amd64
v1.48.0-focal-arm64

很多人遇到這麼多 Image Tag 都會有選擇障礙，但其實我有一個很簡單的判斷方法，就是選擇「最短」的那個名字。因為現在的 Docker 容器映像檔都是多架構支援的，所以你只要選擇最短的那個 Tag 名稱，或是只有版本號的那個 Tag 名稱，他就會自動幫你選擇最適合的那個來下載。

越是明確的 Tag 名稱，代表他支援的架構越少，當然下載量也會最小，因此：

在本機執行，基本上選最短的那個
在 CI 執行，基本上選最精準的那個

針對這些 Tags 的命名規則，我也進一步說明一下。

CPU 架構
- amd64：x86-64 架構
- arm64：ARM 64 架構
作業系統

像 noble, jammy, focal 這些名字實際上是 Ubuntu 作業系統的發行版代號，每一個代號都代表了一個特定版本的 Ubuntu，並且都有一個可愛的動物名稱搭配形容詞，聽起來就像動畫電影中的角色一樣。
- noble: 對應 Ubuntu 24.04 LTS，代號 Noble Numbat。Numbat 是一種可愛的小型有袋動物，象徵著耐心和穩定，正如這個長期支援版本一樣，致力於提供穩定和安全的環境。
- jammy: 對應 Ubuntu 22.04 LTS，代號 Jammy Jellyfish。Jellyfish (海蜇) 給人一種輕盈靈活的感覺，反映出這個版本的 Ubuntu 在功能性和性能上的靈活性與創新性。
- focal: 對應 Ubuntu 20.04 LTS，代號 Focal Fossa。Fossa 是馬達加斯加特有的捕食者，代表著這個版本的 Ubuntu 在穩定性和安全性上的強大能力，確保用戶在使用過程中的順暢和可靠。

所以你如果要在本機跑 Playwright 的測試腳本，選擇最短的那個 Tag 名稱就可以了：

docker pull mcr.microsoft.com/playwright:v1.48.0

初始化 Docker Desktop 執行環境 (Windows)

若你是 Windows 作業系統，請確保你已經啟用了 Docker Desktop 的 Enable host networking 功能，這樣你才能順利的在容器中方便的使用 localhost 本地迴路介面 (loopback interface)，並在 Host 主機順利的連線到容器中的網路。

Docker Desktop > Settings > Resources > Network > Enable host networking

這個 Enable host networking 功能必須使用 Docker Desktop v4.34 以上版本才有支援，並且在 Windows 作業系統中，必須啟用 WSL 2 功能。

在啟用了 Enable host networking 選項之後，你就可以用比較簡單的命令來執行 Playwright 測試，並且可以很容易的透過 localhost 在 Windows 本機連接到容器，不需要在 docker run 時設定 -p 埠號對應參數。

建立 Playwright 容器

你可以透過以下指令來快速建立 Playwright 容器：

Windows / PowerShell

docker run -it --rm --ipc=host --net=host -v ${PWD}:/app --workdir=/app mcr.microsoft.com/playwright:v1.48.0 /bin/bash

Linux / macOS / bash / WSL

docker run -it --rm --ipc=host --net=host -v $PWD:/app --workdir=/app mcr.microsoft.com/playwright:v1.48.0 /bin/bash

進入容器環境後，可以直接透過命令列工具執行 Playwright 測試：

初始化 Playwright 專案

npm init playwright@latest --yes -- --quiet

執行 Playwright 測試
```
npx playwright test
```
查看 Playwright 的測試報表
```
npx playwright show-report
```
Playwright 預設的 HTML reporter 會監聽 Port 9323 讓你透過瀏覽器查看報表，所以你可以連到 http://localhost:9323 開啟 HTML 測試報表。

由於我們已經啟用 Enable host networking 功能的關係，所以你可以不用管容器的 IP 位址，直接在 Host 主機上開啟瀏覽器，連到 http://localhost:9323 就可以開啟 HTML 測試報表。

不過，如果你使用舊版的 Docker Desktop 來執行容器，啟動容器時要加上 -p 9323:9323 參數，並且執行 npx playwright show-report 命令時，還要額外加上 --host 0.0.0.0 參數，否則你將無法從 Host 主機開啟瀏覽器透過 http://localhost:9323 查看容器中的報表，設定相對麻煩許多。

後記

另外要提醒的一點是，微軟 Playwright 團隊所準備的這些容器映像檔，都已經內建最新版瀏覽器執行檔，所以你不需要在容器下載瀏覽器，這對 CI 來說也是非常方便的！👍

後來學員回報他自己解決了問題，他說公司內網 chromium 跟 firefox 都可以正常透過 Playwright 內建的瀏覽器連到外部網站，唯獨 webkit 連不出去，他在測試時改連外網 webkit 就可以成功運行了。我自己研判他們公司的資安設定限制了特定應用程式的連線能力，至於確切是如何阻擋的，那就真的要詢問他們公司的網管人員才能清楚了。

該學員最後也有分享，他參考 Playwright.tw 官網的 HTTP Proxy 文件，在 playwright.config.ts 加上 proxy 設定，就可以使用內網透過 webkit 連線到外網了！

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    proxy: {
      server: 'http://myproxy.com:3128',
      username: 'usr',
      password: 'pwd'
    }
  }
});

The Will Will Web

記載著 Will 在網路世界的學習心得與技術分享