カテゴリ目次
はじめに
Playwrightのテストは、npx playwright testというコマンド1つで実行できます。ただ、実際の開発・調査の現場では、これだけで済むことはほとんどありません。「1つのテストだけ動かしたい」「失敗した瞬間の様子を見たい」「CIでは並列に分割して実行したい」といった場面ごとに、コマンドの後ろにさまざまなオプションを付けて実行することになります。
npx playwright test --headed --trace onこのように、npx playwright testの後ろに続くオプションを知っているかどうかで、デバッグや調査にかかる時間が大きく変わります。逆に言えば、オプションを知らないと、本当は一発で解決できることを、手作業で何度もブラウザを開き直したり、コードにログを仕込んだりして時間を溶かしてしまいがちです。
この記事は、Playwrightのplaywright testコマンドで使えるCLIオプションを一望できる保存版リファレンスです。「あのオプション何だっけ」となったときに、このページを開けばすぐ見つかるようにまとめています。実在しないオプションを載せると余計に混乱を招くため、この記事では実際にPlaywrightに存在するオプションだけを扱っています。
姉妹記事として、expectのマッチャーをまとめたPlaywright の expect マッチャー完全リファレンスもあります。「検証の書き方」で迷ったらそちらを、「実行のしかた」で迷ったらこのページを見てもらえれば大丈夫です。
早見表：やりたいこと→オプション
「〜したい」から、使うべきオプションを逆引きできる表です。オプション名をクリックすると、詳しい説明と使用例のある見出しへジャンプします。
| やりたいこと | オプション |
|---|---|
| ブラウザの動きを目で見ながら実行したい | –headed |
| 好きな場所で一時停止してステップ実行したい | –debug |
| ウォッチしながら対話的にデバッグしたい | –ui |
| 失敗時の詳細な実行履歴（トレース）を記録したい | –trace |
| 特定のファイル・ディレクトリだけ実行したい | ファイル・ディレクトリ指定 |
| ファイルの特定の行のテストだけ実行したい | 行番号指定 |
| テスト名（タイトル）で絞り込みたい | -g, –grep |
| 特定のテストを除外したい | –grep-invert |
| 特定のブラウザ（プロジェクト）だけ実行したい | –project |
| さっき失敗したテストだけ再実行したい | –last-failed |
| gitで変更したファイルのテストだけ実行したい | –only-changed |
| 実行せずに一覧だけ見たい | –list |
| 並列数を変えたい・直列にしたい | –workers |
| 失敗時に自動でリトライしたい | –retries |
| フレーキーテストを疑って何度も流したい | –repeat-each |
| CIで分割並列実行したい | –shard |
| 一定数失敗したら打ち切りたい | –max-failures, -x |
| test.onlyの残留をCIで検知したい | –forbid-only |
| フレーキーテストがあれば全体を失敗扱いにしたい | –fail-on-flaky-tests |
| テスト1件ごとの制限時間を変えたい | –timeout |
| テストスイート全体の制限時間を設けたい | –global-timeout |
| 結果の表示形式を変えたい | –reporter |
| 成果物の出力先を変えたい | –output |
| 余計な出力を減らしたい | –quiet |
| スクリーンショットなどの基準を更新したい | –update-snapshots, -u |
| 設定ファイルを指定したい | –config, -c |
| HTMLレポートを開きたい | show-report |
| トレースファイルを見たい | show-trace |
| 操作を記録してコードを自動生成したい | codegen |
| ブラウザ本体をインストールしたい | install |
デバッグ・可視化
テストがなぜ失敗するのか分からないとき、まず頼りになるのがこのカテゴリのオプションです。
–headed
デフォルトではブラウザは画面に表示されない状態（ヘッドレス）で実行されますが、--headedを付けるとブラウザのウィンドウが実際に開き、動きを目で確認しながら実行できます。
npx playwright test --headed–debug
Playwright Inspectorという専用のデバッグツールを開き、テストを1ステップずつ実行できるようにします。各操作の前で一時停止し、ページの状態やロケータの一致状況を確認しながら進められます。
npx playwright test tests/login.spec.ts --debug–ui
UIモードでテストランナーを起動します。テストの一覧をウォッチしながら実行でき、実行後は各ステップの「タイムトラベル」（各操作時点のDOMスナップショットをさかのぼって確認できる機能）でじっくり調査できます。日常的な開発中のデバッグ手段として特におすすめです。
npx playwright test --ui–trace
テスト実行中の操作・スクリーンショット・ネットワーク通信などをまとめて記録する「トレース」の取得タイミングを指定します。on（常に記録）・off（記録しない）・on-first-retry（最初のリトライ時のみ記録）・retain-on-failure（失敗したテストの分だけ記録を残す）などが指定できます。
# 常にトレースを記録する
npx playwright test --trace on
# CIでは、失敗して最初にリトライしたときだけ記録する（容量を抑えられる）
npx playwright test --trace on-first-retry記録したトレースは、後述のshow-traceで開いて確認します。
実行対象の絞り込み
すべてのテストを毎回流すのではなく、今調べたい範囲だけに絞り込むためのオプションです。
ファイル・ディレクトリ指定
コマンドの後ろにファイルパスやディレクトリパスを指定すると、そのファイル（またはディレクトリ配下のテストファイル）だけを実行します。
npx playwright test tests/login.spec.ts
npx playwright test tests/e2e/行番号指定
ファイルパスの後ろに:行番号を付けると、その行にあるテスト（test(...)の呼び出し）だけをピンポイントで実行できます。
npx playwright test tests/login.spec.ts:10-g, –grep
テストのタイトル（test("〜", ...)の文字列部分）を正規表現でフィルタし、一致するテストだけを実行します。
npx playwright test -g "ログイン"
npx playwright test --grep "@smoke"よくある使い所: テストのタイトルに@smokeのようなタグを仕込んでおき、スモークテストだけを実行したいとき。
–grep-invert
-g/--grepとは逆に、指定したパターンに一致しないテストだけを実行します。
npx playwright test --grep-invert "@slow"–project
playwright.config.tsで定義した「プロジェクト」（多くの場合Chromium・Firefox・WebKitなどのブラウザ単位）のうち、指定したものだけを実行します。複数指定も可能です。
npx playwright test --project=chromium
npx playwright test --project=chromium --project=webkit–last-failed
直前の実行で失敗したテストだけを再実行します。修正後にすべてを流し直さず、失敗していた箇所だけを素早く確認したいときに便利です。
npx playwright test --last-failed–only-changed
gitで変更されたファイルに関連するテストだけを実行します。変更内容から影響範囲を推測して絞り込んでくれるため、開発中に「関係ありそうなテストだけ」を素早く回したいときに使います。
npx playwright test --only-changed–list
テストを実際には実行せず、実行対象となるテストの一覧だけを表示します。他のフィルタオプション（-gなど）と組み合わせて、「このフィルタでどのテストが対象になるか」を事前に確認したいときに使います。
npx playwright test --grep "ログイン" --list並列・リトライ・安定化
実行速度や、実行結果の安定性（フレーキーテスト対策）に関わるオプションです。
–workers
テストを並列実行するワーカー（プロセス）の数を指定します。数値を大きくすると速くなりますが、マシンのリソースやテスト対象のサーバー負荷と相談する必要があります。--workers=1を指定すると直列（1つずつ順番）実行になり、実行順序に依存する不具合の切り分けに役立ちます。
npx playwright test --workers=4
# 直列実行にして、並列実行が原因かどうかを切り分ける
npx playwright test --workers=1–retries
テストが失敗したときに、指定した回数だけ自動的に再実行します。ネットワークの一時的な遅延など、環境要因によるまれな失敗（フレーキーテスト）を吸収するために使われます。
npx playwright test --retries=2補足: リトライはあくまで対症療法です。多用しすぎると、本当のバグを見逃す原因にもなるため注意してください。
–repeat-each
各テストを指定した回数だけ繰り返し実行します。「たまに失敗する」というフレーキーテストの再現性を確かめたいときに使います。
npx playwright test tests/login.spec.ts --repeat-each=10–shard
テスト全体を指定した数に分割し、そのうちの1つだけを実行します。CIで複数のマシン（ジョブ）に分散して並列実行し、全体の実行時間を短縮するために使います。
# 全体を3分割し、1番目のシャードだけ実行する
npx playwright test --shard=1/3–max-failures, -x
指定した件数の失敗が発生した時点で、それ以降のテスト実行を打ち切ります。-xは「1件失敗したら即座に打ち切る」の省略形です。
npx playwright test --max-failures=5
npx playwright test -xよくある使い所: 大きな環境障害が起きているときに、全件失敗するまで待たされずに早く気づきたいとき。
–forbid-only
コード中にtest.only（そのテストだけを実行する指定）が残っていた場合、テストをエラーとして扱います。開発中に一時的に付けたtest.onlyをうっかりコミットし、CIで一部のテストしか実行されなくなる事故を防ぐため、CI用の設定として使われます。
npx playwright test --forbid-only–fail-on-flaky-tests
リトライの末に最終的には成功した「フレーキーテスト」が1件でもあった場合、コマンド全体の終了コードを失敗扱いにします。「リトライで通ったから良し」とせず、不安定なテストの存在自体をCIで検知したいときに使います。
npx playwright test --fail-on-flaky-testsタイムアウト
処理にかけてよい時間の上限を指定するオプションです。
–timeout
テスト1件あたりの制限時間をミリ秒単位で指定します。この時間を超えるとそのテストはタイムアウトとして失敗になります。
npx playwright test --timeout=60000–global-timeout
テストスイート全体（すべてのテストの合計）にかけられる制限時間をミリ秒単位で指定します。CIの実行時間そのものに上限を設けたいときに使います。
npx playwright test --global-timeout=600000レポート・出力
実行結果をどう表示するか、どこに出力するかを指定するオプションです。
–reporter
実行結果の表示形式（レポーター）を指定します。list（1件ずつ詳細表示）・line（1行で進捗表示）・dot（ドットで簡易表示）・html（ブラウザで見られるHTMLレポート）・json・junit（CIツール連携用）などがあり、カンマ区切りで複数同時に指定することもできます。
npx playwright test --reporter=html
npx playwright test --reporter=list,junit–output
スクリーンショットやトレース、動画などの成果物（アーティファクト）を保存するディレクトリを指定します。
npx playwright test --output=test-results–quiet
コンソールへの出力を抑え、必要最小限の情報だけを表示します。CIのログを見やすくしたいときなどに使います。
npx playwright test --quietスナップショット・設定
スナップショットの更新や、設定ファイルの切り替えに関するオプションです。
–update-snapshots, -u
toHaveScreenshotなどで使うスクリーンショットや、その他のスナップショットの基準ファイルを、現在の実行結果で更新（上書き）します。デザイン変更などで基準画像を意図的に更新したいときに使います。
npx playwright test --update-snapshots
npx playwright test -u注意: 意図しない見た目の崩れまで「正しい状態」として上書きしてしまわないよう、実行前に差分を目視で確認してから使うのが安全です。
–config, -c
読み込む設定ファイルのパスを明示的に指定します。環境ごとに設定ファイルを分けている場合などに使います。
npx playwright test --config=playwright.staging.config.tsあわせて覚える関連コマンド
playwright test本体のオプションではありませんが、セットで覚えておくと便利なnpx playwrightのサブコマンドを紹介します。
show-report
直前のテスト実行で生成されたHTMLレポートをブラウザで開きます。
npx playwright show-reportshow-trace
–traceオプションなどで記録したトレースファイル（.zip）を、トレースビューアで開いて確認します。各操作の前後のスクリーンショット、DOMの状態、ネットワーク通信などを時系列でたどれます。
npx playwright show-trace trace.zipcodegen
指定したURLでブラウザを開き、実際にクリックや入力といった操作をすると、それに対応するPlaywrightのコードを自動生成してくれます。ロケータの書き方に迷ったときの取っかかりとしても便利です。
npx playwright codegen https://example.cominstall
テストの実行に必要なブラウザ本体（Chromium・Firefox・WebKitなど）をダウンロード・インストールします。新しい環境でセットアップするときに最初に実行するコマンドです。
npx playwright installCLIとplaywright.config.tsの関係
ここまで紹介してきたオプションの多くは、実はplaywright.config.tsの設定としても同じ内容を書くことができます。たとえば--workersや--retries、--timeout、--reporterなどは、設定ファイル側にデフォルト値として定義しておくのが一般的です。
// playwright.config.ts
import { defineConfig } from "@playwright/test";
export default defineConfig({
workers: 4,
retries: 2,
timeout: 30000,
reporter: "html",
});このとき覚えておきたいのは、CLIオプションは設定ファイルの値より優先されるという関係です。つまり、playwright.config.tsにworkers: 4と書かれていても、実行時にnpx playwright test --workers=1と指定すれば、その回だけは1（直列）で動きます。
普段の基本設定はplaywright.config.tsにまとめておき、「今回だけ一時的に変えたい」というときにCLIオプションで上書きする、という使い分けが基本になります。
初心者向けまとめ：まずこれ
- 動きを見ながら確認したいときは
--headedを付けて実行する - テストが落ちたときは、
--trace onを付けて再実行するか、--debugでステップ実行して原因を探る - 日常的な開発中のデバッグは
--uiがもっとも情報量が多く、まず試す価値があります - 実行結果を後からじっくり見たいときはshow-reportでHTMLレポートを開く
- 迷ったら、まず早見表に戻ってきてください
これだけ覚えておけば、「動きを見る → 落ちたら記録を取る・ステップ実行する → レポートで確認する」という一連の調査の流れがひとりで回せるようになります。オプションの詳細な仕様はバージョンによって追加・変更されることがあるため、より正確な情報が必要なときは公式のCLIリファレンスもあわせて確認することをおすすめします。
コメント