命令列

Playwright 提供強大的命令列介面，用於執行測試、產生程式碼、偵錯等等。您可以透過 npx playwright --help 隨時取得 CLI 上最新的指令與參數清單。

基本指令

執行測試

執行您的 Playwright 測試。閱讀更多關於執行測試的資訊。

語法

npx playwright test [options] [test-filter...]

範例

# 執行所有測試
npx playwright test

# 執行單一測試檔案
npx playwright test tests/todo-page.spec.ts

# 執行一組測試檔案
npx playwright test tests/todo-page/ tests/landing-page/

# 執行特定行的測試
npx playwright test my-spec.ts:42

# 依標題執行測試
npx playwright test -g "add a todo item"

# 在有頭瀏覽器中執行測試
npx playwright test --headed

# 執行特定專案的測試
npx playwright test --project=chromium

# 取得幫助
npx playwright test --help

停用平行化

npx playwright test --workers=1

使用 Playwright Inspector 在偵錯模式中執行

npx playwright test --debug

在互動式 UI 模式下執行測試

npx playwright test --ui

常用選項

選項	說明
--debug	使用 Playwright Inspector 執行測試。等同於 PWDEBUG=1 環境變數與 --timeout=0 --max-failures=1 --headed --workers=1 選項的快捷方式。
--headed	在有頭瀏覽器中執行測試（預設：無頭）。
-g <grep> 或 --grep <grep>	只執行符合此正規表示式的測試（預設：".*"）。
--project <project-name...>	只執行指定專案清單中的測試，支援 '*' 萬用字元（預設：執行所有專案）。
--ui	在互動式 UI 模式中執行測試。
-j <workers> 或 --workers <workers>	並行工作程序數量或邏輯 CPU 核心的百分比，使用 1 表示在單一工作程序中執行（預設：50%）。

所有選項

選項	說明
非選項參數	每個參數都被視為針對完整測試檔案路徑的正規表示式。只有來自符合模式的檔案的測試會被執行。特殊符號如 $ 或 * 應該使用 \ 跳脫。在許多 shell/終端機中，您可能需要將參數加上引號。
-c <file> 或 --config <file>	組態檔案，或包含可選 "playwright.config.{m,c}?{js,ts}" 的測試目錄。預設為目前目錄中的 playwright.config.ts 或 playwright.config.js。
--debug	使用 Playwright Inspector 執行測試。等同於 PWDEBUG=1 環境變數與 --timeout=0 --max-failures=1 --headed --workers=1 選項的快捷方式。
--fail-on-flaky-tests	如果有任何測試被標記為不穩定則失敗（預設：false）。
--forbid-only	如果呼叫 test.only 則失敗（預設：false）。在 CI 上很有用。
--fully-parallel	平行執行所有測試（預設：false）。
--global-timeout <timeout>	此測試套件可執行的最大時間（毫秒）（預設：無限制）。
-g <grep> 或 --grep <grep>	只執行符合此正規表示式的測試（預設：".*"）。
--grep-invert <grep>	只執行不符合此正規表示式的測試。
--headed	在有頭瀏覽器中執行測試（預設：無頭）。
--ignore-snapshots	忽略螢幕截圖與快照預期。
-j <workers> 或 --workers <workers>	並行工作程序數量或邏輯 CPU 核心的百分比，使用 1 表示在單一工作程序中執行（預設：50%）。
--last-failed	只重新執行失敗的測試。
--last-run-file	最後執行文件的路徑 (預設值: "test-results/.last-run.json")。此 json 文件用於 --last-failed 選項。您也可以在 filterTests 屬性中提供 testCase.id 陣列，以應用自定義過濾器。
--list	收集所有測試並回報，但不執行。
--max-failures <N> 或 -x	在第一個 N 次失敗後停止。傳遞 -x 會在第一次失敗後停止。
--no-deps	不執行專案相依性。
--output <dir>	輸出成品的資料夾（預設："test-results"）。
--only-changed [ref]	只執行在 'HEAD' 與 'ref' 之間已變更的測試檔案。預設執行所有未提交的變更。僅支援 Git。
--pass-with-no-tests	即使沒有找到測試，也讓測試執行成功。
--project <project-name...>	只執行指定專案清單中的測試，支援 '*' 萬用字元（預設：執行所有專案）。
--quiet	隱藏標準輸入輸出。
--repeat-each <N>	每個測試執行 N 次（預設：1）。
--reporter <reporter>	要使用的報告器，以逗號分隔，可以是 "dot"、"line"、"list" 或其他（預設："list"）。您也可以傳遞自訂報告器檔案的路徑。
--retries <retries>	不穩定測試的最大重試次數，零表示不重試（預設：不重試）。
--shard <shard>	分片測試並只執行選定的分片，以 "current/all" 形式指定，從 1 開始，例如 "3/5"。
--timeout <timeout>	指定測試逾時閾值（毫秒），零表示無限制（預設：30 秒）。
--trace <mode>	強制追蹤模式，可以是 on、off、on-first-retry、on-all-retries、retain-on-failure、retain-on-first-failure。
--tsconfig <path>	適用於所有匯入檔案的單一 tsconfig 路徑（預設：為每個匯入檔案分別查找 tsconfig）。
--ui	在互動式 UI 模式中執行測試。
--ui-host <host>	提供 UI 服務的主機；指定此選項會在瀏覽器分頁中開啟 UI。
--ui-port <port>	提供 UI 服務的連接埠，0 表示任何可用的連接埠；指定此選項會在瀏覽器分頁中開啟 UI。
-u 或 --update-snapshots [mode]	使用實際結果更新快照。可能的值有 "all"、"changed"、"missing" 與 "none"。不使用旗標執行測試預設為 "missing"；使用旗標但不提供值執行測試預設為 "changed"。
--update-source-method [mode]	使用實際結果更新快照。可能的值有 "patch"（預設）、"3way" 與 "overwrite"。"Patch" 建立統一的差異檔案，可稍後用於更新原始碼。"3way" 在原始碼中產生合併衝突標記。"Overwrite" 使用新的快照值覆寫原始碼。
-x	在第一次失敗後停止。

