Playwrightのカスタムレポーターでテスト結果を集計する方法

​​Playwright​CI,E2Eテスト,TypeScript

Playwright のカスタムレポーターを書くと、テストの結果を自分の欲しい形で集計できます。成功・失敗・flaky(再実行で通ったテスト)・スキップの件数や、ファイル別・タグ別の内訳、時間のかかったテストを、1つの JSON にまとめて書き出せます。CI のテスト結果をチャットに通知したり、テストの件数の移り変わりを記録したりするときの元データになります。

私は検証環境で、成功するもの、失敗するもの、再実行で通るもの、スキップするもの、test.fail() で失敗を想定したものを混ぜて実行し、レポーターに何が渡ってくるのかと、数え方で結果がどう変わるのかを確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0、TypeScript 5.9.3 です。テストはブラウザを開かない単純なものにして、レポーターの動きだけを見ました。シャーディングした結果を merge-reports でまとめる場合、HTML レポーターとの組み合わせ、Windows・macOS は試していません。

レポーターは、メソッドを持つクラスを1つ書くだけ

公式ドキュメントにあるカスタムレポーターの説明のとおり、レポーターは Reporter 型のメソッドをいくつか持つクラスです。どのメソッドも省略できます。クラスを export default して、設定の reporter にファイルのパスを書きます。配列の2つ目に書いたオブジェクトは、コンストラクターの引数として渡ります。

ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: 1,
  workers: 2,
  reporter: [['./summary-reporter.ts', { outputFile: 'summary.json' }]],
});

Reporter の API リファレンスによると、呼ばれる順番は次のとおりです。

  • onBegin:テストを見つけ終えたあと、始める前に1回
  • onTestBegin / onTestEnd:テストを1回動かすごとに
  • onEnd:すべてのテストが終わったあとに1回
  • onExit:テストランナーが終わる直前に1回

集計は、すべての結果がそろった onEnd でまとめて行うのが分かりやすいです。onBegin で受け取る suite(すべてのテストを含むいちばん上のスイート)を取っておけば、onEnd で suite.allTests() からすべてのテストをたどれます。

試したテスト

2つのファイルに、7つのテストを用意しました。設定では retries: 1 にして、失敗したテストを1回だけ再実行します。

ts
// tests/cart.spec.ts
import { test, expect } from '@playwright/test';

test('カートに商品を追加できる @smoke', async () => {
  await new Promise((r) => setTimeout(r, 300));
  expect(1 + 1).toBe(2);
});

test('合計金額を計算できる', async () => {
  await new Promise((r) => setTimeout(r, 120));
  expect(100 * 3).toBe(300);
});

test('送料の表示がずれる(再実行で通る) @smoke', async ({}, testInfo) => {
  // 1回目は失敗し、再実行(retry 1)では通る
  expect(testInfo.retry).toBe(1);
});
ts
// tests/login.spec.ts
import { test, expect } from '@playwright/test';

test('正しいパスワードでログインできる @smoke', async () => {
  await new Promise((r) => setTimeout(r, 500));
  expect('ok').toBe('ok');
});

test('パスワードを間違えるとエラーになる', async () => {
  expect('エラー').toBe('ようこそ');
});

test('SNS ログイン(未実装)', async () => {
  test.skip(true, 'まだ作っていない');
});

test('既知の不具合:長いメールアドレス', async () => {
  test.fail();
  expect('a'.repeat(300).length).toBeLessThan(255);
});

「送料の表示がずれる」は、1回目にわざと失敗させ、再実行で通るようにしました。最後のテストは test.fail() で「失敗するのが正しい」と宣言してあり、中身も実際に失敗します。

onTestEnd で result.status を数えると、件数がずれる

最初に、onTestEnd で受け取る result.status をそのまま数えるレポーターを試しました。

ts
// naive-reporter.ts
import type { Reporter, TestCase, TestResult } from '@playwright/test/reporter';

class NaiveReporter implements Reporter {
  private counts: Record<string, number> = {};
  onTestEnd(test: TestCase, result: TestResult) {
    this.counts[result.status] = (this.counts[result.status] ?? 0) + 1;
    console.log(`onTestEnd: ${test.title} status=${result.status} retry=${result.retry} outcome=${test.outcome()}`);
  }
  onEnd() {
    console.log('result.status で数えた結果', JSON.stringify(this.counts));
  }
}
export default NaiveReporter;

