PlaywrightのCLIは、テストを流す npx playwright test を中心に、操作を記録する codegen、ブラウザを入れる install、結果を開く show-report と show-trace が並ぶ構成になっています。設定ファイルを書き換えなくても、実行対象・並列数・レポーターはコマンドライン側から上書きできます。この記事では、実行の絞り込みから CI での分割実行とレポート統合まで、公式ドキュメントのオプション定義に沿って作業順に整理しました。バージョンは1.63系（2026年9月時点）を前提にしています。
まとめ：Playwright CLIで先に押さえる4つのコマンド
- test：ファイル名・
--project・-gの3つで対象を絞り、--workersと--retriesで実行時間を調整する。 - codegen：操作を記録してテストの下書きを作る。ログイン後の状態は
--save-storageでファイルに残して再利用する。 - install：ブラウザ本体とOS依存パッケージを入れる。CIでは
--with-depsを付け、描画が不要なら--only-shellで落とす量を減らす。 - show-report と merge-reports：単発の確認は show-report、分割実行したジョブの blob レポートは merge-reports で1つのHTMLに束ねる。
- 再実行の短縮は
--last-failedと--only-changed、不安定なテストの追い込みは--repeat-eachと--max-failuresが担当する。 - 1.63系では install の
--no-remove、codegen の--http-credentials、設定に足す--add-reporter、perfetto レポーターが加わった。
Playwright CLIはテスト実行と記録・導入の3系統に分かれる
Playwright のコマンドは数が多く見えますが、役割で分けると「テストを流す」「操作を記録する」「実行環境を整える」の3系統に収まります。どのサブコマンドも npx playwright に続けて書き、オプションは設定ファイルの値を上書きする指定です。公式のコマンドラインリファレンスには各オプションの定義が並んでおり、手元の版で使える範囲は npx playwright --help でも確認できます。
| サブコマンド | 担当する作業 |
|---|---|
| test | テストの実行と絞り込み |
| codegen | 操作の記録とコード生成 |
| install | ブラウザと依存の導入 |
| uninstall | 導入済みブラウザの削除 |
| show-report | HTMLレポートを開く |
| show-trace | トレースを開いて追跡 |
| merge-reports | 分割実行の結果を統合 |
| clear-cache | キャッシュの削除 |
npx playwright testが受け取る引数とオプションの並び方
test コマンドの書式は npx playwright test [options] [test-filter...] です。フィルタは正規表現としてファイルパスに照合されるため、ディレクトリ名の一部を書くだけでも対象を狭められます。オプションとフィルタの順序は問われませんが、読み手が追いやすいようにオプションを先、対象を後ろに置く書き方をチームで揃えておくと差分が読みやすくなります。
# すべて実行
npx playwright test
# ファイル1本だけ
npx playwright test tests/todo-page.spec.ts
# ディレクトリを2つ指定
npx playwright test tests/todo-page/ tests/landing-page/npx経由で実行してプロジェクトごとにPlaywrightの版を固定する
CLIをグローバルに入れると、案件ごとに版がずれてブラウザの同梱バージョンも食い違います。npx を挟めば node_modules 配下の実体が呼ばれ、package.json で固定した版がそのまま走ります。版の確認方法やリリース履歴の追い方はPlaywrightの最新バージョンは1.63｜確認・更新方法とリリース履歴で扱っているので、更新のタイミングはそちらで判断してください。導入そのものでつまずいた場合はPlaywrightのインストール方法とできない時の対処が入口になります。
npx playwright testでファイルとプロジェクトを絞って実行する
ローカルでの待ち時間は、対象を狭めるだけで大きく縮みます。Playwright の絞り込みは、ファイルパス、--project によるブラウザやデバイス単位、-g によるテスト名の3つを組み合わせる形です。3つは同時に指定でき、条件はすべて満たすものだけが実行されます。
ファイル指定・プロジェクト指定・grepで対象を狭める書き方
--project は playwright.config に定義したプロジェクト名を受け取り、公式定義では「指定されたプロジェクトのリストのみからテストを実行」します。-g（--grep）はテスト名に対する正規表現で、除外側は --grep-invert です。ブラウザを表示して目視したいときは --headed、ステップ実行で止めたいときは --debug を足します。
# Chromiumのプロジェクトだけ、名前に「ログイン」を含むテスト
npx playwright test --project=chromium -g "ログイン"
# 画面を出して1件ずつ確認する
npx playwright test tests/login.spec.ts --headed --workers=1
# インスペクタを開いて止めながら追う
npx playwright test tests/login.spec.ts --debugworkersとretriesをCLIから上書きして実行時間を詰める
--workers は同時ワーカー数で、数値のほかCPUコア数に対する割合でも渡せます。CI で他のジョブと資源を奪い合うときは、割合での指定が有効です。--retries は不安定なテストの再試行回数で、原因を突き止めたい局面ではむしろ0に落とし、失敗をそのまま観測する使い方をします。設定ファイルの値を一時的に外したいだけなら、CLI 側の上書きで済ませるほうが差分を残さずに済みます。
# CPUの50%をワーカーに割り当てる
npx playwright test --workers=50%
# 再試行を止めて失敗をそのまま見る
npx playwright test --retries=0 --workers=1失敗したテストだけを再実行して原因の切り分けを短い時間で終える
全件を流し直すと、直したい1件の結果が出るまで待たされます。Playwright には前回の失敗分だけを拾う --last-failed と、変更されたファイルだけを走らせる --only-changed があり、修正と確認の往復を短くできます。
–last-failedと–only-changedで再実行の範囲を絞る
--last-failed は公式定義で「失敗したテストのみを再実行」、--only-changed [ref] は「HEADと指定参照間で変更されたテストファイルのみを実行」と説明されています。後者はブランチ名やコミットを渡せるため、レビュー前の自己確認をブランチの差分に限定することが可能です。未コミットの変更も対象に入るので、書きかけのテストを流すときにも使えます。
# 直前の実行で落ちたテストだけ
npx playwright test --last-failed
# mainとの差分で変わったテストファイルだけ
npx playwright test --only-changed=main–repeat-eachと–max-failuresで不安定なテストを追う
たまに落ちるテストは、1回の実行では再現しません。--repeat-each は各テストをN回繰り返す指定で、再現率を測る用途に向きます。逆に、落ちた時点で止めて調査に入りたいときは --max-failures（短縮形は -x）でN件目の失敗を実行の打ち切り条件にする指定です。両者を組み合わせると、20回中で何回落ちるかを測りつつ、最初の失敗のトレースだけを確実に残せます。テスト自体の書き方で不安定さを減らす話はE2E（エンドツーエンド）テストのベストプラクティスにまとめています。
# 同じテストを20回繰り返して再現率を測る
npx playwright test tests/flaky.spec.ts --repeat-each=20 --retries=0
# 1件落ちたら即座に止める
npx playwright test -xcodegenでブラウザ操作を記録してテストコードの下書きを作る
codegen は、ブラウザ上の操作を記録してテストコードへ書き起こすサブコマンドです。ロケータの候補を自動で選ぶため、手書きよりも早く骨組みが作れます。生成されたコードはそのまま使うのではなく、ロケータの妥当性と待機の入り方を見て整える前提で扱ってください。
ログイン状態をファイルに保存して認証後の画面の記録を再開する手順
認証後の画面を記録したい場合、毎回ログインし直すのは手間です。公式のCodegenドキュメントには、--save-storage でクッキーとローカルストレージをファイルへ保存し、次回は --load-storage で読み込む手順が示されています。デバイスやカラースキーム、言語やタイムゾーンを指定した状態での記録にも対応します。
# ログインして状態をauth.jsonに保存
npx playwright codegen github.com/microsoft/playwright --save-storage=auth.json
# 保存した状態を読み込んで記録を再開
npx playwright codegen --load-storage=auth.json github.com/microsoft/playwright
# デバイスとカラースキームを指定して記録
npx playwright codegen --device="iPhone 13" --color-scheme=dark playwright.dev記録したコードを本番のテストへ育てる段階では、ページ単位で操作をまとめる設計に切り替える判断が出てきます。判断材料はPage Object Model（POM）とは？Playwright・Seleniumの実装例と保守コストの実測で整理しました。
installでブラウザとOS依存パッケージを入れる手順を分ける
Playwright はブラウザ本体を自前で管理します。npx playwright install は Chromium・Firefox・WebKit を落とし、Linux では別途OS側の共有ライブラリを用意することが必要です。ローカルとCIで必要な範囲が違うため、入れる対象を絞る指定を覚えておくと待ち時間とディスクを節約できます。
–with-depsと–only-shellをCIで使い分ける基準
公式のBrowsersドキュメントによれば、--with-deps はブラウザとOS依存パッケージを1コマンドで入れる指定です。ヘッドレス実行しかしないなら、--only-shell を付けることで「Chromium本体のダウンロードを避けられる」と説明されています。逆にヘッドレスシェルが不要な構成では --no-shell でその分を省くことが可能です。CIのコンテナではブラウザを1種類に絞るだけでも、ジョブの開始が目に見えて早くなります。
# ブラウザとOS依存をまとめて導入（Chromiumのみ）
npx playwright install --with-deps chromium
# ヘッドレス専用。フルのChromiumを落とさない
npx playwright install --with-deps --only-shell
# 逆にヘッドレスシェルが不要なとき
npx playwright install --with-deps --no-shell導入済みブラウザの保存先の確認と不要になったキャッシュの掃除手順
ダウンロード先は既定でユーザー配下のキャッシュフォルダになり、Windowsは ms-playwright フォルダ、macOSはライブラリのキャッシュ、Linuxはドットキャッシュ配下に置かれます。場所を変えるときは環境変数 PLAYWRIGHT_BROWSERS_PATH を指定し、リポジトリ内に閉じたい場合に設定する値は0です。導入済みの一覧は --list、削除は uninstall で、現在の版のブラウザだけか全部かを選べます。
# どの版のブラウザが入っているか一覧で見る
npx playwright install --list
# 今の版のブラウザだけ削除／すべて削除
npx playwright uninstall
npx playwright uninstall --all
# キャッシュをまとめて消す
npx playwright clear-cacheCIでシャード実行しmerge-reportsでレポートを束ねる
テストが増えると、1ジョブでの実行時間が伸びてリリース前の待ちが長くなります。Playwright は --shard=x/y の書式で全体をy個に分割し、x番目だけを実行する仕組みです。分割したジョブはそれぞれ独立したレポートを持つため、そのままでは結果が散らばります。ここで blob レポーターと merge-reports を使い、最後に1つのHTMLへ統合します。
各シャードのblobレポートを集めて1つのHTMLに統合するまでの流れ
公式のShardingドキュメントでは、blob レポートに「実行されたすべてのテストとその結果、およびトレースやスクリーンショット差分などの全テスト添付ファイル」が含まれると説明されています。各シャードの成果物をまとめてダウンロードし、merge-reports に渡すことで統合レポートを得る仕組みです。設定側で fullyParallel を有効にしておくと、ファイル単位ではなくテスト単位で分配されるため、シャード間の実行時間の偏りが小さくなります。
# 4分割したうちの1番目をblob形式で実行
npx playwright test --shard=1/4 --reporter=blob
# 集めたblobレポートを1つのHTMLに統合
npx playwright merge-reports --reporter html ./all-blob-reports
# 統合時にレポーターを複数指定することもできる
npx playwright merge-reports --reporter=html,github ./all-blob-reportsGitHub Actions ならマトリクスでシャード番号を配り、最後に統合ジョブを1つ置く形になります。分割数を増やすほど並列で短くなりますが、ジョブ起動とブラウザ導入の固定費が毎回かかるため、1シャードあたりの実行が1分を切るあたりから伸びは鈍ります。
strategy:
fail-fast: false
matrix:
shard: [1, 2, 3, 4]
steps:
- run: npx playwright install --with-deps chromium
- run: npx playwright test --shard=${{ matrix.shard }}/4 --reporter=blobレポーターとトレースをCLIから切り替えて失敗の中身を追う手順
実行結果の見え方はレポーターで決まります。公式のReportersドキュメントには list・line・dot・html・blob・json・junit・perfetto・github・null が並び、既定はローカルが list、CI環境が dot です。CLI からは --reporter で切り替えます。出力先はレポーターごとの環境変数で変えられ、HTMLレポートの自動表示は PLAYWRIGHT_HTML_OPEN で制御します。
show-reportとshow-traceで実行後の記録を開く手順
HTMLレポートを開くためのコマンドは npx playwright show-report です。失敗の中身を追うには trace が要り、公式のTrace viewerドキュメントの手順どおり、取得した trace.zip を show-trace に渡すとアクションごとのスナップショットとネットワークを追えます。CIで落ちたときは、レポートと trace を成果物として保存しておくと、手元で同じ画面を開けます。
# 直前の実行のHTMLレポートを開く
npx playwright show-report
# レポーターを切り替えて実行する
npx playwright test --reporter=line
npx playwright test --reporter=junit
# 保存されたトレースを開く
npx playwright show-trace test-results/login-chromium/trace.zipPlaywright 1.63で増えたCLIオプションを実行して確かめる
1.63系では、CLI側にも追加が入りました。公式のリリースノートには、install の --no-remove が「他のPlaywright導入のブラウザを削除せずに残す」、codegen の --http-credentials が「HTTP認証の背後にあるページに対して記録する」と記されています。前者は複数バージョンを並行させている開発機で効きます。
レポーター側では --add-reporter が加わりました。既存の --reporter が設定ファイルの指定を置き換えるのに対し、--add-reporter は設定済みのレポーターの上に追加する動きです。公式のリファレンス上、どちらもカンマ区切りで複数のレポーターを受け取る指定と説明されており、既定の形式に別形式を重ねる書き方も可能です。CIで既定のレポート構成を保ったまま、その回だけ別形式を足したいときに使えます。あわせて perfetto レポーターが増え、Perfetto UI やブラウザのトレース画面で開けるトレースイベント形式のファイルを書き出せます。オプション名と挙動は1.63系時点のもので、版を上げる際はリリースノートとGitHubのリリース一覧を突き合わせてください。
# 他の導入分のブラウザを消さずに追加する
npx playwright install --no-remove
# 設定のレポーターを保ったまま出力を1つ足す
npx playwright test --add-reporter=perfettoなお、Playwright そのものの仕組みや Selenium との違いから確認したい場合はPlaywrightとは｜仕組み・できること・Seleniumとの違いを解説を先に読むと、CLIの各オプションが何を切り替えているか掴みやすくなります。
受託開発でPlaywright CLIをどこまで使うか条件で示す
CLIのオプションは強力ですが、何でもコマンドラインに書くとチーム内で実行条件がばらつきます。どこまでをCLIに任せ、どこから設定ファイルへ移すかは、実行者が誰かで線を引くのが現実的です。
CLIの指定だけで回してよい条件とチーム共通の設定ファイルへ移す境目
手元での調査、単発の再現確認、CIの一時的な切り分けは、CLIの指定だけで回して差し支えありません。判断の分かれ目は「同じ指定を2回以上、別の人が打つか」です。2回目が発生した時点で、その指定は playwright.config やnpm scriptsへ移し、コマンドは短い名前で呼べる形にしてください。--workers や --retries のように環境で変えたい値は設定側に既定を置き、CLIは上書き専用と決めておくと、CIログから実際の実行条件を読み取れます。テスト基盤の整備と運用の内製化を外部と進める場合は、保守運用・内製化支援のように運用まで含めて引き受ける体制と組むと、設定の置き場所とCIの構成を一度に決められます。
担当者や実行環境からCLI中心の運用を見送りUIモードや別手段へ寄せる場面
次の3つに当てはまるなら、CLI中心の運用は見送ってよい場面です。第一に、テストを書く担当が非エンジニアで、コマンドの前提知識を揃える負荷が大きいとき。--ui のUIモードや、記録中心の運用へ寄せたほうが定着します。第二に、実行環境がブラウザの導入を許さない管理端末で、install の段階で止まるとき。この場合はコンテナ側に寄せるか、ホスト型の実行サービスを検討します。第三に、テスト数が数十本規模でシャード分割の効果が出ないとき。分割の固定費のほうが大きく、単一ジョブのままで運用したほうが総時間は短くなります。
よくある質問
Playwright CLIで使えるコマンドの一覧はどこで確認できますか？
公式のコマンドラインリファレンスに、test・codegen・install・show-report・show-trace・merge-reports・clear-cache などのサブコマンドとオプション定義が並んでいます。手元の版で使える範囲を確認するなら npx playwright --help が確実で、サブコマンド単位のオプションは test や codegen に続けて help を付けると出ます。
npx playwright testと直接のplaywright testは何が違いますか？
npx を付けるとプロジェクトの node_modules 配下にある実体が呼ばれ、package.json で固定した版で走ります。グローバル導入したコマンドを直接叩くと、案件ごとに版がずれてブラウザの同梱バージョンも食い違うことがあるため、チーム開発では npx 経由に揃える運用が扱いやすくなります。
特定のテストだけを実行するにはどう書きますか？
ファイルパスを引数に渡すのが最も短く、テスト名で絞るなら -g に正規表現を渡します。ブラウザやデバイスの単位で分けているなら --project を併用し、3つを組み合わせて対象を狭める方法が有効です。前回の失敗分に限るなら --last-failed、差分に限るなら --only-changed が使えます。
CIでブラウザのインストールは毎回必要ですか？
コンテナを毎回作り直す構成では、ブラウザのインストールも毎回必要です。導入時間を削るには、ブラウザを1種類に絞る、ヘッドレスのみなら --only-shell を使う、あるいはブラウザを含めたイメージを事前に作っておく方法があります。キャッシュ位置は環境変数で変更でき、その場所をジョブ間でキャッシュする構成も取れます。
CLIのオプションと設定ファイルはどちらが優先されますか？
コマンドラインで渡した値が playwright.config の指定を上書きします。レポーターについては、置き換える --reporter と、設定済みのものに足す --add-reporter が1.63系で使い分けられるようになりました。恒久的に変えたい値は設定ファイル、その場限りの調整はCLI、と役割を分けておくと実行条件が追いやすくなります。
関連記事
- Playwrightとは｜仕組み・できること・Seleniumとの違いを解説：CLIの各オプションが切り替えている対象を理解するための前提
- Playwrightのインストール方法とできない時の対処｜バージョン確認・Windows対応：installコマンドが途中で止まるときの原因切り分け
- Playwrightの最新バージョンは1.63｜確認・更新方法とリリース履歴【2026年9月】：本記事のオプションが使える版かどうかの確認方法
- Page Object Model（POM）とは？Playwright・Seleniumの実装例と保守コストの実測：codegenの生成コードを保守できる形へ育てる設計
- E2E（エンドツーエンド）テストのベストプラクティス｜結合テストとの違いとツール選定：不安定なテストを減らすための書き方と運用
