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

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

![representing Docker and Playwright automation testing](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/c800d9abc56d4aae8042-d863fc0e-f0c6-48bd-9f8f-42d8a9ed3355.webp)

你可以透過 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 或 [Podman](https://podman.io/) 來執行 Playwright 容器，我們這篇文章就以 Docker Desktop 為例進行講解。

### 先下載 Docker 容器映像

首先，由微軟主導的 Playwright 專案也維護了一份 Playwright 的映象檔，但是他並不是維護在 [Docker Hub](https://hub.docker.com/r/microsoft/playwright) 上面，而是在微軟自家的 [Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/playwright/) 上面。

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

> [https://mcr.microsoft.com/en-us/product/playwright/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 名稱就可以了：

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

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

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

![Docker Desktop > Settings > Resources > Network > Enable host networking](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/e0dc8b8dcf047a31e7a2-9c1d8500-14de-449e-84ae-e238a41205c3.jpg)

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

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

### 建立 Playwright 容器

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

-   Windows / PowerShell
    
    ```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
    
    ```powershell
    docker run -it --rm --ipc=host --net=host -v $PWD:/app --workdir=/app mcr.microsoft.com/playwright:v1.48.0 /bin/bash
    ```
    

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

1.  初始化 Playwright 專案
    
    ```bash
    npm init playwright@latest --yes -- --quiet
    ```
    
2.  執行 Playwright 測試
    
    ```bash
    npx playwright test
    ```
    
3.  查看 Playwright 的測試報表
    
    ```bash
    npx playwright show-report
    ```
    
    Playwright 預設的 [HTML reporter](https://playwright.tw/docs/test-reporters#html-reporter) 會監聽 Port `9323` 讓你透過瀏覽器查看報表，所以你可以連到 [http://localhost:9323](http://localhost:9323) 開啟 HTML 測試報表。
    
    由於我們已經啟用 `Enable host networking` 功能的關係，所以你可以不用管容器的 IP 位址，直接在 Host 主機上開啟瀏覽器，連到 `http://localhost:9323` 就可以開啟 HTML 測試報表。
    
    不過，如果你使用舊版的 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 來執行容器，啟動容器時要加上 `-p 9323:9323` 參數，並且執行 `npx playwright show-report` 命令時，還要額外加上 `--host 0.0.0.0` 參數，否則你將無法從 Host 主機開啟瀏覽器透過 [http://localhost:9323](http://localhost:9323) 查看容器中的報表，設定相對麻煩許多。
    

### 後記

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

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

該學員最後也有分享，他參考 [Playwright.tw](https://playwright.tw/) 官網的 [HTTP Proxy](https://playwright.tw/docs/network#http-proxy) 文件，在 `playwright.config.ts` 加上 proxy 設定，就可以使用內網透過 webkit 連線到外網了！

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

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

### 相關連結

-   [Playwright - Microsoft Artifact Registry](https://mcr.microsoft.com/en-us/product/playwright/)
-   [Docker | Playwright](https://playwright.tw/docs/docker)
-   [網路 | Playwright](https://playwright.tw/docs/network#http-proxy)