> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# レポーター

> カスタムレポーターで実行イベントを受け取り、結果を公開します。

レポーターは実行イベントを発生時に受け取り、レポートの書き込み後に完了した実行を受け取ります。`e2e.config.ts` の `reporters` には、組み込みレポーターの ID とレポーターオブジェクトを並べて指定します。

```ts title="e2e.config.ts"

export default {
  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
  reporters: ['list', 'junit', github()],
} satisfies E2EConfig;
```

## リファレンス

### 組み込みレポーター

| レポーター | 説明 |
| --- | --- |
| [`list`](#list) | ターミナルの進捗と実行サマリー |
| [`json`](#json) | レポートを stdout に出力 |
| [`junit`](#junit) | `<output>/junit.xml` に書き込み |
| [`markdown`](#markdown) | `<output>/summary.md` に書き込み |
| [`github()`](#github) | プルリクエストのコメントとジョブサマリー |
| [`htmlReporter()`](#htmlreporter) | `<output>/report.html` に書き込み |

| 投げるエラー | 発生条件 |
| --- | --- |
| `INVALID_CONFIG` | `reporters` が配列でない場合。 |
| `INVALID_CONFIG` | `list`、`json`、`junit`、`markdown` 以外の ID を指定した場合。 |
| `INVALID_CONFIG` | エントリが ID でも、`name` と 1 つ以上のハンドラーを持つオブジェクトでもない場合。 |
| `INVALID_CONFIG` | `json` と `list` を併用した場合。 |

#### `list`

ターミナルに進捗、失敗、実行サマリーを表示します。

```ts
reporters: ['list'], // default
```

- [`onEvent`](#onevent) が受け取るものと同じイベントを表示します。
- TTY では実行中のテストをリアルタイムに表示します。stdout がターミナルでない場合（パイプ、リダイレクト、多くの CI）は、各テストの完了時に表示します。
- レポーターが返す[サマリー行](#onrunfinished)を、自身のサマリーの下に表示します。
- 出力の最後には、失敗したテストごとに `Failed` 行を表示します。ファイルと行、エラーの最初の行、作成済みならトレースページを示すため、`e2e run | tail` でも何が失敗したかを確認できます。

#### `json`

レポートドキュメントを stdout に出力します。

```ts
reporters: ['json'],
```

#### `junit`

レポートと同じディレクトリに `junit.xml` を書き込みます。

```ts
reporters: ['list', 'junit'],
```

- `run.report` を読み、`run.reportPath` と同じディレクトリに `junit.xml` を書き込み、そのファイルを示す 1 行を返します。レポーターの最小限の完全な実装例です。
- 失敗、タイムアウト、リトライ後にのみ成功、または [`test.fail`](https://e2e.com/docs/ja/reference/test#fail) の期待どおりに失敗したテストで、失敗時のスクリーンショットを記録している場合、`<testcase>` 内に `<system-out>[[ATTACHMENT|<path>]]</system-out>` としてリンクします。GitLab CI はこれをパイプラインのテストレポートに表示します。パスは `$CI_PROJECT_DIR`、未設定ならプロジェクトルートからの相対パスです。その外にあるスクリーンショットにはリンクしません。
- 2 回目の Ctrl-C でもファイルを書き込むため、新しいレポートの隣に前回のファイルが残ることはありません。

#### `markdown`

レポートと同じディレクトリに `summary.md` を書き込みます。

```ts
reporters: ['list', 'markdown'],
```

2 回目の Ctrl-C を含め、`junit` と同じように動きます。出力ファイルは `summary.md` で、[`renderMarkdownReport`](#rendermarkdownreport) を使います。

<a id="rendermarkdownreport" />

##### `renderMarkdownReport`

レポートを、`markdown` レポーターと同じ Markdown ページに変換します。独自のレポーターから、同じページを別の場所に投稿できます。

```ts

const reporter: Reporter = {
  name: 'wiki',
  async onRunFinished(run) {
    const page = renderMarkdownReport(run.report, { traces: run.traces });
    await fetch('https://wiki.example.test/runs', { method: 'POST', body: page });
  },
};
```

- `traces` は結果 ID に基づき、各ブロックをトレースページにリンクします。
- GitHub Actions 向けにこの処理を行うレポーターが [`@e2e-dev/github`](https://e2e.com/docs/ja/github) です。

#### `github()`

`@e2e-dev/github` は GitHub Actions から実行結果を 1 つのプルリクエストコメントとして投稿し、再実行時に更新します。同じテキストをジョブサマリーにも書き込みます。

```ts

const reporter = github({ key: 'chromium' });
```

- `key` は、マトリックスなどでワークフロー、ジョブ、プロジェクトが同じ場合に、各ジョブのコメントを区別します。指定しなければ、同じジョブのマトリックス実行はコメントを共有し、最後に完了した結果が残ります。再実行時に古いコメントを見つける必要があるため、実行 ID は使わないでください。キーは `e2e chromium: 77 passed` のように、コメントの見出しにも使います。
- トークン、イベント、リポジトリを読み取るのは実行終了時です。設定の読み込み時には読みません。
- `--last-failed` では、再実行を [`lastRun`](#onrunfinished) に統合して、両方の実行を 1 つのコメントに表示します。
- 設定と権限については[プルリクエストのコメント](https://e2e.com/docs/ja/github)を参照してください。

#### `htmlReporter()`

`@e2e-dev/html-reporter` は、ブラウザで開ける 1 枚のページに実行結果を書き込みます。ファイルごとのテスト一覧、状態のタブ、検索ボックスに加え、各テストの試行、エラー、ステップ、スクリーンショット、動画を表示します。

```ts

const reporter = htmlReporter({ media: 'embed' });
```

- レポートと同じディレクトリに `report.html` を書き込み、レポートドキュメントを埋め込みます。サーバーなしでディスクから開けます。
- `media` は、スクリーンショット、動画、ダウンロードの扱いを決めます。

  | `media` | ページの内容 | 共有方法 |
  |---|---|---|
  | `'link'`（デフォルト） | `<output>/results/` から相対パスでリンクします | 出力ディレクトリ全体を 1 つの CI 成果物としてまとめます |
  | `'embed'` | メディアを含む、1 ファイルで完結するレポートです | ファイルを送ります。デバイスの動画は 1 分あたり数十 MB になります |
  | `'none'` | メディアを除き、テキストだけを表示します | ファイルを送ります |

  ダウンロードリンクはファイルを開かず、保存します。PDF や zip など、ランナーがシークレットを検査できなかったダウンロードは、埋め込みページに含めません。ホスト型ブラウザやデバイスのサービスが保存する動画は、リンクのままにします。
- `outputFile` を指定すると、プロジェクトルートからのパスで別の場所にページを保存できます。
- ページに表示するのは、そのページを作成した実行だけです。`--last-failed` の後は、引き継いだ失敗を除く再実行のテストを表示します。`e2e explore` では探索を表示しますが、発見事項は含めません。
- テストは、各ファイル、その describe ブロック、テストの順でツリー表示し、失敗を先に並べます。ファイルのパスを選択すると、テストを折りたたみます。
- 各ステップには、試行の動画内での開始時刻を表示します。時刻を選択するとそこから再生し、動画で再生中のステップを強調表示し続けます。動画のタイムラインには各ステップの開始位置を示します。速度ボタンは 0.25 倍から 4 倍まで切り替えられ、5 秒未満の録画は低速で再生を始めます。スマートフォンの録画はステップの上ではなく横に表示します。
- 期待値と実際の値を報告するアサーション失敗（ロケーターのアサーションなど）では、異なる文字を強調表示します。テストファイルがプロジェクト内にあれば、失敗した呼び出しの周辺コードを表示し、各ステップから実行したコードを開けます。このためページには各ステップの周辺の数行を保存し、共有したレポートにも表示します。
- 失敗した試行のエラーにある **copy prompt** は、コーディングエージェント向けに失敗内容をコピーします。エラー、ステップ、失敗したステップの操作、存在するトレースページ、画面ツリー、スクリーンショット、動画のプロジェクトルートからのパスを含めます。
- エージェントステップには、説明、実行した操作、モデル、トークン数とコスト、キャッシュからリプレイしたかどうか、最後のターンを表示します。
- ページはシステムのライト・ダークテーマに従います。上部の太陽と月でどちらかに固定でき、ブラウザはその選択を、以後開くすべてのレポートに適用します。

### カスタムレポーター

レポーターオブジェクトには `name` と 1 つ以上のハンドラーが必要です。リアルタイムの進捗には `onEvent`、最終レポートと成果物の処理には `onRunFinished` を使います。

```ts title="e2e.config.ts"

const upload: Reporter = {
  name: 'upload',
  async onRunFinished(run) {
    const response = await fetch('https://example.test/runs', {
      method: 'POST',
      body: JSON.stringify(run.report),
    });
    const { url } = (await response.json()) as { url: string };
    return [{ label: 'Results', text: url }];
  },
};

export default {
  targets: [{ engine: web(), app: { url: 'localhost:3000' } }],
  reporters: ['list', upload],
} satisfies E2EConfig;
```

| メンバー | 型 |
| --- | --- |
| [`name`](#name) | `string` |
| [`onEvent`](#onevent) | `(event: RunEvent) => void` |
| [`onRunFinished`](#onrunfinished) | `(run, signal) => Promise<…>` |

```ts
interface Reporter {
  readonly name: string;
  onEvent?(event: RunEvent): void;
  onRunFinished?(run: FinishedRun, signal: AbortSignal): Promise<ReporterSummary | void>;
}
```

キャッシュしたステップは、記録に含まれていれば、`report.json` とトレースページで `cache.recordedBy: { provider, model }` を公開します。古い記録では省略します。コンソールに `replayed · recorded with provider/model` を表示するのは、その識別情報が設定したモデルと異なる場合だけです。複数エージェントの実行や、実行ヘッダーにモデルが載らない固定エージェントでは表示しません。

#### `name`

診断に使うレポーターのラベルです。必須で、空にはできません。

```ts
name: 'upload',
```

#### `onEvent`

各実行イベントを、発生時に通常の JSON として受け取ります。

```ts
onEvent(event) {
  switch (event.type) {
    case 'test-finished':
      console.log(event.result.test.title, event.result.status);
      break;
    default:
  }
},
```

一覧は[イベント](#events)を参照してください。

<Note>
`onEvent` でブロックや例外の送出をしないでください。時間のかかる処理は `onRunFinished` で行います。例外を投げると、そのレポーターはその実行が終わるまで無効になり、レポーター名、イベントの種類、エラーを stderr に 1 行表示します。実行結果は変わりません。
</Note>

#### `onRunFinished`

レポートを書き込み、ターミナルのサマリーを表示した後に、完了した実行と `AbortSignal` を渡して呼び出します。

```ts
async onRunFinished(run, signal) {
  await fetch('https://example.test/runs', { method: 'POST', body: JSON.stringify(run.report), signal });
  return [{ label: 'Results', text: 'https://example.test/runs/0192c' }];
},
```

```ts
interface FinishedRun {
  readonly report: Report;                 // the report-1 document, as written
  readonly status: RunStatus;              // report.run.status
  readonly exitCode: RunExitCode;
  readonly projectRoot: string;            // what the terminal shows paths relative to
  readonly reportPath: string | undefined; // absent when the write failed
  readonly artifactsRoot: string;          // what the report's artifact paths are relative to
  readonly aiTracePath: string | undefined;
  readonly traces: ReadonlyMap<string, string>;      // result id -> its trace page, from the project root
  readonly lastRun?: Report;               // with --last-failed, the report the rerun selected from
  redact(text: string): string;            // masks the config's fixed secret values (not provider-resolved ones) in text from outside the report
}

type ReporterSummary = readonly { label: string; text: string }[];
```

- すべてのレポーターを並行して実行し、それぞれに 1 分の期限を設けます。
- タイムアウト、例外、不正な戻り値は stderr に報告します。実行の状態、終了コード、レポートは変わりません。
- Ctrl-C が 1 回ならレポーターの完了を待ちます。2 回目の Ctrl-C で待機をやめますが、[`junit`](#junit) と [`markdown`](#markdown) は例外です。
- 予算を使い切るか、実行を強制停止すると `signal` が中止状態になります。
- ランナーは `onRunFinished` を呼ぶ前に、トレースページ `results/<test>/trace.md` を書き込みます。

<Note>
すべてのリクエストとタイマーに `signal` を渡してください。CLI は待機をやめたレポーターを待たずに終了し、残りの処理も打ち切ります。[`e2e/runner`](https://e2e.com/docs/ja/reference/runner) では、その処理が残るとプロセスも動き続けます。
</Note>

##### サマリー行

レポーターが resolve 時に返す行は、`list` のサマリーの下に同じレイアウトで表示します。`json` レポーターには含めません。

```
   Test Files  2 passed (2)
        Tests  6 passed (6)
     Start at  14:02:11
     Duration  8.41s

        JUnit  .e2e/junit.xml
      Results  https://example.test/runs/0192c…
```

##### 成果物

- レポート内の成果物パスは、`artifactsRoot` 相対の POSIX パスです。
- `path`、`size`、`sha256` は省略可能です。ファイルが生成されなかった成果物や、秘匿処理によって非公開になった成果物は、これらを付けずに記録します。読み取る前に `path` を確認してください。
- ホスト型サービスが保存する動画は、`path` の代わりに `http(s)` の `url` を持ちます。

##### `--last-failed` での再実行

- 再実行自身のレポートでは、実行しなかったテストを未選択として記録します。`@e2e-dev/github` がプルリクエストのコメントを更新するように、同じ場所を最新に保つレポーターは、再実行を `lastRun` に統合して両方の実行をまとめて表示します。
- 再実行すべきだったのに別のフィルターで除外されたテストは、再実行の `run.carried` に入ります。そのテストの最後の結果、試行を保持する直列グループ、そのテストをスコープに含む `beforeAll` または `afterAll` の失敗を、それらを報告した過去の実行から引き継ぎます。
- 統合後は、未選択の結果の代わりに引き継いだ結果を表示し、引き継いだ失敗やフックエラーも実行結果に反映します。
- 両方のレポートが参照する成果物は、ディスク上の `artifactsRoot` にあります。

<a id="test-filters" />
##### テストフィルター

- [テストフィルター](https://e2e.com/docs/ja/filters)が除外したテストは未選択の結果になり、`skip.cause` が `filtered`、`skip.filter` がフィルター名になります。
- `run.filters` は呼び出したフィルターごとに 1 件の記録を、呼び出し順で保持します。内容は `name`、`candidates`、`excluded`（直列グループがメンバーを戻した後の除外テスト数）、`note`（1024 文字で切り詰め。失敗またはタイムアウトしたフィルターでは理由を示す警告）、`outcome` です。この値はフィルターが何も除外しなかった場合に設定し、例外や不正な結果なら `failed`、5 分を超えた場合は `timed-out` です。対象テストが残っていないフィルターは呼ばず、記録も作りません。
- フィルターの判断後、`run.changes` は判断した変更を集計値で保持します。`base`（マージベース）、`files`、`skipped`（`no files changed since abc1234` など、どのフィルターも実行しなかった理由）です。フィルターを設定して `--changed-since` を渡した実行に存在します。ただし `e2e explore`、`--watch` の再実行、判断前に終了した実行は除きます。`--last-failed`、または判断するテストがない場合は、`skipped` だけを保持します。
- 存在しないコミットを指定した参照による `INVALID_CHANGED_SINCE` など、フィルターの判断中の失敗は、`phase` が `filter` のエラーとして `run.errors` に入ります。不正な形式の `changedSince` では `phase` は `config` です。

## イベント

`onEvent` は、次のいずれかのイベントを受け取ります。各イベントには連番 `seq` と ISO 形式のタイムスタンプ `at` もあります。

```ts
type RunEventFact =
  | { type: 'run-started'; runId; projectId; projectRoot; artifactsRoot; ci; targets; agents?; model?; judge? }
  | { type: 'plan'; total; files: { file; target; tests }[] }
  | { type: 'notice'; target; message }
  | { type: 'output'; target; pair; stream: 'stdout' | 'stderr'; text }
  | { type: 'setup'; step: SetupStep; state: 'started' }
  | { type: 'setup'; step: SetupStep; state: 'finished'; durationMs; outcome?: 'reused' | 'failed' | 'timed-out' }
  | { type: 'test-started'; testId; agent; repeat; title; file; serialId; target }
  | { type: 'step'; testId; agent; repeat; target; progress: StepProgress }
  | { type: 'test-finished'; result: RunEventResult }
  | { type: 'serial-group'; group: SerialGroupRecord }
  | { type: 'explore'; progress: ExploreProgress }
  | { type: 'run-error'; error: SerializedError }
  | { type: 'run-interrupted'; mode: 'graceful' | 'forced' }
  | { type: 'run-stopped'; failures; limit }
  | { type: 'run-finished'; status; exitCode; reportPath?; aiTracePath?; traces? };
```

- 最初が `run-started`、最後が `run-finished` です。
- `run-started` の `targets` は、`--target` で選んだターゲットを設定順で列挙します。指定がない場合、または `--target` に未知のターゲットを指定した場合は、設定済みのすべてのターゲットを列挙します。未知のターゲットの場合、実行は `UNKNOWN_TARGET` で失敗します。レポートの `run.targets` は、いずれの場合も設定済みの全ターゲットを列挙します。
- `run-started` の `judge` は、実行エージェントのジャッジモデルです。判定に `model` 以外のモデルを使う場合だけ存在します。
- `setup` はテスト開始前の処理の開始と終了を示します。`step.kind` は `collect`、`filter`（`name` で示す 1 つの[テストフィルター](https://e2e.com/docs/ja/filters)）、`prepare`、`service`、`app` のいずれかです。`app` ステップの `url` は、準備完了チェックがポーリングする URL で、空きポートを反映し、ユーザー情報とクエリを除いています。`outcome` は、サービスやアプリのコマンドが、その URL ですでに稼働するプロセスを再利用した場合に `reused`、フィルターが例外を投げるか不正な結果を返した場合に `failed`、5 分を超えた場合に `timed-out` になります。
- `notice` は、その行が何についての通知かを `target` に示します。値はターゲット名、`app`、`collect`、テストフィルターの進捗やサマリーを示す `filter`、または `run` です。
- `output` はテストによる stdout または stderr への 1 回の書き込みです。`pair` はその時点で実行中のテストを示し、テストの合間では undefined です。
- `test-finished` は、すべての試行の成果物を含む完全な結果記録を持ちます。
- `explore` は `e2e explore` の実行時だけ発生します。`started`、`planning`、`step-started`、`step-finished`、`finding`、`finished` があります。すべての記録はレポートの `run.explore` にあります。
- イベントの種類は今後追加されます。既知の種類を処理し、それ以外は無視してください。`switch` の `default` 分岐は空にします。

### テストと試行

- 複数のエージェントに固定したテストは、エージェントごとに 1 回開始・終了します。実行状態のキーには、テスト ID、ターゲット、エージェントを組み合わせてください。
- 通常のテストは、その組み合わせごとに `test-started` を 1 回発行します。直列グループのメンバーは、実際に実行されるグループの試行ごとに発行します。
- リトライの区別には、ステップ進捗の[識別情報](#step-progress)を使ってください。
- ステップの開始前に失敗した試行は、ステップ進捗を発行せず、最終結果に現れます。

<Note>
シークレットはイベントを作成する前に秘匿します。エラーメッセージとスキップ理由から取り除くのは、ANSI エスケープと、タブ、改行、`\r\n` の `\r` 以外の制御文字だけです。そのため、信頼できない内容として扱ってください。
</Note>

### ステップ進捗

`phase` フィールドはステップの進捗を示します。

- `start` と `end` はステップの開始と終了です。
- `event` は、モデルのターン、ツール呼び出し、観測の完了を報告します。
- `activity` は、`observe`、`action`、`model` の処理開始を報告します。
- `replay` は、キャッシュからのリプレイ開始、またはエージェントへの制御の返却を報告します。

```ts
type StepProgress = (
  | { phase: 'start'; kind: StepKind; api: string; label: string }
  | {
      phase: 'end';
      kind: StepKind;
      api: string;
      label: string;
      status: 'passed' | 'failed' | 'blocked' | 'timed-out' | 'cancelled';
      durationMs: number;
      modelCalls: number;
      error?: SerializedError;
      explanation?: string;
    }
  | { phase: 'event'; api: string; event: StepEvent }
  | { phase: 'activity'; api: string; activity: 'observe' | 'model' | 'action' }
  | { phase: 'replay'; api: string; active: boolean }
) & { identity?: StepProgressIdentity };
```

`end` フェーズの `error` と `explanation` は秘匿済みです。`blocked` や `cancelled` を含め、`status` をそのまま扱ってください。成功以外のすべてのステップを、プロダクトの不具合と見なさないでください。

ランナーが発行するすべてのステップフェーズには、`progress.identity` を含めます。

```ts
{ attemptId: string; attemptIndex: number; stepId: string; stepIndex: number }
```

- ID は最終レポートと一致します。2 つのインデックスはどちらも 0 始まりです。
- リトライには新しい試行 ID と、より大きい試行インデックスを割り当てます。ステップのインデックスは再び 0 から始まります。
- 直列グループのメンバーは、グループの試行 ID とインデックスを共有します。各メンバーのステップ ID は区別されます。
- ネストしたステップも含め、start、activity、event、replay、end フェーズを対応づけるには `stepId` を使います。
- 古いイベントストリームもレポーターが受け取れるように、型上の `identity` は省略可能です。

## `--reporter` とレポーターオブジェクトの関係

`--reporter` が置き換えるのは組み込みレポーターだけです。設定済みのレポーターオブジェクトは引き続き実行します。

<CodeGroup>
```bash npm
npx e2e run --reporter list,junit
```

```bash pnpm
pnpm exec e2e run --reporter list,junit
```

```bash bun
bunx e2e run --reporter list,junit
```
</CodeGroup>

- レポーターオブジェクトだけを指定した設定では、組み込みのターミナル出力はありません。実行エラーは引き続き stderr に、各行 `CODE: message` の形式で表示します。

## レポーターの実行場所

ハンドラーはランナーのプロセスで実行します。ワーカーも設定を読み込むため、レポーターの作成時に副作用を起こさないでください。

- トークンの読み取りやリクエストの開始は、ハンドラー内で行ってください。
- レポーターを追加しても、[キャッシュしたトレース](https://e2e.com/docs/ja/cache#what-must-match)は有効なままです。

## 型

`Reporter`、`FinishedRun`、`ReporterSummary`、`Report`、`RunEvent`、`RunEventOf` はメインエントリポイントからエクスポートします。`renderMarkdownReport(report, options)` も同様です。

## 関連情報

`@e2e-dev/github` の設定は[プルリクエストのコメント](https://e2e.com/docs/ja/github)を参照してください。組み込みレポーターが書き込む内容は [CLI リファレンス](https://e2e.com/docs/ja/reference/cli#output)に一覧があります。
