Playwrightで失敗時だけ動画とスクリーンショットを残す設定

​​Playwright​E2Eテスト,TypeScript,トラブルシュート

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個)は失敗します。

ts
// 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 の節によると、スクリーンショットも動画も、何も指定しなければ撮りません。

ts
// 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 とコードの抜粋は省いています)。

text
  ✓  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件目のフォルダーは、作られていません。

text
      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個」のまま止まっている画面が写っています。

Playwright の HTML レポートで、失敗したテストの Screenshots と Videos の欄を開いた画面。上のスクリーンショットにも、下の動画(0:03 の位置で止めたもの)にも「カートの中:2個」と出ている
HTML レポートに添付された、失敗時のスクリーンショットと動画

比べるために、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' のままだと、失敗した実行それぞれに動画とスクリーンショットが残りました。リトライで通った実行のフォルダーはありません。

text
    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' のままなので、失敗した実行にだけ撮られています。

text
    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 になりました。

ts
use: {
  video: {
    mode: 'retain-on-failure',
    size: { width: 640, height: 360 },
  },
},

指定しないときは、ビューポートを 800×800 に収まるように縮めた大きさになります(video のリファレンスによる)。ビューポートも指定していないときは 800×450 になる、とも書かれていて、最初の実行の動画はこの大きさでした。

スクリーンショットも、オブジェクトにして fullPage: true を付けると、見えている範囲だけでなく、スクロールした先までページ全体を撮ります。検証のページは縦に長いので、1280×720 だった画像が 1280×1239 になりました。

ts
use: {
  screenshot: { mode: 'only-on-failure', fullPage: true },
},
注意

スクリーンショットと動画には、テスト中に表示された画面がそのまま写ります。テストでパスワードや個人情報を表示しているなら、CI の成果物として保存したファイルを、だれが見られるかに気をつけてください。

​Posted by 86