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

# テストフィルター

> プルリクエストの影響を受ける可能性のあるテストだけを実行します。

`--changed-since <ref>` を指定すると、テストフィルターがその ref 以降の変更では影響を受けないテストを除外し、失敗する可能性の高いテストのファイルから開始します。デシジョンフィルターは、Jev などの[デシジョンモデル](https://e2e.com/docs/ja/decision-models)に各テストについて質問します。`main` やローカルでこのフラグを指定しなければ、すべてのテストが実行されます。

<Video>
  <video src="/images/filters.mp4" aria-label="2 つの実行を並べて表示しています。--changed-since を使う実行では、デシジョンフィルターが 27 件中 25 件を除外し、12 秒で成功します。全テストの実行は 30 秒後も続いています。" muted loop playsInline controls />

  `--changed-since origin/main` を指定すると、デシジョンフィルターが 27 件中 25 件を除外します。
</Video>

## デシジョンフィルターを追加する

<CodeGroup>
```bash npm
npm install -D @e2e-dev/decision ai
```

```bash pnpm
pnpm add -D @e2e-dev/decision ai
```

```bash bun
bun add -d @e2e-dev/decision ai
```
</CodeGroup>

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

export default {
  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
  filters: [decisionFilter({ model: gateway.decisionModel('typesafe-ai/jev') })],
} satisfies E2EConfig;
```

CI では、プルリクエストに `--changed-since` を指定し、e2e のステップに AI Gateway のキーを渡します。

```yaml title=".github/workflows/e2e.yml"
steps:
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
    with:
      fetch-depth: 0
  # ...
  - run: npx e2e run ${{ github.event_name == 'pull_request' && format('--changed-since origin/{0}', github.base_ref) || '' }}
    env:
      AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
```

フラグは `pull_request` の実行にだけ付けます。push、マージキュー、スケジュール実行では付けず、すべてのテストを実行します。`pull_request_target` には絶対に付けないでください。その実行はシークレットを保持しており、フォークの差分がモデルを誘導してテストを除外させる可能性があります。`fetch-depth: 0` により、ベースブランチとマージベースがチェックアウトに含まれます。それらがないと、実行は `INVALID_CHANGED_SINCE` で失敗します。

変更の対象は、ref と `HEAD` のマージベースから異なるすべてのファイルです。未コミットと未追跡のファイルも含みます。モデルは、コミットによる差分、テストファイル、そのセッションを保存するセットアップファイルを読みます。シークレットはマスキングされますが、シークレットプロバイダーが返す値は対象外です。未コミットや未追跡など、作業ツリーだけに変更があるファイルは、内容ではなく名前だけが渡ります。そのため、CI ステップが書いたファイルの内容はモデルに届きません。

モデルがテストとそのセットアップの両方について、影響を受ける確率を 20% 未満と評価すると、そのテストを除外します。モデルが判定できないテストは実行され、フィルターの注記に理由が表示されます。差分が 60 kB を超える、テストやセットアップファイルが大きすぎて差分と一緒に送れない、一部の呼び出しが失敗した、といった場合です。フォークからのプルリクエストでキーがない場合など、すべての呼び出しが失敗するとフィルター自体が失敗します。実行は警告を出して全テストを実行し、テストファイル、セットアップファイル、保存済みスクリーンショットが変わったものから開始します。git がない、プロジェクトがリポジトリ内にない、ref と `HEAD` に共通履歴がないなど、git が変更を取得できない場合は `INVALID_CHANGED_SINCE` で失敗します。フィルターには `ai` 7.0.134 以降が必要です。

`boolean` の質問に答える[デシジョンモデル](https://e2e.com/docs/ja/decision-models)なら使えます。たとえば TypeSafe に直接接続する Jev では、`TYPESAFE_AI_API_KEY` を設定し、`@ai-sdk/typesafe-ai` の `typeSafeAi.decisionModel('jev-latest')` を使います。`providerOptions` はすべての呼び出しに渡ります。例として `{ gateway: { zeroDataRetention: true } }` があります。

## ローカルで結果を確認する

<CodeGroup>
```bash npm
npx e2e list --changed-since origin/main
```

```bash pnpm
pnpm exec e2e list --changed-since origin/main
```

```bash bun
bunx e2e list --changed-since origin/main
```
</CodeGroup>

`e2e list` は、フィルターが除外した各テストと理由を表示します。アプリは起動しませんが、実行時と同じモデル呼び出しを行います。デシジョンフィルターが読むのはコミットによる変更だけなので、先にコミットしてください。

## 常に実行されるもの

- `--changed-since` がない場合、またはマージベース以降に変更ファイルがない場合の全テスト。
- `--last-failed` による再実行。そのため、`e2e run || e2e run --last-failed` は安全に使えます。また、`--watch` の初回以降のすべての再実行。

デシジョンフィルターは、次のテストも実行します。

- テストファイルまたはその保存済みスクリーンショットが変わったテストと、同様に変わったセットアップファイルのセッションを使うテスト。
- 読み込まれた設定ファイルが変わった場合の全テスト。ファイル名は問いません。また、プロジェクトのディレクトリ、その配下、ワークスペースルートなどの親ディレクトリで、`e2e.config.ts`（`.mts`、`.js`、`.mjs`）、Gradle の `libs.versions.toml`、ロックファイルが変わった場合も全テストを実行します。ロックファイルは `pnpm-lock.yaml`、`Podfile.lock`、`gradle.lockfile`、`Gemfile.lock`、`go.sum`、`Cargo.lock` などの名前で判別します。それ以外のファイルや兄弟プロジェクトのファイルは、モデルが判定します。

フィルターが例外を投げる、`{ exclude, relevance?, note? }` 以外を返す、または 5 分を超える場合、何も除外せず警告を表示します。次のフィルターは、渡されたすべてのテストを引き続き判定します。失敗したフィルターはスコアも付けません。ただし、[独自に実装する](#write-your-own)で説明するように、投げたエラーが `relevance` を持つ場合を除きます。5 分を超えたフィルターは破棄され、その後に投げる例外は結果に影響しません。

他の CI サービスでも、プルリクエストのビルドだけに `--changed-since origin/main` を付け、マージベースを取得できるだけの履歴を fetch してください。GitLab では[影響を受けるテストだけを実行する](https://e2e.com/docs/ja/ci/gitlab#run-only-affected-tests)を参照してください。`--shard` を使う場合、各マシンのフィルターは、そのマシンに割り当てられた部分だけを判定します。

## 失敗しそうなものから開始する

デシジョンフィルターは、残した各テストにスコアを付けます。各ターゲットは、可能性の高いテストを含むファイルから開始します。失敗を早く確認でき、特に `--max-failures` や、CI のデフォルトである 1 ワーカーの実行で時間を節約できます。

| テスト | スコア |
| --- | --- |
| テストファイル、セットアップファイル、保存済みスクリーンショットが変わった | 100% |
| その他のテスト | テストとセットアップの評価の高いほう。モデルが評価していないものは 50% とする |

- ファイルは、75% 以上、50% 以上 75% 未満、25% 以上 50% 未満、25% 未満の 4 段階で開始します。ファイル内で最も高いスコアのテストが、そのファイルの段階を決めます。
- ワーカーが複数ある場合、同じ段階では[実行時間の履歴](https://e2e.com/docs/ja/ci#cache-the-timings-history)が最も長いファイルから開始します。時間の記録がないファイルは、記録があるものより先に開始します。
- ターゲットは、最も高いスコアのファイルの段階順になり、同点なら設定順です。各ターゲットはその中のファイルを同じ順序で開始します。ターゲットのセットアップテストは、最初のテストファイルが始まる前に引き続き完了します。
- 可能性の低い長いファイルより、可能性の高い短いファイルが先に始まることがあります。そのため、複数ワーカーで最後まで実行すると、終了が遅くなる場合があります。レポートの順序は変わらず、`e2e list` に実行順は表示されません。

自作のフィルターでは、[独自に実装する](#write-your-own)のように `relevance` でスコアを付けます。

## 結果の表示

- **ターミナル**: `decision kept 7 of 77 tests, left out 70 (1 call, 17.6k tokens, $0.0007)` のように、フィルターごとに 1 行表示します。デシジョンフィルターの注記末尾には、モデル呼び出し回数、トークン数、AI Gateway のようにプロバイダーが報告する場合は費用が付きます。スコアが複数の段階に分かれる場合は、`ranked 7 of 7 tests by relevance, likeliest first` のような行が続きます。サマリーには `Left out` 行が追加されます。フィルターによって実行対象がなくなった場合、アプリを起動せずに成功します。
- **[プルリクエストコメント](https://e2e.com/docs/ja/github)と `summary.md`**: `7 passed, 70 left out by filters` という見出しと、各テストと理由を示す折りたたみ表が表示されます。
- **`junit.xml` と `report.json`**: 除外した各テストはスキップされたケースになります。レポートには `run.filters`、`run.changes` とともに `skip.filter` が入ります。[レポーター](https://e2e.com/docs/ja/reference/reporters#test-filters)を参照してください。

## デシジョンフィルターを調整する

デシジョンフィルターをラップすると、判定対象を変えられます。次の例は、`infra/` が変わると全テストを実行し、これらのテストが扱わない `apps/mobile/` を変更対象から外し、`smoke` テストは常に実行します。

```ts title="tuned-filter.ts"

const decision = decisionFilter({ model: gateway.decisionModel('typesafe-ai/jev') });

export const tuned = {
  name: 'decision',
  filter(tests, context) {
    if (context.changes.files.some((file) => file.startsWith('infra/'))) return { exclude: {}, note: 'infra/ changed' };
    const judged = tests.filter((test) => !test.tags.includes('smoke'));
    const files = context.changes.files.filter((file) => !file.startsWith('apps/mobile/'));
    if (files.length === 0) return { exclude: Object.fromEntries(judged.map((test) => [test.id, 'only apps/mobile/ changed'])) };
    return decision.filter(judged, { ...context, changes: { ...context.changes, files } });
  },
} satisfies TestFilter;
```

`filters` 内の `decisionFilter(...)` を `tuned` に置き換えます。特定のプルリクエストで全テストを実行するには、`all-tests` ラベルが付いている場合に `--changed-since` を省略します。ラベルを付けたときに実行が始まるよう、イベントに `labeled` を追加してください。

```yaml title=".github/workflows/e2e.yml"
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled]
# ...
      - run: npx e2e run ${{ github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'all-tests') && format('--changed-since origin/{0}', github.base_ref) || '' }}
