> ## 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.

# 実行をデバッグする

> トレースページと証拠を確認し、ブラウザの動作やモデルに送られた情報を調べます。

テストが失敗すると、エラーと[トレースページ](#traces)のパスを表示します。実行全体のサマリーが必要なら `markdown` レポーターを追加してください。`.e2e/summary.md` に書き出します。

## 失敗を読み解く

`list` レポーターの `Failed Tests` セクションには、エラー、失敗した行、ロケーターが失敗した場合の近い候補、アプリのログ、トレースページが表示されます。アプリの最初の 3 件のエラー（コンソールエラー、未捕捉の例外、失敗したリクエスト、5xx 応答）も、トレースページと同じように機密情報をマスキングして引用します。`.e2e/summary.md` にも表示されます。

```text
 FAIL  |web| tests/todos.e2e.ts > shows the remaining count
LOCATOR_NOT_FOUND: locator did not become visible: getByRole("heading", name: "Todos")
 ❯ tests/todos.e2e.ts:31:3
 ❯ at http://127.0.0.1:4271/nope
 ❯ app 2 errors, 2 warnings logged
   × console error: Error occurred prerendering page "/todos"
   × network error: GET /api/todos 500 Internal Server Error
 ❯ trace .e2e/results/todos-shows-the-remaining-count-796fac5f12ab34cd/trace.md
```

終了コードは失敗の種類を示します。

| 終了コード | 意味 | ジョブを再試行するか |
| ---: | --- | --- |
| 1 | テストの失敗 | テストが不安定な場合のみ |
| 2 | 設定、収集、ポリシーの問題 | 先に報告された問題を修正 |
| 3 | エンジン、アプリプロセス、モデルプロバイダー、アーティファクト、クリーンアップのインフラ障害 | 一時的な原因の場合 |
| 4 | ランナー内部のエラー | 問題を報告 |
| 130 | 実行の中断 | |

## トレース

デフォルトでは、失敗、タイムアウト、中断、flaky となった各テストの[結果ディレクトリ](#artifacts)に、トレースページ `trace.md` を作成します。リンクを使えるよう、エディターの Markdown プレビューで開いてください。実行したブラウザまたはデバイスの情報に続き、次が表示されます。

- **ステップ。** 操作が届いたノード、待機中にアサーションが読み取った値、リプレイキャッシュの判断、アプリのログ、ページの移動先、前のステップからの画面の変化。
- **アプリのログ。** コンソール出力、未捕捉の例外、失敗したリクエスト、4xx と 5xx 応答を、それぞれ対応するステップ付きで最大 50 行表示します。エラーと警告を優先します。試行が保持するのは、エラーと警告を最大 200 件、その他を最大 100 行です。
- **エージェントの直近のターン。**
- **失敗時の画面。** 最大 5 秒以内に取得したスクリーンショットとセマンティックツリーです。時間内にアプリが応答しなければ、画面のセクションはありません。

<Accordion title="トレースページの例">

````markdown
# ✗ todos › shows the remaining count

`tests/todos.e2e.ts` · failed · 2.2s

**ASSERTION_FAILED**

```text
expect.toHaveText failed
locator: getByRole("status", name: "Remaining")
expected: text "1 remaining"
observed: text "0 remaining" (match count 1)
```

Ran on: browser `chromium 141.0.7390.37` · user agent `Mozilla/5.0 (Macintosh; …) HeadlessChrome/141.0.7390.37 Safari/537.36`

Look at: `tests/todos.e2e.ts:15`

## Steps

1. ✓ `app.open` `/todos` (37ms in beforeEach) — `tests/todos.e2e.ts:4`
2. ✓ `agent.act` "Add a todo named Milk." (429ms, 2 model calls) — `tests/todos.e2e.ts:12`
   - cache: no replay: nothing recorded for this step yet; recording saved (`.e2e/cache/1227d5a6….json`)
   - type "Milk" into textbox "New todo" (17ms)
   - press "Enter" on the focused field (5ms)
   - ✗ network error: `POST /api/todos 500 Internal Server Error`
   - screen: 6 changes since step 1 at `/todos`, 38 nodes
     - `added listitem "Milk Delete Milk" testid="todo"`
     - `added checkbox "Milk"`
     - `changed status "Remaining" text="1 remaining" (was: status "Remaining" text="0 remaining")`
     - 3 more
3. ✓ `locator.check` `getByLabel("Milk")` (13ms) — `tests/todos.e2e.ts:14`
   - check checkbox "Milk" (13ms)
   - screen: 3 changes since step 2 at `/todos`, 38 nodes
     - `added checkbox "Milk" [checked]`
     - `changed status "Remaining" text="0 remaining" (was: status "Remaining" text="1 remaining")`
     - `removed checkbox "Milk"`
4. ✗ `expect.toHaveText` `getByRole("status", name: "Remaining")` (1.6s) — **ASSERTION_FAILED** — `tests/todos.e2e.ts:15`
   - expect gave up after 16 reads in 1.6s: text "0 remaining" (1 match) x16

## App log

What the app logged, oldest first, with the step it happened in.

- step 2 · ✗ network error: `POST /api/todos 500 Internal Server Error`

## Screen at failure
`http://127.0.0.1:4271/todos` · viewport 1280x720 · 38 nodes

![screenshot at failure](attempt-1/screenshots/001-failure.png)

```text
#n29 textbox "New todo"
#n30 button "Add"
 #n35 listitem "Milk Delete Milk" testid="todo"
  #n36 checkbox "Milk" [checked]
#n40 status "Remaining" text="0 remaining"
```
````

</Accordion>

ずっと同じ値を読んでいたアサーションは、期待値が間違っているか、アプリがその状態に到達していません。アプリのログで失敗したリクエストを探してください。読み取り値が変化したアサーション（`"2 remaining" x3 -> at 410ms "1
remaining"`）は、アプリの更新とタイミングが競合しています。操作後の `screen: unchanged` は、目に見える効果がなかったことを意味します。Web のステップに表示する画面は操作後の画面、デバイスでは操作対象となった画面です。

[`trace`](https://e2e.com/docs/ja/reference/config#trace) モードで、どのテストのページを保持するか設定します。`--trace` は成功したものを含むすべてのテストで保持し、`--trace off` は何も書きません。テスト自身の `trace` オプションは、どちらよりも優先されます。

## アーティファクト

各テストは `.e2e/results/`（または [`<output>`](https://e2e.com/docs/ja/reference/config#output)`/results/`）にひとつのディレクトリを持ちます。トレースページと、試行ごとの `attempt-<n>` が入ります。直列実行グループのテストは、ひとつのディレクトリを共有します。

```text
.e2e/results/todos-adds-a-todo-1a2b3c4d5e6f7a8b/trace.md
.e2e/results/todos-adds-a-todo-1a2b3c4d5e6f7a8b/attempt-1/screen-at-failure.txt
.e2e/results/todos-adds-a-todo-1a2b3c4d5e6f7a8b/attempt-1/screenshots/001-failure.png
```

テストの実行まで進む実行は、最初に `results/` を空にします。`--last-failed` による再実行では、再実行元のレポートが参照するファイルを保持し、新しい試行を各テストの `rerun-<n>/` に書きます。

| アーティファクト | 保存されるタイミング |
| --- | --- |
| スクリーンショット | エンジンが対応していれば、失敗した試行で撮影します。組み込みの `agent.assert` は、`screenshot: false` でなければ判定の成否にかかわらず撮影します。`app.screenshot('label')` でも撮影できます。マスキングされるのはセキュアなフィールドだけです。[シークレット入力後のスクリーンショット](https://e2e.com/docs/ja/reference/security#screenshots-after-a-secret-fill)を参照してください。 |
| ダウンロード | `browser.waitForDownload` で保存したファイルを `download` として、アプリが提供した内容で保存します。ランナーがシークレットをマスキングする条件は[ダウンロード](https://e2e.com/docs/ja/reference/security#downloads)を参照してください。 |
| 動画 | [録画を有効にした場合](#watch-it-happen)。動画は何もマスキングしません。[マスキングの限界](https://e2e.com/docs/ja/reference/security#where-redaction-stops)を参照してください。 |
| エージェントのトランスクリプト | [`--debug`](#agent-steps) を指定した場合。 |

## スクリプトから読む report.json

テストの実行まで進む実行は、[出力ディレクトリ](https://e2e.com/docs/ja/reference/config#output)（デフォルトは `.e2e`）に `report.json` も書きます。バージョン付きスキーマで、実行の全結果を保持します。`--reporter json` はこれを標準出力に表示します。

```bash
jq '.run | {status, exitCode, errors}' .e2e/report.json
jq '.run.results[] | select(.status != "passed") | .attempts[-1]
    | {status, error, failure, steps: [.steps[] | select(.status != "passed") | {api, label, source, status, error}], artifacts}' .e2e/report.json
```

`run.errors` は実行全体の失敗を保持します。失敗した各結果の最後の試行には、次の情報があります。

| フィールド | 内容 |
| --- | --- |
| `error` | コード、メッセージ、ソース行、アサーションの詳細 |
| `failure` | 画面とスクリーンショットのアーティファクト、ロケーター候補 |
| `steps` | 失敗までの呼び出し。各ステップの `events` は、実行内容（`engine`）、ポーリングした内容（`poll`）、アプリの移動先（`navigation`）を保持します。エージェントステップには `cache` と直近のモデルターンも加わります。`observationTruncated: true` は、少なくともひとつのセマンティックな観測が不完全だったことを示します。 |
| `appLog` | アプリのログ。各行の `step` は対応するステップの `index` で、最初のステップより前は省略されます。 |
| `artifacts` | 保存したファイル |

直列実行グループの各テストには、独自の `attempts` はありません。結果は `run.serialGroups` にあり、試行ごとの各テストにひとつのメンバーがあります。実行が中断したリトライや、メンバーの実行まで到達しなかったリトライは `cutRetry: true` で、判定を持たないため読み飛ばしてください。

```bash
jq '.run.serialGroups[] | (.attempts | map(select(.cutRetry != true)) | last).members[]? | select(.status != "passed")
    | {testId, status, error, failure}' .e2e/report.json
```

## 動作を目で確認する

<CodeGroup>
```bash npm
npx e2e run --headed                      # a visible browser
npx e2e run --video                       # record every attempt
npx e2e run --video=retain-on-failure     # record every attempt, keep the failures
```

```bash pnpm
pnpm exec e2e run --headed                      # a visible browser
pnpm exec e2e run --video                       # record every attempt
pnpm exec e2e run --video=retain-on-failure     # record every attempt, keep the failures
```

```bash bun
bunx e2e run --headed                      # a visible browser
bunx e2e run --video                       # record every attempt
bunx e2e run --video=retain-on-failure     # record every attempt, keep the failures
```
</CodeGroup>

`--video` は任意のモードを受け取ります。テストファイルはその前に指定するか、`--video=<mode>` と書いてください。

各録画は試行のディレクトリに保存されます。Web ではページごとの WebM、デバイスでは MP4 です。失敗のまとめにはパスが表示され、ホスト型ブラウザが録画を保持する場合は URL が表示されます。ステップの `startedAt` から録画の `startedAt` を引くと、動画内の位置がわかります。

CI では、設定に `video: 'on-first-retry'` を指定します。初回で成功したテストは録画せず、flaky なテストはリトライの録画を残します。

ターゲットの `video` は全体設定より優先され、`--video` はその両方より優先されます。`test('checkout', { video: 'on' }, ...)` のようなテスト自身のオプションは、すべてに優先します。

全体設定の `video` と `--video` は、録画に対応するエンジンのターゲットにだけ適用されます。対応しないものは通知に列挙されます。ターゲットやテストが未対応の録画を明示的に要求した場合、テスト開始前に `UNSUPPORTED_ARTIFACT` で失敗します。

すべてのモードとファイルについては、[記録](https://e2e.com/docs/ja/reference/config#recording)を参照してください。

## テストをステップ実行する

`--step` は最初のステップを実行した後、キーを押すまで後続の各ステップを待機させます。ステップ間のブラウザを見るには、`--headed` を追加します。

<CodeGroup>
```bash npm
npx e2e run tests/checkout.e2e.ts --step --headed
```

```bash pnpm
pnpm exec e2e run tests/checkout.e2e.ts --step --headed
```

```bash bun
bunx e2e run tests/checkout.e2e.ts --step --headed
```
</CodeGroup>

待機中のステップは、実行済みステップの下に表示されます。

```text
 ❯ |web| tests/checkout.e2e.ts 0/1
   └── pays with a card paused
       ✓ app.open "/checkout" 412ms
       ▶ step 2  locator.fill "getByLabel("Email")"  tests/checkout.e2e.ts:9
         press enter to run this step, press h to show help, press q to quit
```

キー操作は [`--watch`](https://e2e.com/docs/ja/reference/cli#watch-mode) に準じます。プロンプトでは次が使えます。

| キー | 動作 |
| --- | --- |
| Enter | 待機中のステップを実行し、次で待機 |
| `n` | リトライも含めてこのテストの残りを実行し、次のテストで待機 |
| `a` | 残りの実行を止めずに続行 |
| `h` | プロンプトの下に全キーを表示、または非表示 |
| `q`、Esc | Ctrl-C と同様に停止。テストは `interrupted`、残りはスキップ、終了コード 130 |

- 前のステップ向けのキーで次を実行しないよう、プロンプト表示から 150 ms 以内のキー入力は無視します。Ctrl-C は、ステップ実行中も含めていつでも使えます。
- 待機時間は、ステップの所要時間、テストの `timeout`、`maxDuration` のいずれにも加算しません。ステップ後にテストがハングした場合は、残り時間でタイムアウトします。レポートのテスト自身の所要時間には待機時間を含みます。
- セットアップテスト、リトライ、`afterEach` フック、フィクスチャの後処理、`expect.poll` の読み取り内のステップは停止せず実行します。`agent.act` はひとつのステップです。
- `Promise.all` などで同時に開始したステップは、ひとつのプロンプトを共有し、1 回の Enter で実行します。そのため、トリガーとなるクリックと並べた `waitForResponse` がキー待ちになることはありません。別のステップが待機中になった時点ですでに動いていたステップは、自身のタイムアウトで実行を続けます。
- 待機中に長時間何も操作しないと、ホスト型ブラウザやデバイスのサービスがセッションを終了することがあります。

`--step` はテストを 1 つずつ実行します。CI、`--watch`、1 を超える `--workers`、json レポーターとの併用は拒否されます。

## ターミナルなしでステップ実行する

コーディングエージェントのシェルなど、標準入力または標準出力がターミナルでない場合、`--step` はテストをバックグラウンドで実行します。コマンドは最初の待機ステップで、そのステップが待っている画面とともに戻ります。後続のコマンドも同じディレクトリで実行してください。コマンドにターミナルを割り当てるシェルでは、代わりにキー入力のプロンプトになります。その場合は標準入力を null デバイスからリダイレクトします（`< /dev/null`、Windows の `cmd` では `< NUL`）。

<CodeGroup>
```bash npm
npx e2e run tests/checkout.e2e.ts --step
npx e2e run --step next
```

```bash pnpm
pnpm exec e2e run tests/checkout.e2e.ts --step
pnpm exec e2e run --step next
```

```bash bun
bunx e2e run tests/checkout.e2e.ts --step
bunx e2e run --step next
```
</CodeGroup>

```text
✓ app.open "/checkout" 124ms
Paused before step 2 of pays with a card [web]:
  locator.fill "getByLabel("Email")" (tests/checkout.e2e.ts:9)
Screen:
  http://localhost:3000/checkout
  heading "Checkout"
  textbox "Email"
  button "Pay"
Next: e2e run --step next runs it, e2e run --step rest runs the rest, e2e run --step stop ends the run.
```

| コマンド | 動作 |
| --- | --- |
| `e2e run --step next` | 待機中のステップを実行し、次で戻る |
| `e2e run --step rest` | 残りの実行を止めずに続行 |
| `e2e run --step stop` | 別のコマンドが待機中でも、`q` と同様に停止。終了コード 130 |

- 各応答の冒頭には、前のコマンド以降の出力が付きます。上の最初の行のように、実行したステップごとに 1 行表示し、失敗した場合はその下にエラーを表示します。最後の応答は実行サマリーと `The stepped run has ended.` で終わり、コマンドは実行全体の終了コードで終了します。
- 画面はトレースページと同様にアプリのノードを列挙し、シークレットをマスキングします。
- ひとつのディレクトリでステップ実行できるのはひとつだけです。最初の実行が終わるまで、2 つ目の `--step` は終了コード 2 で終了します。
- `next` と `rest` は、コマンドが表示済みのステップだけを進めます。待機中のコマンドを強制終了した場合、次のコマンドは見逃した内容を表示します。ステップなら実行せずに表示し、実行が終わっていれば終了を表示します。ステップ実行中に送った `next` や `rest` は、操作せずに次の停止を待ちます。どちらの場合も、操作を適用しなかったことを示す行で応答が始まります。
- コマンドなしでステップが 30 分待機すると、実行を停止します。
- `--step` を使う場合、`next`、`rest`、`stop` というファイルやディレクトリには、`./next` のようにパスを付ける必要があります。

## コンソール出力

テスト内の `console.log` と `console.error` は、実行中に表示されます。ストリーム、ターゲット、ファイル、テストを示す見出しが付きます。

```text
stdout | |web| tests/todos.e2e.ts > adds a todo
hello from the test
```

ファイルの最上位やレポーターなど、テスト外の出力は `stdout | runner` または `stderr | runner` の下に表示します。両ストリームとも標準出力に表示します。`list` レポーターがなければ、各出力は元のストリームにそのまま流れます。ただし `json` レポーター（`--reporter json` または `reporters` 内）では、標準出力をレポート専用にし、その他は標準エラー出力に流します。設定読み込み中の出力は実行ヘッダーより前に表示されます。読み込みが失敗した場合は警告に置き換わります。

ランナーはシークレットの値を[マスキング](https://e2e.com/docs/ja/reference/security#redaction)します。レポートにコンソール出力は含まれないため、後から読む人に必要な情報は `expect` またはアーティファクトを使って残してください。

## エージェントステップ

次のフラグで、エージェントの動作を確認できます。

<CodeGroup>
```bash npm
npx e2e run --debug     # timings and a step table on stderr
npx e2e run --ai-trace  # every model call, for a trace viewer
npx e2e run --no-cache  # run the agent live instead of replaying
```

```bash pnpm
pnpm exec e2e run --debug     # timings and a step table on stderr
pnpm exec e2e run --ai-trace  # every model call, for a trace viewer
pnpm exec e2e run --no-cache  # run the agent live instead of replaying
```

```bash bun
bunx e2e run --debug     # timings and a step table on stderr
bunx e2e run --ai-trace  # every model call, for a trace viewer
bunx e2e run --no-cache  # run the agent live instead of replaying
```
</CodeGroup>

`--debug` は、実行のフェーズ別所要時間と、エージェントステップごとの表を追加します。表には所要時間、モデル呼び出し回数、トークン数、プロンプトキャッシュの割合、プロバイダーが報告する場合は費用が表示されます。計画された各ステップは、モデルのトランスクリプトもアーティファクトとして保存します。

```console
[e2e debug] agent steps (execution order, model openai/gpt-6-luna-fast, total $0.0312)
  step                                   total   model  observe  action  calls  tokens in/out  cached       cost
  act "add a todo named groceries"       3.9s    2.8s    410ms   620ms      3  9412/388       61% (5740)   $0.0198
  assert "the list shows groceries"      1.2s    1.1s     88ms     0ms      1  3120/41        0% (0)       $0.0114
```

`--ai-trace` は `.e2e/ai-trace.json` を書きます。エージェントステップごとに 1 実行、モデル呼び出しごとに 1 エントリーがあり、入力は機密情報をマスキングし、画像のバイト列はサイズに置き換えます。[unbox-ai](https://github.com/e2e-inc/unbox-ai) で、プロンプト、ツール呼び出し、トークン使用量を確認できます。

<CodeGroup>
```bash npm
npx unbox-ai runs .e2e/ai-trace.json
npx unbox-ai summary .e2e/ai-trace.json --run 0
```

```bash pnpm
pnpm dlx unbox-ai runs .e2e/ai-trace.json
pnpm dlx unbox-ai summary .e2e/ai-trace.json --run 0
```

```bash bun
bunx unbox-ai runs .e2e/ai-trace.json
bunx unbox-ai summary .e2e/ai-trace.json --run 0
```
</CodeGroup>

再生したステップはモデルを呼ばず、AI トレースも残しません。フロー全体を記録する、または古い[記録](https://e2e.com/docs/ja/cache)を原因から除外するには、`--no-cache` を追加します。

## よくあるエラー

| コード | よくある原因 | 対処 |
| --- | --- | --- |
| `APP_UNREACHABLE` | `app.url` に応答がない、または `app.command` の準備が完了しない。iOS では、メッセージが代わりに自動化ランナーを指す場合がある | `app.command.log` を設定して読み、ポートを確認し、`app.command.startupTimeout` を増やす。iOS ランナーの場合はメッセージに従う（[モバイル](https://e2e.com/docs/ja/mobile#troubleshooting)を参照） |
| `APP_ALREADY_RUNNING` | ランナーが `app.command` を起動しようとした時点で、すでに `app.url` が使われている | 停止するか、ローカル実行で `reuseExisting: true` を設定 |
| `LOCATOR_NOT_FOUND` | ロールや名前が違う、テキストが完全一致しない、iframe 内の要素、ページが開かれていない | マークアップでアクセシブルネームを確認。`exact: false` を試す。iframe には `browser.frameLocator`、目視には `--headed` |
| `LOCATOR_AMBIGUOUS` | 非表示の重複要素や同じラベルなど、2 つの一致がある | `{ name }` を追加、コンテナー内に限定、`filter`、`first()`、`{ visible: true }` を使用 |
| `ASSERTION_FAILED` | 期待値が違う、状態の確定に 5 秒以上かかる、または `agent.assert` が偽と判定した | スクリーンショットと比較。マッチャーに `{ timeout }` を指定。質問を書き直す |
| `ASSERTION_INCONCLUSIVE` | `agent.assert` や `agent.extract` が、別ページ、読み込み中、画像だけの情報など、画面に現れていない内容を尋ねた | 正しい画面を開くか待つ。答えが画像内にある場合は `vision: true` を追加（メッセージにも表示） |
| `ACTION_FAILED` | 要素が覆われている、無効、削除済み、または操作がタイムアウトした | 先に `expect` で適切な条件を待つ。オーバーレイを閉じる |
| `STEP_BUDGET_EXHAUSTED`、`STEP_TIMEOUT` | エージェントの操作数、モデル呼び出し数、時間が尽きた | 目標を 1 ステップに絞る。予算ならエージェントの `maxSteps` または `maxModelCalls`、`act` の時間なら設定の `timeout`、`assert`、`waitFor`、`extract` ならエージェントの `judgmentTimeout` を増やす |
| `MODEL_UNAVAILABLE` | 設定にモデルが作られていない、または GitHub Copilot がアカウントにモデルを提供していない | [モデル](https://e2e.com/docs/ja/models)を参照。Copilot では[モデルを選ぶ](https://e2e.com/docs/ja/subscriptions#pick-a-model)を参照 |
| `MODEL_PROVIDER_FAILED` | キーが不正、レート制限、残高不足、またはひとつのリクエストの全試行が 120 秒応答なし | プロバイダーが読むキーと利用枠を確認。遅いローカルモデルでは画面を小さくする（`agents.<name>.maxObservationBytes`）か、高速なモデルを使う |
| `MODEL_REFUSED` | モデルがプロンプトを拒否した（終了理由 `content-filter`）。終了コード 1 | 指示を言い換えるか、別のモデルに切り替える |

[エラーリファレンス](https://e2e.com/docs/ja/reference/errors)に、すべてのコード、分類、終了コードを記載しています。

## 次のステップ

<CardGroup cols={2}>
  <Card title="CLI リファレンス" icon="terminal" href="/reference/cli#e2e-run">
    `e2e run` の全フラグを確認します。
  </Card>
  <Card title="エラー" icon="triangle-exclamation" href="/reference/errors">
    すべてのエラーコードを確認します。
  </Card>
</CardGroup>
