Playwrightで失敗時だけ動画とスクリーンショットを残す設定
Playwright Test の設定ファイルで screenshot: 'only-on-failure' と video: 'retain-on-failure' を指定すると、失敗したテストについてだけ、最後の画面の PNG と、テスト中の操作を録画した WebM が残ります。CI で落ちた E2E テストのように、その場でブラウザを見られないテストでも、失敗したときの画面をあとから確かめられます。通ったテストの分は残らないので、成果物(artifacts)としてまとめて保存するときも、ファイルが増えすぎません。
私は検証環境で、わざと失敗するテストを用意し、この設定でどのファイルが残るか、リトライと組み合わせたときにどうなるか、録画で実行時間がどれだけ延びるかを確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけで動かしました。テストするページは、検証用に書いた小さな Node.js のサーバーが返すもので、外部のサイトには接続していません。CI の上での実行、Firefox・WebKit での録画、動画に操作の説明を重ねる show オプションは試していません。
失敗したときだけ残す設定
使ったのは、「カートに入れる」を押すとカートの中の個数が増えるページです。わざと不具合を入れてあり、3回目からは数が増えません。テストは2件で、1件目(1回押すと1個)は通り、2件目(3回押すと3個)は失敗します。
// tests/cart.spec.ts
import { test, expect } from '@playwright/test';
test('1回押すと1個になる', async ({ page }) => {
await page.goto('/');
await page.getByRole('button', { name: 'カートに入れる' }).click();
await expect(page.locator('#count')).toHaveText('カートの中:1個');
});
test('3回押すと3個になる', async ({ page }) => {
await page.goto('/');
const add = page.getByRole('button', { name: 'カートに入れる' });
await add.click();
await add.click();
await add.click();
await expect(page.locator('#count')).toHaveText('カートの中:3個', { timeout: 2000 });
});
設定は、playwright.config.ts の use に2行足すだけです。公式ドキュメントの Recording Options の節によると、スクリーンショットも動画も、何も指定しなければ撮りません。
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
reporter: [['list'], ['html', { open: 'never' }]],
use: {
baseURL: 'http://localhost:3000',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
webServer: {
command: 'node server.mjs',
url: 'http://localhost:3000',
},
});
screenshot: 'only-on-failure' は、テストが失敗したときに、終わった時点の画面を1枚撮ります。video: 'retain-on-failure' は、すべてのテストを録画したうえで、通ったテストの動画を消します(リファレンスの screenshot と video の説明による)。
実行すると残るファイル
npx playwright test を実行すると、2件目が失敗しました。エラーの下に、スクリーンショットと動画の場所が出ます(Call log とコードの抜粋は省いています)。
✓ 1 tests/cart.spec.ts:3:1 › 1回押すと1個になる (241ms)
✘ 2 tests/cart.spec.ts:9:1 › 3回押すと3個になる (2.4s)
1) tests/cart.spec.ts:9:1 › 3回押すと3個になる ───────────────────────────────────────────────────────────
Error: expect(locator).toHaveText(expected) failed
Locator: locator('#count')
Expected: "カートの中:3個"
Received: "カートの中:2個"
Timeout: 2000ms
(中略)
attachment #1: screenshot (image/png) ──────────────────────────────────────────────────────────
test-results/cart-3回押すと3個になる/test-failed-1.png
────────────────────────────────────────────────────────────────────────────────────────────────
attachment #2: video (video/webm) ──────────────────────────────────────────────────────────────
test-results/cart-3回押すと3個になる/video.webm
────────────────────────────────────────────────────────────────────────────────────────────────
Error Context: test-results/cart-3回押すと3個になる/error-context.md
test-results フォルダーの中は次のとおりでした(左の数字はバイト数)。通った1件目のフォルダーは、作られていません。
96 test-results/.last-run.json
1594 test-results/cart-3回押すと3個になる/error-context.md
35911 test-results/cart-3回押すと3個になる/test-failed-1.png
22570 test-results/cart-3回押すと3個になる/video.webm
スクリーンショットは 1280×720 の PNG、動画は VP8 の WebM で、大きさは 800×450、長さは 4.08 秒でした。この設定では、ビューポートの大きさを指定していません。
HTML レポートで失敗したテストを開くと、Screenshots と Videos の欄にこの2つが並び、レポートの画面の中で、画像と動画を見られました。どちらにも、カートの中が「2個」のまま止まっている画面が写っています。