出力の順番を固定するため、ワーカーを1つにして実行しました。

text
$ npx playwright test --workers=1 --reporter=./naive-reporter.ts; echo "exit=$?"
onTestEnd: カートに商品を追加できる @smoke status=passed retry=0 outcome=expected
onTestEnd: 合計金額を計算できる status=passed retry=0 outcome=expected
onTestEnd: 送料の表示がずれる(再実行で通る) @smoke status=failed retry=0 outcome=unexpected
onTestEnd: 送料の表示がずれる(再実行で通る) @smoke status=passed retry=1 outcome=flaky
onTestEnd: 正しいパスワードでログインできる @smoke status=passed retry=0 outcome=expected
onTestEnd: パスワードを間違えるとエラーになる status=failed retry=0 outcome=unexpected
onTestEnd: パスワードを間違えるとエラーになる status=failed retry=1 outcome=unexpected
onTestEnd: SNS ログイン(未実装) status=skipped retry=0 outcome=skipped
onTestEnd: 既知の不具合:長いメールアドレス status=failed retry=0 outcome=expected
result.status で数えた結果 {"passed":4,"failed":4,"skipped":1}
exit=1

テストは7つなのに、onTestEnd は9回呼ばれました。再実行したテストは、1回目と2回目でそれぞれ呼ばれるためです。その結果、本当の失敗は1件なのに「failed が4件」と数えてしまいました。4件の内訳は、再実行で通ったテストの1回目、本当に失敗したテストの2回分、test.fail() で失敗が想定どおりのテストです。

ポイント

テストごとの最終的な結果は、result.status ではなく test.outcome() で見ます。値は expected(想定どおり)、unexpected(想定外の失敗)、flaky、skipped の4つです。

TestCase の API リファレンスにも、outcome() は TestResult.status と同じではなく、失敗が想定どおりのテストが失敗したら expected、再実行で通ったら flaky になると書かれています。上の出力でも、test.fail() のテストは status=failed でも outcome=expected でした。

onEnd で件数・ファイル別・タグ別・遅いテストをまとめる

outcome() を使って集計し、端末に要約を出しつつ JSON に書き出すレポーターです。

ts
// summary-reporter.ts
import { writeFileSync } from 'node:fs';
import { stripVTControlCharacters } from 'node:util';
import type {
  Reporter, FullConfig, Suite, TestCase, TestResult, FullResult,
} from '@playwright/test/reporter';

type Outcome = ReturnType<TestCase['outcome']>;

class SummaryReporter implements Reporter {
  private suite!: Suite;
  private attempts = 0;

  constructor(private options: { outputFile?: string; failOnFlaky?: boolean } = {}) {}

  onBegin(config: FullConfig, suite: Suite) {
    this.suite = suite;
    console.log(`集計を始めます:テスト ${suite.allTests().length} 件、workers ${config.workers}`);
  }

  onTestEnd(_test: TestCase, _result: TestResult) {
    // 再実行のたびに呼ばれる
    this.attempts++;
  }

