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

# キャッシュ

> 確認済みのエージェント操作をモデル呼び出しなしで再生し、アプリが変わったらエージェントに引き継ぎます。

リプレイキャッシュは、後続の確認で結果が検証された `agent.act()` ステップの操作を記録します。次の実行では、ランナーがモデルを呼ばずにその操作を再生します。コントロールや期待する終了状態が一致しなくなると、エージェントが現在の画面から引き継ぎます。[セルフヒーリングするテスト](https://e2e.com/docs/ja/self-healing)を参照してください。

`agent.assert`、`agent.waitFor`、`agent.extract` は、毎回実際に実行されます。実行サマリーには結果別の件数が表示されます。

```text
           AI  4.1k tokens · 2 model calls · openai/gpt-6-luna-fast
        Cache  4 replayed · 1 handed off · 1 missed · 1 not saved
```

`not saved` は、成功または flaky となったテストのうち、成功した試行で [`step.cache.write`](#when-a-recording-is-written) が `unconfirmed`、`no-change`、`not-written` だったステップを数えます。

## 記録が書き込まれる条件

テストの最後に、結果を確認してください。`read-write` モードでは、後続の検証ステップが成功した各 `act` の記録を、試行終了時にランナーが保存します。最後のひとつの確認で、それ以前のすべての `act` を確認済みにできます。

```ts title="tests/cart.e2e.ts"

test('adds an item', async ({ app, agent, screen }) => {
  await app.open('/cart');

  await agent.act('add one item to the cart');

  await expect(screen.getByRole('status')).toHaveText('1 item');
});
```

| 検証として数えるもの | 数えないもの |
| --- | --- |
| `expect(locator).toHaveText(...)` などのロケーターマッチャー | 通常の値に対する `expect(value).toBe(...)` |
| `expect(browser).toHaveURL(...)` などのエンジンアサーション | `expect.poll(...)` |
| `locator.waitFor()`、`browser.waitForURL()` | `locator.textContent()` などの読み取り |
| `agent.assert(...)`、`agent.waitFor(...)` | `agent.extract(...)`、別の `act`、試行自体の成功 |

レポートにだけ含まれる `step.cache.write` は、試行終了時に記録をどう扱ったかを示します。

| `step.cache.write` | 意味 |
| --- | --- |
| `saved` | 次の実行用に記録しました。 |
| `kept` | エントリーをそのまま保持しました。 |
| `unconfirmed` | ステップ後に確認が成功しなかったため保存していません。ロケーターやエンジンのアサーション、`agent.assert` でテストを終えるか、`locator.waitFor()` や `agent.waitFor` で状態を待ってください。 |
| `evicted` | エントリーを削除しました。再生が失敗や修復で終わったか、試行が失敗する前に確認されませんでした。 |
| `no-change` | 記録していません。コントロールの出現、消失、状態変化がなく、ルートも変わりませんでした。[別サイトのフレーム](https://e2e.com/docs/ja/browser#reach-into-an-iframe)内だけが変わったステップも含みます。このようなステップは毎回実行されます。 |
| `not-written` | 保存していません。ストアが書き込みを拒否したか、ファイルストアのサイズ上限超過などにより記録を受け付けませんでした。 |

操作を行わなかったステップは何も記録せず、`write` も報告しません。

失敗した試行でも、失敗前に検証済みのステップは保存します。未検証のエントリーと、失敗に関わったリプレイは削除します。失敗するアサーションを直す間もセットアップの目標を記録に残したい場合は、`locator.waitFor()` など、状態を待つ処理でセットアップを終えてください。独自ストアでこの削除に対応するには `delete` メソッドが必要です。実行をキャンセルした場合、キャッシュは変更しません。

<Accordion title="モデルが応答しなかった場合の失敗">
モデルが応答しなかった失敗しかない試行では、何も削除しません。次の失敗はアプリの状態を示すものではないためです。

- `MODEL_UNAVAILABLE`: モデルが未設定、または GitHub Copilot がそのアカウントにモデルを提供していません。
- `MODEL_PROVIDER_FAILED`: キーの不足や拒否、レート制限、5xx などのエラーがプロバイダーから返ったか、120 秒以内にリクエストへの応答がありませんでした。

そのため、モデルにアクセスできない `read-write` 実行でも記録を保持します。モデルに到達できなかった `agent.assert` より前に再生したステップも含みます。

一方、使えないモデルの回答（`MODEL_OUTPUT_INVALID`、`CONTEXT_OVERFLOW`）、拒否（`MODEL_REFUSED`）、`STEP_TIMEOUT`（リクエストが処理中でも）、同じ試行内の `afterEach` アサーションなどの他の失敗は、フローの失敗として扱います。
</Accordion>

## 一致が必要な情報

キャッシュエントリーは、ひとつのテスト、ターゲット、指示、パラメーターの組み合わせ、エージェントに属します。次の変更はいずれもキャッシュミスになります。

- テスト、`describe` グループ、ターゲットの名前を変える、またはテストファイルを移動する。
- 指示や通常のパラメーターを変える。
- 別の設定済みエージェントで実行する（`agent: ['buyer', 'admin']` はそれぞれ別のエントリーを記録）、エージェントの `context` またはテストの `agentContext` を変える。その中のシークレットは、名前だけがキーに入ります。
- エンジンを変える、プロジェクト ID またはアプリの識別情報を変える。

モデルの変更やエンジンのアップグレード自体は、キャッシュミスになりません。新しいバージョンがノードを異なる形で解決する場合は、再生時に一致しなくなります。

新しいモデルを評価するには `--no-cache` を使います。記録元の情報を持つエントリーでは、再生時に `step.cache.recordedBy` を公開します。古いエントリーや記録元が不明なエントリーでは省略されます。

タイムスタンプや毎回新しいメールアドレスは、そのままでは毎回キャッシュミスになります。`unique()` で包むと、再生時にランナーが現在の値を入れます。

```ts

const name = `E2E ${Date.now()} Company`;
await agent.act('create a company named {name}', { params: { name: unique(name) } });
await expect(screen.getByRole('heading', { name })).toBeVisible();
```

フローで入力・確認するデータには `unique()` を使い、プラン名などフロー自体を変える選択には通常のパラメーターを使います。値の置換は、URL 内の表記（`%20`、`+`）や、画面上で 1 行になった複数行の値にも対応します。`unique()` の値が別のパラメーター値と等しい、またはその一部になっている場合、そのステップは記録されません。`step.cache.notRecorded` が `param-collision` となり、次の実行で記録します。

デプロイごとに変わるプレビュー URL では、[`app.identity`](https://e2e.com/docs/ja/reference/config#the-app-under-test) を設定してキャッシュの識別情報を固定します。デバイスでは、リプレイは[画面タイトル](https://e2e.com/docs/ja/reference/mobile#replay-cache-on-a-device)をパスとして使います。

## 修正しながらテストを再実行する

失敗したテストを直す間は、ローカルのデフォルトである `read-write` モードを維持し、書き込みを行わない[厳格モード](#fail-on-a-stale-recording)は無効にしてください。`CI` が設定されている場合、モード未指定時は `read-only` です。失敗した実行でも、その前に[確認済み](#when-a-recording-is-written)となった記録は保持します。次の実行では、画面と一致する限り、それらの目標をモデル呼び出しなしで再生します。

1. `test(` が始まる行で、そのテストだけを実行します: `npx e2e run tests/cart.e2e.ts:3`。
2. テスト名や、成功している目標の文言を変えないでください。どちらも[キャッシュミスの原因](#what-must-match)です。名前を変えるとテスト内の全目標、目標の文言を変えるとその目標が対象になります。
3. リトライが有効な場合（設定の `retries`、または `CI` が設定済み）は、`--retries 0` を追加します。テストや `describe` の `retries` オプションは、このフラグより優先されます。リトライでは再生せず、すべての目標を実行します。
4. テストが成功したら、一度 `--no-cache` で実行します。すべての目標を実行することで、記録なしでもエージェントが達成できることを確認します。

## リプレイの仕組み

1. 開始画面を確認します。同じルートでなければなりません。
2. 記録した各コントロールを、ロール、名前、テスト ID、周囲の文脈から探し、操作を繰り返します。ランナーは見つからないコントロールを待ち、一致が曖昧なら停止します。
3. 最終ルートと、元のステップが変えた内容を確認します。出現したコントロールとその checked、selected、expanded、pressed 状態、消失したコントロールが対象です。
4. モデルを呼ばずに完了するか、実行済みの内容と停止理由の記録を渡してエージェントに続行させます。

入力値は記録どおりに再生します。シークレットの入力は、名前から現在値を解決し、再び認可を受けます。

記録した変化が表示されるとリプレイは完了します。その下のコンテンツがまだ読み込み中の場合もあります。ステップの後に読み込まれる内容を確認するには、画面を一度だけ判定する `agent.assert` ではなく、表示を待つ `agent.waitFor` を使ってください。

<Accordion title="同じルートとみなす条件">
ルートはオリジン、パス、クエリで構成します。レコード ID とフラグメントは含みません。パスやクエリ内の ID、トークン、タイムスタンプ、キャッシュ回避用の値は ID のプレースホルダーとして扱うため、`/orders/42?t=1727780000` と `/orders/7?t=1727780999` は同じルートです。

その他のクエリ値はすべてルートの一部です。`?mode=safe` と `?mode=unsafe`、`/companies` と `/companies?tab=notes` は異なり、新しいトラッキングパラメーターも違いになります。`/products/summer-sneaker` と `/products/winter-boot` も別のルートです。

アプリ自身のオリジンにある場所はパスで比較するため、同じ `app.identity` を持つプレビューデプロイでも記録を使えます。他のオリジンのページは別のルートです。
</Accordion>

<Accordion title="終了確認が画面を読む方法">
- 記録した変化の少なくともひとつが、リプレイ中に起きる必要があります。操作前から画面にある結果は証拠になりません。最後の操作が別ルートへ移動した場合は、その移動が根拠になります。
- 記録時にはなかったアラートがリプレイ中に出ると、停止します。Web エンジンは Next.js App Router のルートアナウンサーを観測しないため、そのタイトルの再通知は対象になりません。
- 日付、所要時間、ID など毎回変わるテキストは、ステップの差分の出現側または消失側に安定した変化があれば無視します。他に変化がなければ残し、値が変わるとエージェントに引き継ぎます。アラート内ではプレースホルダーとして扱います。アプリが生成するテスト ID（`node-<uuid>`）だけで識別されるノードも同様に無視します。確認対象に残す場合、出現したノードはそのパターンに一致する任意の ID でよい一方、消失したノードは元の正確な ID で確認します。
- `3 records imported` のように対象を明示する件数は、操作した画面にステップが新たに表示させた場合、再生時も一致する必要があります。単に増減した件数（`41 items` から `42 items`）や、移動先の画面にある件数は、差分の同じ側に安定した変化がある場合にだけ無視します。反対側に安定した変化があっても、それだけでは件数を外しません。バッジのような数字だけの表示には、前述のテキストのルールを適用します。
- 名前のないコントロールは、同じ名前付きの行、リスト項目、グループ内にある、同種の無名コントロール間での位置で探します。生成されたテスト ID だけで識別するコントロールも、ID パターンを使って同様に探すか、そのパターンを持つ唯一の要素だった場合に特定します。
</Accordion>

## ステップが再生されなかった理由

各 `act` ステップは `step.cache` を報告します。そのステップのキャッシュが無効な場合は省略されます。`agent.act()` は `write` を除いたものを `result.cache` として返し、[トレースページ](https://e2e.com/docs/ja/debugging#traces)ではステップの下に表示します。

| 実行サマリー | `step.cache.mode` | 意味 |
| --- | --- | --- |
| `replayed` | `self-finalized` | モデルを呼ばずに記録の再生を完了しました。 |
| `handed off` | `agent-concluded` | 再生を開始した後、エージェントに引き継ぎました。 |
| `missed` | `missed` | エージェントが最初からステップを実行しました。 |

引き継ぎとミスには `step.cache.reason` が付き、`step.cache.detail` が停止位置と理由を示します（`at action 2 of 3, tap button "Apply": ...`）。`end-mismatch` の後には、表示されなかった記録済みノード、消えなかったノード、記録時になかったアラートが列挙されます。または、操作前から結果が表示されていたことを示します。`step.cache.entry` は、エントリーのキーであり、ファイルストア内のファイル名（`<entry>.json`）にもなります。

| 理由 | 起きたこと | 対処 |
| --- | --- | --- |
| `no-entry` | ステップとパラメーターに一致する記録がありません。 | `step.cache.write` が `no-change` でなければ、次に検証付きで成功したときに記録します。 |
| `retry` | `--strict-cache` または `cache.strict` を除き、リトライでは再生しません。 | 対処は不要です。 |
| `invalid-entry` | ファイルが読めない、1 MiB を超える、またはスキーマのバージョンが異なります。 | `npx e2e cache clear` を実行します。 |
| `truncated` | 記録が上限に達しました。[以下](#limits-and-gaps)を参照してください。 | ステップを分割するか、シークレットを `Secret` として渡します。 |
| `wrong-context` | 記録時とは別のルートにアプリがありました。[リプレイの仕組み](#how-a-replay-works)を参照してください。 | ステップの前に同じ画面を開きます。 |
| `target-not-found` | 記録済みコントロールが 15 秒以内に現れなかったか、名前も名前付きコンテナーもなく、同種の要素と区別できません。 | UI が変わった場合は、次の成功時に記録し直します。無名のコントロールにはラベルを付けるか、名前付きの行やグループに置きます。 |
| `target-ambiguous` | 一致するコントロールの数が変わりました。 | 繰り返されるコントロールに異なる名前を付けるか、一意なテストデータを使います。 |
| `gap` | 再生できない操作です。[以下](#limits-and-gaps)を参照してください。 | この部分はエージェントが実行します。固定の値は `params` に入れます。 |
| `action-failed` | アプリが再生した操作を拒否しました。 | アプリを確認します。 |
| `action-uncertain` | 再生した操作が失敗し、反映されたか不明です。エージェントには再操作前に確認するよう伝えます。 | アプリを確認します。 |
| `viewport-changed` | ノードに結び付かない座標のタップ、ホバー、ドラッグが、異なるサイズのビューポートで記録されていました。 | ビューポートを固定します。 |
| `end-mismatch` | 全操作は実行されましたが、[終了確認](#how-a-replay-works)が失敗しました。 | 前の実行のデータ残り、表示が変わるバナー、リグレッションなどが考えられます。一意なテストデータと `afterEach` での後処理が役立ちます。 |

失敗の原因からキャッシュを切り分けるには、一度キャッシュなしで実行します。

<CodeGroup>
```bash npm
npx e2e run --no-cache
```

```bash pnpm
pnpm exec e2e run --no-cache
```

```bash bun
bunx e2e run --no-cache
```
</CodeGroup>

### 上限と再生できない操作

次のステップは、記録が `truncated` になります。

- 50 回を超える操作を行った場合。`maxSteps` が 50 を超えるときだけ起こります。
- 4,096 文字を超える値や URL、または登録済みシークレットを含む値や URL を入力した場合。
- 使用可能な説明を持たないコントロールを操作した場合。

`gap` は、キャッシュが繰り返せない操作です。状態を変更する[プロジェクトツール](https://e2e.com/docs/ja/tools)、またはエージェントが画面から読み取った値、スクリーンショットを見た後に入力した値、日付から算出した値が該当します。`step.cache.derived` は該当ルールを示します。`whole-node`（コントロールの名前またはテキスト全体）、`minted-token`（アプリが独立した語として表示したコードや ID）、`date`、`pixels` です。指示や `params` にある値と、エージェント自身が作った値は再生されます。

## 記録の内容

各エントリーは `.e2e/cache/` 配下の JSON ファイルで、キーのハッシュをファイル名に使います。操作、対象の説明、入力テキスト、ステップの要約、終了確認を保持します。終了確認にはルートと、出現したコントロール最大 8 個、消失したコントロール最大 8 個が含まれます。プロンプト、会話、スクリーンショット、観測ツリー、シークレットの値は含みません。シークレットの入力では名前だけを保存します。

<Warning>
それ以外の入力値はそのまま保存します。共有前に記録をレビューしてください。[キャッシュの信頼性](https://e2e.com/docs/ja/reference/security#cache-trust)を参照してください。
</Warning>

## モード

| モード | 再生 | 記録 | デフォルトになる条件 |
| --- | --- | --- | --- |
| `'read-write'` | する | する | ローカル |
| `'read-only'` | する | しない | CI で `cache` が未設定 |
| `'off'` | しない | しない | `--no-cache` を指定した実行 |

```ts title="e2e.config.ts fragment"
cache: 'off',
// or
cache: { mode: 'read-write', dir: '.e2e/cache' },
```

`--no-cache` は設定を上書きします。`read-only` モードでは、`read-write` 実行で置き換えるまで古いエントリーを保持します。独自の `cache.store` はファイルストアを置き換え、CI でもデフォルトが `read-only` にはなりません。`e2e explore` と `e2e mcp` のセッションはキャッシュを使いません。ただしセッション内で実行するテスト（[`open_session {test}`](https://e2e.com/docs/ja/reference/mcp#running-a-test)）は、通常実行の最初の試行と同じように使います。

## 複数のチェックアウトでキャッシュを共有する

`E2E_CACHE_DIR`、または 1 回の実行用の `--cache-dir` で、プロジェクトの全チェックアウトから同じディレクトリを指定します。どちらも `cache.dir` を置き換え、プロジェクトルートから解決されます（`~` または先頭の `~/` はホームディレクトリ）。モードは変わりません。独自の `cache.store` では `--cache-dir` はエラーになり、`E2E_CACHE_DIR` は無視されます。各書き込みはファイルをアトミックに置き換えるため、並列実行でも共有できます。キーはプロジェクト単位なので、すべてのチェックアウトに同じ `projectId`（または `package.json` の `name`）を指定してください。どちらもなければ、各チェックアウトのパスが識別情報となり、相互に再生できません。

- エントリーは共有されるため、どれかの実行が失敗するとエントリーが削除されます。また、同じアプリ識別情報で異なるアプリコードを使うチェックアウトは、互いのエントリーを上書きします（最後の書き込みが優先）。
- 上書き指定中は、`cache.dir` にコミットしたキャッシュを読みません。
- プロジェクトごとにディレクトリを分けてください。2 つのプロジェクトを同じディレクトリに置くと、`cache.strict` で誤った `REPLAY_STALE` が起こる可能性があります。

```bash
E2E_CACHE_DIR=~/.cache/my-app/e2e npx e2e run
```

## リプレイキャッシュをコミットする

<span id="commit-your-traces" />

`e2e init` は `.gitignore` に `.e2e/cache/` を追加するため、各マシンが自分の記録を作り、CI は記録なしで始まります。再生を共有するには、その行を削除してディレクトリをコミットします。`cache: 'read-write'` を設定しない限り、CI は `read-only` のままです。コミットしたエントリーはテストデータとして扱い、記録し直したプルリクエストでレビューしてください。

ローカル実行は、何かが変わらなければコミット済みディレクトリを変更しません。再生したステップはエントリーを書き直さず、実際に実行した記録も操作、パス、基準情報が同じなら書き込みません。そのため、少しずつ変わる UI のエントリーは、コントロールを見つけられなくなった時点で初めて修復されます。ファイルが変わるのは次の場合です。

- ステップを初めて記録した、またはエージェントへの引き継ぎ後に記録した。
- 再生後にステップが失敗した、エージェントが修復を要する `end-mismatch` で終わった、記録するものがないまま成功した、または試行終了までに確認されなかった。これらはエントリーを削除します。
- `e2e` のアップグレードで照合方法が変わり、すべてのエントリーに新しいキーが付いた。次の実行で記録し直します。

## 古くなった記録で失敗させる

デフォルトでは、コミット済み記録を再生できなくなっても、それ自体では失敗しません。エージェントが引き継ぎ、誰かが記録し直すまで、CI の実行ごとにモデル呼び出しの費用がかかります。`--strict-cache`（または `cache: { strict: true }`）を指定すると、ステップは `REPLAY_STALE` で失敗し、モデルを呼びません。

<CodeGroup>
```bash npm
CI=1 npx e2e run --strict-cache
```

```bash pnpm
CI=1 pnpm exec e2e run --strict-cache
```

```bash bun
CI=1 bunx e2e run --strict-cache
```
</CodeGroup>

`REPLAY_STALE` の終了コードは 2 で、リトライされません。

| 厳格モードで失敗するもの | 引き続き実行するもの |
| --- | --- |
| `invalid-entry`、`wrong-context`、`target-not-found`、`target-ambiguous`、`viewport-changed`、`action-failed`、`action-uncertain`、`end-mismatch`: アプリまたはエントリーが変わった | 一度も記録されていないステップ（新規または編集済みの指示やパラメーター） |
| `no-entry`: キャッシュディレクトリに同じステップの記録が別のキーで存在する場合 | `gap` または `truncated` の記録 |
| | ストアの読み取りが失敗したステップ |

別のキーの記録は、キーを変える `e2e` のアップグレード、プロジェクト ID、アプリの識別情報、エージェントのコンテキストの変更などで生じます。メッセージにはそのファイルと、現行バージョンで作られた記録なら変更点も示されます。何も再生しなくなったファイルは削除してください。この検査は、独自の `cache.store` には適用されません。

厳格モードの実行は、`read-write` でもエントリーの書き込みや削除を行いません。新しいステップを記録できるのは、厳格モードでない実行だけです。設定内の `cache.strict` より、CI での `--strict-cache` を推奨します。古いエントリーを直すには、次の手順を行います。

1. フラグを付けずに `read-write` モードでテストを実行します。設定に `cache.strict` があれば無効にします。
2. 変わったエントリーをコミットします。独自の `cache.store` には、その実行から新しいエントリーが渡ります。

## キャッシュを調べる

<CodeGroup>
```bash npm
npx e2e cache ls      # one row per entry: test, target, instruction digest, age, actions
npx e2e cache stats   # entry count and size
npx e2e cache clear   # delete every entry
```

```bash pnpm
pnpm exec e2e cache ls      # one row per entry: test, target, instruction digest, age, actions
pnpm exec e2e cache stats   # entry count and size
pnpm exec e2e cache clear   # delete every entry
```

```bash bun
bunx e2e cache ls      # one row per entry: test, target, instruction digest, age, actions
bunx e2e cache stats   # entry count and size
bunx e2e cache clear   # delete every entry
```
</CodeGroup>

<Note>
AI 使用量の `cached` の割合は、プロバイダーのプロンプトキャッシュです。モデル呼び出しの費用を下げます。リプレイキャッシュは呼び出し自体を省略します。
</Note>

## 次のステップ

<CardGroup cols={2}>
  <Card title="設定リファレンス" icon="sliders" href="/reference/config#cache">
    `mode`、`store`、`dir` を確認します。
  </Card>
  <Card title="CLI リファレンス" icon="terminal" href="/reference/cli#e2e-cache">
    `e2e cache ls`、`stats`、`clear` を確認します。
  </Card>
</CardGroup>