```

## 独自に実装する

フィルターは `{ name, filter }` です。`filter` はテストと変更を受け取り、除外するテストを理由付きで返します。`relevance` で残りに 0〜1 のスコアを付けることもできます。次の例は、変更されたパスをテストタグに対応付け、変更が及ぶ領域のテストから開始します。

```ts title="areas-filter.ts"

/** The test tags each part of the app reaches, by path from the repository root. */
const AREAS: Readonly<Record<string, readonly string[]>> = {
  'src/todos/': ['todos'],
  'src/auth/': ['auth', 'smoke'],
  'src/checkout/': ['checkout'],
};
/** Every tag an area reaches; a test without one always runs. */
const AREA_TAGS: ReadonlySet<string> = new Set(Object.values(AREAS).flat());

export const areas = {
  name: 'areas',
  filter(tests, { changes }) {
    const reached = new Set<string>();
    let unmapped: string | undefined;
    for (const file of changes.files) {
      const area = Object.keys(AREAS).find((prefix) => file.startsWith(prefix));
      if (area === undefined) unmapped = file;
      else for (const tag of AREAS[area] ?? []) reached.add(tag);
    }
    const exclude: Record<string, string> = {};
    const relevance: Record<string, number> = {};
    for (const test of tests) {
      const tags = test.tags.filter((tag) => AREA_TAGS.has(tag));
      if (tags.some((tag) => reached.has(tag))) relevance[test.id] = 1;
      else if (tags.length > 0 && unmapped === undefined) exclude[test.id] = 'the change reaches none of its areas';
    }
    if (unmapped === undefined) return { exclude, relevance };
    return { exclude, relevance, note: `${unmapped} is in no area, so areas leaves nothing out` };
  },
} satisfies TestFilter;
```

デシジョンフィルターより前に置くと、モデルは `areas` が残したテストだけを判定します。

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

export default {
  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
  filters: [areas, decisionFilter({ model: gateway.decisionModel('typesafe-ai/jev') })],
} satisfies E2EConfig;
```

