Playwright 和 widget test 的互補

Widget test 在 Flutter test framework 中執行，不需要瀏覽器，驗證的是 widget tree 的結構和狀態。Playwright 在真實瀏覽器中執行，驗證的是渲染後的 DOM 和視覺呈現。

兩者的分工：widget test 驗證「邏輯上正確」（該有的元素存在、該觸發的事件發生），Playwright 驗證「視覺上正確」（元素在正確的位置、顏色和大小符合設計）。

Playwright test 的基本結構

 1import { test, expect } from '@playwright/test';
 2
 3test('terminal screen shows connection status', async ({ page }) => {
 4  await page.goto('http://localhost:8080');
 5  
 6  // 點擊連線按鈕
 7  await page.click('text=Connect Terminal');
 8  
 9  // 等待畫面轉換
10  await page.waitForSelector('[data-testid="terminal-screen"]');
11  
12  // 驗證連線狀態顯示
13  const status = page.locator('[data-testid="connection-status"]');
14  await expect(status).toBeVisible();
15});

三個位置的斷言

Playwright test 中的斷言放在三個位置，各自驗證不同的東西：

假設斷言（test 開頭）：驗證 test 的前置條件。頁面載入成功、初始狀態正確。如果假設斷言失敗，test 的後續結果不可信。

行為斷言（操作之後）：驗證 UI 操作的即時效果。點擊按鈕後 dialog 出現、表單提交後顯示成功訊息。

互動斷言（流程結束）：驗證完整操作流程的最終狀態。多步驟操作完成後畫面回到預期狀態。

Selector 策略

Playwright 用 selector 定位 DOM 元素。Selector 的穩定性決定了 test 的維護成本。

推薦：data-testid

在 HTML 元素上加 data-testid 屬性，Playwright 用 [data-testid="xxx"] 定位。data-testid 不受 CSS class 改名、文字內容變更、DOM 結構調整影響。

1<button data-testid="connect-button">Connect Terminal</button>

可接受：文字內容

用 text=Connect Terminal 定位。在按鈕文字穩定的場景下可用，但多語系支援或文案調整時會斷。

避免：CSS selector

用 .btn-primary 或 #main-content > div:nth-child(2) 定位。CSS class 和 DOM 結構的改動頻率高，test 頻繁因無關變更而失敗。

和開發伺服器的整合

Playwright test 需要一個正在運行的 web 應用。整合方式：

手動啟動：開發者先啟動 dev server，再跑 Playwright test。適合本地開發。

自動啟動：Playwright 設定檔中指定 webServer 配置，Playwright 自動啟動 dev server，test 結束後自動停止。適合 CI。

1// playwright.config.ts
2export default defineConfig({
3  webServer: {
4    command: 'npm run dev',
5    port: 8080,
6    reuseExistingServer: !process.env.CI,
7  },
8});

下一步路由

• 視覺比對 → 螢幕截圖比對
• 狀態覆蓋策略 → Widget test 的狀態覆蓋策略
• 導航路徑 test → 導航路徑 test

安裝 Zellij

1# macOS
2brew install zellij
3
4# Linux（使用安裝腳本）
5bash <(curl -L zellij.dev/launch)
6
7# Windows（需要支援原生 Windows 的版本，詳見 GitHub Releases）
8# 從 https://github.com/zellij-org/zellij/releases 下載 Windows 版 .zip
9# 解壓後將 zellij.exe 加入 PATH

確認版本（需 v0.43.0 以上）：

1zellij --version

事前準備

• 一個網域名稱（或固定 IP）
• SSL 憑證（對外連線強制要求）
• SSH 連線能力（如需遠端操作主機）→ 參考 SSH Key 設定筆記

步驟一：取得 SSL 憑證

外網連線強制使用 HTTPS，必須提供 SSL 憑證。

取得 Let’s Encrypt 憑證的 certbot 指令需真實網域、本機未實機驗證；自簽憑證的 openssl 指令、以及 zellij web server 啟停與 token 管理已在 localhost 實機驗證。

使用 Let’s Encrypt（免費，推薦）

需要先安裝 certbot：

1# macOS
2brew install certbot
3
4# Ubuntu / Debian
5sudo apt install certbot
6
7# Windows（使用 Chocolatey）
8choco install certbot
9# 或使用 win-acme（Windows 原生替代方案）：https://www.win-acme.com/

申請憑證（將 your-domain.com 換成實際網域）：

1sudo certbot certonly --standalone -d your-domain.com

Windows 上若未使用 WSL，建議改用 win-acme，操作更直覺。

憑證預設存放在：