  async onEnd(result: FullResult) {
    const tests = this.suite.allTests();
    const byOutcome: Record<Outcome, number> = { expected: 0, unexpected: 0, flaky: 0, skipped: 0 };
    const byFile: Record<string, Record<Outcome, number>> = {};
    const byTag: Record<string, number> = {};
    for (const t of tests) {
      const o = t.outcome();
      byOutcome[o]++;
      const file = t.location.file.split('/').pop()!;
      byFile[file] ??= { expected: 0, unexpected: 0, flaky: 0, skipped: 0 };
      byFile[file][o]++;
      for (const tag of t.tags) byTag[tag] = (byTag[tag] ?? 0) + 1;
    }
    const slowest = tests
      .map((t) => ({ title: t.title, ms: t.results.reduce((s, r) => s + r.duration, 0) }))
      .sort((a, b) => b.ms - a.ms)
      .slice(0, 3);
    const failed = tests
      .filter((t) => t.outcome() === 'unexpected')
      .map((t) => ({ title: t.title, error: stripVTControlCharacters(t.results.at(-1)?.error?.message ?? '').split('\n')[0] }));

    const summary = {
      status: result.status,
      durationMs: Math.round(result.duration),
      total: tests.length,
      attempts: this.attempts,
      byOutcome, byFile, byTag, slowest, failed,
    };

    console.log(`結果:${result.status}(${summary.durationMs} ms)`);
    console.log(`成功 ${byOutcome.expected} / 失敗 ${byOutcome.unexpected} / flaky ${byOutcome.flaky} / スキップ ${byOutcome.skipped}(実行回数 ${this.attempts})`);
    for (const s of slowest) console.log(`  遅い順:${s.title} ${Math.round(s.ms)} ms`);
    if (this.options.outputFile) writeFileSync(this.options.outputFile, JSON.stringify(summary, null, 2));

    // flaky を失敗として扱う(終了コードが 1 になる)
    if (this.options.failOnFlaky && byOutcome.flaky > 0 && result.status === 'passed') {
      console.log('flaky なテストがあるため、失敗として終えます');
      return { status: 'failed' as const };
    }
  }
}

export default SummaryReporter;

ポイントは4つです。

  • テストの時間は、test.results(実行1回ごとの結果の配列)の duration を足しています。再実行したテストは、2回分の合計になります。
  • タグは test.tags から取っています。TestCase の API リファレンスのとおり、test() の tag オプションで付けたものに加えて、タイトルの中の @smoke のような語もタグとして入ります。
  • 失敗の理由は、最後の実行の error.message の1行目だけを残しています。
  • onEnd は async にしてあります。最後の節で、終了コードを変えるときに必要になります。

設定の reporter にこのレポーターだけを書いて実行した結果です。

text
$ npx playwright test; echo "exit=$?"
集計を始めます:テスト 7 件、workers 2
結果:failed(2186 ms)
成功 4 / 失敗 1 / flaky 1 / スキップ 1(実行回数 9)
  遅い順:正しいパスワードでログインできる @smoke 509 ms
  遅い順:カートに商品を追加できる @smoke 310 ms
  遅い順:合計金額を計算できる 126 ms
exit=1

今度は、失敗が1件、flaky が1件と、テストの数どおりに数えられました。test.fail() のテストは「成功」の4件に入っています。書き出された summary.json は次のとおりです(一部を省略し、改行を詰めています)。

json
{
  "status": "failed",
  "durationMs": 2186,
  "total": 7,
  "attempts": 9,
  "byOutcome": { "expected": 4, "unexpected": 1, "flaky": 1, "skipped": 1 },
  "byFile": {
    "cart.spec.ts": { "expected": 2, "unexpected": 0, "flaky": 1, "skipped": 0 },
    "login.spec.ts": { "expected": 2, "unexpected": 1, "flaky": 0, "skipped": 1 }
  },
  "byTag": { "@smoke": 3 },
  "slowest": [
    { "title": "正しいパスワードでログインできる @smoke", "ms": 509 },
    ...
  ],
  "failed": [
    {
      "title": "パスワードを間違えるとエラーになる",
      "error": "Error: expect(received).toBe(expected) // Object.is equality"
    }
  ]
}

エラーの文には、端末の色の制御文字が入っている

失敗の理由をそのまま JSON に入れると、読めない文字が混ざります。stripVTControlCharacters を外した版で試したところ、error.message は次のようになっていました。

text
"Error: \u001b[2mexpect(\u001b[22m\u001b[31mreceived\u001b[39m\u001b[2m).\u001b[22mtoBe\u001b[2m(\u001b[22m\u001b[32mexpected\u001b[39m\u001b[2m) // Object.is equality\u001b[22m"