顯示報告

顯示先前測試執行的 HTML 報告。閱讀更多關於 HTML 報告器的資訊。

語法

npx playwright show-report [report] [options]

範例

# 顯示最新的測試報告
npx playwright show-report

# 顯示特定報告
npx playwright show-report playwright-report/

# 在自訂連接埠上顯示報告
npx playwright show-report --port 8080

選項

選項	說明
--host <host>	提供報告服務的主機（預設：localhost）
--port <port>	提供報告服務的連接埠（預設：9323）

安裝瀏覽器

安裝 Playwright 所需的瀏覽器。閱讀更多關於 Playwright 瀏覽器支援的資訊。

語法

npx playwright install [options] [browser...]
npx playwright install-deps [options] [browser...]
npx playwright uninstall

範例

# 安裝所有瀏覽器
npx playwright install

# 只安裝 Chromium
npx playwright install chromium

# 安裝特定瀏覽器
npx playwright install chromium webkit

# 安裝瀏覽器與相依性
npx playwright install --with-deps

安裝選項

選項	說明
--force	強制重新安裝穩定的瀏覽器通道
--with-deps	安裝瀏覽器系統相依性
--dry-run	不執行安裝，只列印資訊
--only-shell	只安裝 chromium-headless-shell，而不是完整的 Chromium
--no-shell	不安裝 chromium-headless-shell

安裝相依性選項

選項	說明
--dry-run	不執行安裝，只列印資訊

產生與偵錯工具

程式碼產生

錄製動作並為多種語言產生測試。閱讀更多關於 Codegen 的資訊。

語法

npx playwright codegen [options] [url]

範例

# 開始使用互動式 UI 錄製
npx playwright codegen

# 在特定網站上錄製
npx playwright codegen https://playwright.dev

# 產生 Python 程式碼
npx playwright codegen --target=python

選項

選項	說明
-b, --browser <name>	要使用的瀏覽器：chromium、firefox 或 webkit（預設：chromium）
-o, --output <file>	產生的腳本輸出檔案
--target <language>	要使用的語言：javascript、playwright-test、python 等
--test-id-attribute <attr>	用於測試 ID 的屬性

追蹤檢視器

分析並檢視測試追蹤以進行偵錯。閱讀更多關於追蹤檢視器的資訊。

語法

npx playwright show-trace [options] <trace>

範例

# 檢視追蹤檔案
npx playwright show-trace trace.zip

# 從目錄檢視追蹤
npx playwright show-trace trace/

選項

選項	說明
-b, --browser <name>	要使用的瀏覽器：chromium、firefox 或 webkit（預設：chromium）
-h, --host <host>	提供追蹤服務的主機
-p, --port <port>	提供追蹤服務的連接埠

專用指令

合併報告

讀取 blob 報告並合併它們。閱讀更多關於 merge-reports 的資訊。

語法

npx playwright merge-reports [options] <blob dir>

範例

# 合併測試報告
npx playwright merge-reports ./reports

選項

選項	說明
-c, --config <file>	組態檔案。可用於為輸出報告指定額外的組態設定
--reporter <reporter>	要使用的報告器，以逗號分隔，可以是 "list"、"line"、"dot"、"json"、"junit"、"null"、"github"、"html"、"blob"（預設："list"）

清除快取

清除所有 Playwright 快取。

語法

npx playwright clear-cache