比べるために、video: 'on' と screenshot: 'on' で実行すると、通った1件目のフォルダーにも video.webm と test-finished-1.png ができました。反対に両方 'off' にすると、残るのは error-context.md だけで、画面の記録はありません。
リトライと組み合わせたとき
リトライを設定したときの動きを見るため、--retries 1 を付けて試しました。テストは、さきほどの2件に、1回目だけ失敗してリトライで通るテストを1件足しています。リトライの実行は、フォルダー名の末尾に -retry1 が付きます。
video: 'retain-on-failure' のままだと、失敗した実行それぞれに動画とスクリーンショットが残りました。リトライで通った実行のフォルダーはありません。
1594 test-results/cart-3回押すと3個になる-retry1/error-context.md
35911 test-results/cart-3回押すと3個になる-retry1/test-failed-1.png
22517 test-results/cart-3回押すと3個になる-retry1/video.webm
1594 test-results/cart-3回押すと3個になる/error-context.md
35911 test-results/cart-3回押すと3個になる/test-failed-1.png
22670 test-results/cart-3回押すと3個になる/video.webm
1345 test-results/flaky-リトライで通るテスト/error-context.md
35998 test-results/flaky-リトライで通るテスト/test-failed-1.png
18595 test-results/flaky-リトライで通るテスト/video.webm
公式ドキュメントの設定例にある video: 'on-first-retry' にすると、動画はリトライの実行(-retry1)にだけ残りました。1回目の失敗の動画はありません。リトライで通ったテストにも動画が残っています。スクリーンショットは 'only-on-failure' のままなので、失敗した実行にだけ撮られています。
1594 test-results/cart-3回押すと3個になる-retry1/error-context.md
35911 test-results/cart-3回押すと3個になる-retry1/test-failed-1.png
22770 test-results/cart-3回押すと3個になる-retry1/video.webm
1594 test-results/cart-3回押すと3個になる/error-context.md
35911 test-results/cart-3回押すと3個になる/test-failed-1.png
12986 test-results/flaky-リトライで通るテスト-retry1/video.webm
1345 test-results/flaky-リトライで通るテスト/error-context.md
35998 test-results/flaky-リトライで通るテスト/test-failed-1.png
ときどきしか落ちないテストを調べたいなら、落ちたときの動画が残る 'retain-on-failure' のほうが向いています。'on-first-retry' で残るのは、2回目の実行の動画です。ほかに、1回目の実行だけ録画する 'retain-on-first-failure' などのモードもあり、公式ドキュメントの Video modes の表に、どの実行を録画してどれを残すかがまとまっています。
録画で延びる実行時間
'retain-on-failure' は、通るテストも録画してから消します。そのぶんの時間を見るため、すべて通るテスト20件を --workers 1 で、設定ごとに3回ずつ実行しました。表の時間は、Playwright が最後に出す 20 passed (…) の値です。
| video の設定 | 1回目 | 2回目 | 3回目 | 残った動画 |
|---|---|---|---|---|
'off' |
3.2秒 | 3.5秒 | 3.6秒 | 0本 |
'retain-on-failure' |
4.6秒 | 4.8秒 | 5.1秒 | 0本 |
'on' |
4.7秒 | 4.8秒 | 4.8秒 | 20本(test-results の合計 194,714〜226,702 バイト) |
この検証環境では、'retain-on-failure' でも 'on' とほぼ同じだけ時間が延び、'off' より1テストあたりおよそ0.07秒長くかかりました。公式ドキュメントの Video modes の表のとおり、どちらも、すべての実行を録画するモードです。違うのは、終わったあとに動画を残すかどうかだけです。テストの数が多いプロジェクトで実行時間を抑えたいときは、リトライのときだけ録画し、通るテストを録画しない 'on-first-retry' を選ぶ方法もあります。
なお npx playwright test --help を見ると、トレースの設定には実行時に切り替える --trace オプションがありますが、動画とスクリーンショットにはありませんでした。設定ファイルで指定します。トレースには、画面のほかにコンソールや通信の記録も入ります(公式ドキュメントのトレースビューアーの説明による)。
動画の大きさと、ページ全体のスクリーンショット
動画の大きさは、video をオブジェクトにして size で指定できます。640×360 を指定すると、できた動画は 640×360 になりました。
use: {
video: {
mode: 'retain-on-failure',
size: { width: 640, height: 360 },
},
},
指定しないときは、ビューポートを 800×800 に収まるように縮めた大きさになります(video のリファレンスによる)。ビューポートも指定していないときは 800×450 になる、とも書かれていて、最初の実行の動画はこの大きさでした。
スクリーンショットも、オブジェクトにして fullPage: true を付けると、見えている範囲だけでなく、スクロールした先までページ全体を撮ります。検証のページは縦に長いので、1280×720 だった画像が 1280×1239 になりました。
use: {
screenshot: { mode: 'only-on-failure', fullPage: true },
},
スクリーンショットと動画には、テスト中に表示された画面がそのまま写ります。テストでパスワードや個人情報を表示しているなら、CI の成果物として保存したファイルを、だれが見られるかに気をつけてください。