- 指定しなかったテストはすべて実行されます。また、指定したテストでも、同じ直列実行グループの別のテストが実行される場合は実行されます。
- `relevance` はテスト ID と 0〜1 の数値を受け取ります。どのフィルターも指定しないテストは 0、複数が指定するテストは最大値を使います。それ以外の値は、`exclude` と同じようにフィルターを失敗させます。
- 失敗したフィルターもスコアを付けられます。投げるエラーの `relevance` プロパティを結果と同じ形式で検証し、同じように適用します。失敗の警告は引き続き出し、何も除外しません。デシジョンフィルターもこの方法を使うため、キーのない実行でも変更の影響を受けるテストから開始します。検証に失敗したスコアは破棄され、その旨を警告します。
- 各フィルターは、前のフィルターが残したテストだけを判定します。残りがなければ呼び出されません。
- すべての呼び出しに `signal` を渡し、モデルに送る内容には `redact` を適用してください。固定値のシークレットと認証パスワード、およびそれらに含まれる 8 文字以上の連続部分を置き換えます。そのため、パスワードが `Password123!` の場合の `Password` のように、8 文字を共有するテキストもマスキングされます。シークレットプロバイダーが返す値はそのまま通過します。
- 実際の処理は `filter` の中で行ってください。ワーカーも設定を読み込みますが、`filter` を呼び出すのはランナーだけです。

型は [`TestFilter`](https://e2e.com/docs/ja/reference/config#testfilter) を参照してください。

## 次のステップ

<CardGroup cols={2}>
  <Card title="継続的インテグレーション" icon="rotate" href="/ci">
    プルリクエストを検証し、シャードに分け、失敗を再実行します。
  </Card>
  <Card title="レポーター" icon="file-lines" href="/reference/reporters">
    独自のレポーターから `run.changes`、`run.filters`、`skip.filter` を読み取ります。
  </Card>
</CardGroup>