1# macOS / Linux
2/etc/letsencrypt/live/your-domain.com/fullchain.pem   # 憑證
3/etc/letsencrypt/live/your-domain.com/privkey.pem      # 私鑰
4
5# Windows（certbot）
6C:\Certbot\live\your-domain.com\fullchain.pem
7C:\Certbot\live\your-domain.com\privkey.pem

使用自簽憑證（測試用）

1openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

注意：自簽憑證會讓瀏覽器在連線時顯示安全警告，於測試環境手動選擇繼續即可；正式對外服務改用上面的 Let’s Encrypt 憑證。

步驟二：開放防火牆 Port

Zellij web server 預設只綁本機 127.0.0.1:8082，要讓外網連入必須顯式綁到對外位址（見步驟四的 --ip 0.0.0.0）並開放對應 port。本教學以 port 3000 為例（port 可自選），需對外開放這個 port：

以下防火牆指令（ufw / pf / Windows Defender）依各平台官方用法、環境特定、本機未實機驗證。

Linux（ufw）

1sudo ufw allow 3000/tcp
2
3# 或指定來源 IP（更安全）
4sudo ufw allow from 1.2.3.4 to any port 3000

macOS

macOS 內建的防火牆是應用程式層級的，無法直接開放特定 port。通常有兩種做法：

1. 系統偏好設定 → 網路 → 防火牆 → 確認沒有擋住 Zellij
2. 使用 pf（進階，通常不需要）：

1# 新增規則到 /etc/pf.conf
2echo "pass in proto tcp from any to any port 3000" | sudo tee -a /etc/pf.conf
3sudo pfctl -f /etc/pf.conf

macOS 預設防火牆通常不會擋住主動開啟的服務，多數情況下不需要額外設定。如果是在家用網路，記得在路由器設定 port forwarding。

Windows

1# 使用 Windows Defender Firewall（以系統管理員執行 PowerShell）
2New-NetFirewallRule -DisplayName "Zellij Web" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow
3
4# 或限制來源 IP（更安全）
5New-NetFirewallRule -DisplayName "Zellij Web" -Direction Inbound -Protocol TCP -LocalPort 3000 -RemoteAddress 1.2.3.4 -Action Allow

Zellij 已支援原生 Windows，直接在 PowerShell 或 Windows Terminal 中執行即可。

如果是雲端主機（AWS、GCP、Azure 等），記得同步在後台的安全群組開放 port 3000。

步驟三：啟動 Zellij

先啟動一個 Zellij session：

1zellij

步驟四：啟動 Web Server

在 Zellij 內，按 Ctrl+o 然後按 s 開啟 share plugin，從 UI 啟動 web server。

或直接用 CLI 啟動並指定憑證：

1zellij web \
2  --ip 0.0.0.0 --port 3000 \
3  --cert /etc/letsencrypt/live/your-domain.com/fullchain.pem \
4  --key /etc/letsencrypt/live/your-domain.com/privkey.pem

背景執行（daemon 模式）：

1zellij web -d \
2  --ip 0.0.0.0 --port 3000 \
3  --cert /path/to/cert.pem \
4  --key /path/to/key.pem

停止 web server：

1zellij web --stop

確認 web server 執行狀態：

1zellij web --status

Zellij web 預設綁 127.0.0.1:8082、只接受本機連線；對外服務必須用 --ip 0.0.0.0 顯式綁到對外位址、並用 --port 指定埠（本教學用 3000）。改用其他 port 時把 --port 一併調整（例如 --port 8443），防火牆規則也要同步改成該 port。

步驟五：產生登入 Token

為了安全，別人連線前需要用 token 登入，token 只會顯示一次，請立即複製。

1zellij web --create-token

或在 share plugin（Ctrl+o + s）裡產生。

將 token 分享給要連線的人。

步驟六：連線

對方在瀏覽器輸入：

1https://your-domain.com:3000/實際-session-名稱

首次連線會要求輸入 token，驗證後即可進入 session。若連線後畫面沒有回應，多半是 port 未對外開放，確認防火牆與雲端主機安全群組是否放行該 port。

連線後的行為

多人連線時，每個人都有自己的游標，可以同時操作。

安全建議

• Token 用完後記得撤銷：從 share plugin 或 CLI 管理
• 盡量限制開放的來源 IP，避免對全網開放
• 不建議長期開啟 web server，用完就關
• 撤銷 token 時，所有對應的 session token 也會一併失效

下一步路由

• zellij 的本機 pane 操作（查看佈局、讀取其他 pane、調整大小）：Zellij 多終端機操作指南。
• 不需要瀏覽器、純 SSH 的多工器持久化：tmux 基礎。
• 多工器在整個遠端工具選型中的定位：終端機圖形化工具總覽。