\u001b[31m などは、端末で文字に色を付けるための制御文字です。検証では、出力を /dev/null に捨てて端末につながっていない状態で実行しても、この文字が入っていました。チャットへの通知や JSON に使うなら、Node.js の util.stripVTControlCharacters() で取り除いておきます。上のレポーターでは、取り除いたあとの文が summary.json に入っています。

端末に何も出さないレポーターは、printsToStdio で false を返す

結果をファイルに書くだけで、端末には何も出さないレポーターもあります。Reporter の API リファレンスでは、そういうレポーターは printsToStdio() で false を返すよう勧めています。そうすると、Playwright が標準の端末向けのレポーターを足して、進み具合を表示します。

ts
// quiet-reporter.ts
import { writeFileSync } from 'node:fs';
import type { Reporter, Suite, FullResult } from '@playwright/test/reporter';

class QuietReporter implements Reporter {
  private suite!: Suite;
  printsToStdio() {
    return false;
  }
  onBegin(_config: unknown, suite: Suite) {
    this.suite = suite;
  }
  async onEnd(result: FullResult) {
    const counts: Record<string, number> = {};
    for (const t of this.suite.allTests()) counts[t.outcome()] = (counts[t.outcome()] ?? 0) + 1;
    writeFileSync('quiet.json', JSON.stringify({ status: result.status, ...counts }));
  }
}
export default QuietReporter;

環境変数 CI を設定せずに、このレポーターだけを指定して実行すると、端末には line レポーターと同じ形の表示が出ました(途中を省略し、区切りの線を短くしています)。

text
$ npx playwright test --reporter=./quiet-reporter.ts; echo "exit=$?"

Running 7 tests using 2 workers

[1/7] tests/login.spec.ts:3:1 › 正しいパスワードでログインできる @smoke
[2/7] tests/cart.spec.ts:3:1 › カートに商品を追加できる @smoke
...
  1 failed
    tests/login.spec.ts:8:1 › パスワードを間違えるとエラーになる ────────────
  1 flaky
    tests/cart.spec.ts:13:1 › 送料の表示がずれる(再実行で通る) @smoke ─────
  1 skipped
  4 passed (2.2s)
exit=1
$ cat quiet.json
{"status":"failed","expected":4,"flaky":1,"unexpected":1,"skipped":1}

同じ実行に CI=1 を付けると、足される表示は ···××±F°· のような dot レポーターの形に変わりました。

好きな表示と組み合わせたいときは、--reporter=dot,./quiet-reporter.ts のようにカンマで並べます。この場合は、指定した dot の表示だけが出て、quiet.json も同じ内容で書き出されました。

集計の結果で、終了コードを変える

Reporter の API リファレンスによると、onEnd から { status: 'failed' } のようなオブジェクトを返すと、実行全体の結果と終了コードを変えられます。集計した数を見て「この条件なら CI を失敗にする」と、自分で決められます。

上のレポーターの failOnFlaky は、この仕組みを試すための例です。flaky があれば失敗にしたいだけなら、Playwright には、TestConfig のリファレンスにある標準の設定 failOnFlakyTests(コマンドラインでは --fail-on-flaky-tests)があります。こちらは「Playwrightのretriesで不安定なテストを見つける方法」で試しています。

失敗するテストを --grep-invert で除き、flaky が1件だけ残る状態で、failOnFlaky なしとありで比べました(遅い順の3行は省略しています)。

text
$ npx playwright test --grep-invert "間違える"; echo "exit=$?"
集計を始めます:テスト 6 件、workers 2
結果:passed(1587 ms)
成功 4 / 失敗 0 / flaky 1 / スキップ 1(実行回数 7)
...
exit=0

設定を reporter: [['./summary-reporter.ts', { outputFile: 'summary.json', failOnFlaky: true }]] に変えると、次のようになりました。

text
$ npx playwright test --grep-invert "間違える"; echo "exit=$?"
集計を始めます:テスト 6 件、workers 2
結果:passed(1513 ms)
成功 4 / 失敗 0 / flaky 1 / スキップ 1(実行回数 7)
...
flaky なテストがあるため、失敗として終えます
exit=1

onEnd の中で受け取る result.status は passed のままですが、返した値によって終了コードが1になりました。

onEnd で値を返すときは、onEnd を async にします。検証環境の TypeScript 5.9.3 では、async を付けずに { status: 'failed' } を返すと、Reporter 型の onEnd の戻り値と合わないという型エラー(TS2416)になりました。

注意

Reporter の API リファレンスによると、レポーターのメソッドの中で投げられた例外は、Playwright が握りつぶします。集計や書き出しの失敗に気づきたいときは、自分で try / catch して扱う必要があります。

​Posted by 86