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

# test

> テスト、セットアップテスト、グループ、フック、オプション、フィクスチャ。

`test` はテスト、セットアップテスト、グループ、フックを宣言します。宣言はテストファイルのインポート中に同期的に実行されます。フィクスチャを追加するには `test.extend` を、登録時またはテスト本体の実行中にスキップするには `test.skip` を使います。

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

describe('checkout', { tags: ['billing'] }, () => {
  beforeEach(async ({ app }) => {
    await app.open('/checkout');
  });

  test('pays with a saved card', { retries: 2 }, async ({ screen }) => {
    await screen.getByRole('button', 'Pay').tap();
    await expect(screen.getByText('Payment received')).toBeVisible();
  });
});
```

## リファレンス

### メンバー

| メンバー | 戻り値 |
| --- | --- |
| [`test`](#test) | `TestCase` |
| [`test.skip`](#test-skip) | `TestCase \| void` |
| [`test.skipIf`](#test-skipif) | `TestRegistrar` |
| [`test.runIf`](#test-runif) | `TestRegistrar` |
| [`test.fail`](#test-fail) | `TestCase \| void` |
| [`test.only`](#test-only) | `TestCase` |
| [`test.setup`](#test-setup) | `TestCase` |
| [`test.extend`](#test-extend) | `TestAPI` |
| [`describe`](#describe) | `void` |
| [フック](#hooks) | `void` |

`describe` と 4 つのフックはトップレベルからもエクスポートされます。`test.describe`、`test.beforeEach` などと同じ関数です。`import { describe, beforeEach, test } from 'e2e'` のように使えます。

- `e2e` からインポートしたテストごとのフックには、コアのフィクスチャの型が付きます。
- `@e2e-dev/web` と `@e2e-dev/mobile` は、それぞれ `browser` または `device` フィクスチャの型を付けた `test`、`describe`、4 つのフックをエクスポートします。テストファイルは 1 つのインポート元から登録できます。
- 独自のフィクスチャで拡張した `test` では、`test.beforeEach` を通して登録したフックから、それらのフィクスチャを使えます。

モジュールの評価中以外にテスト、グループ、フックを登録すると、`COLLECTION_ERROR` をスローします。完全な宣言は[型](#types)にあります。

#### `test`

テストを 1 つ登録します。[オプション](#options)は省略できます。

```ts

test('app opens', async ({ app, browser }) => {
  await app.open();
  await expect(browser).toHaveURL('/');
});

test('checks out', { tags: ['billing'], retries: 2, timeout: 60_000 }, async ({ app }) => {
  await app.open('/checkout');
});
```

テストやグループのタイトルは、NFC 正規化後の UTF-8 で 1〜512 バイトで、NUL 文字を含められません。

| エラー | 発生条件 |
| --- | --- |
| `COLLECTION_ERROR` | 同じファイルの 2 つのテストで、グループのタイトルとテスト自身のタイトルをつないだタイトルパスが重複する場合。 |

#### `test.skip`

スキップするテストを登録するか、実行中のテストをスキップします。

```ts
test.skip('exports a PDF', async ({ app }) => {}); // at registration
test.skip(organizations.length < 2, 'a single organization'); // inside a body
test.skip('not on this tenant'); // inside a body, always
```

- デフォルトでは、スキップしたテストは終了コードに影響しません。
- オプションで収集時にスキップするには、[`skip`](#skip) を使います。
- 登録時の戻り値は `TestCase`、テスト本体内では `void` です。

無効な機能フラグなど、実行時に判明する条件には、テスト本体内で `test.skip(condition, reason)` を呼び出します。

```ts
test('switches organizations', { session: 'admin' }, async ({ app, agent }) => {
  const organizations = await listOrganizations();
  test.skip(organizations.length < 2, 'the demo tenant has a single organization');
  await app.open('/backend');
  await agent.act(`switch to the organization "${organizations[1].name}"`);
});
```

- 条件が true なら、Playwright と同じく例外をスローします。呼び出し以降の処理は実行しません。
- それまでに失敗がなければ、理由 `reason` とともに `skipped` と報告し、リトライしません。
- それ以前のステップは、実行結果のままレポートに残ります。
- 呼び出し前に `expect.soft` が失敗していれば、Playwright と同じく試行は失敗します。試行は `failed` となり、ソフトアサーションの失敗をエラーとして、スキップ理由を `skip` として保持します。通常の失敗と同じようにリトライします。
- フックとフィクスチャの後処理は引き続き実行します。
- 前提条件によるスキップは、どのステップよりも前に呼び出してください。
- 失敗した試行の後、リトライでスキップすると、テストは `skipped` になります。CLI は元のエラーとともに `Skipped After Failure` に表示します。この場合に終了コード 1 で実行を失敗させるには、[`failOnSkippedFailure: true`](https://e2e.com/docs/ja/reference/config) を設定します。デフォルトは `false` です。

| エラー | 発生条件 |
| --- | --- |
| `INVALID_ARGUMENT` | セットアップテストで呼び出した場合。他のテストがそのセッションに依存するため、セットアップテストはスキップできません。 |
| `COLLECTION_ERROR` | 条件付きの形式をテスト本体の外で呼び出した場合。 |

#### `test.skipIf`

`test(title, fn)` と同じようにテストを 1 つ登録する関数を返します。条件が真と評価される場合、そのテストをスキップします。

```ts
test.skipIf(process.platform === 'win32')('watches files', async ({ app }) => {});
test.skipIf(process.env.CI)('opens the system dialog', async ({ app }) => {});
```

- 条件はファイルの収集中、この呼び出し時に 1 回だけ読み取ります。`process.platform` や環境変数など、その時点でわかる値を使ってください。実行時にわかる条件には、本体内で [`test.skip(condition, reason)`](#test-skip) を呼び出します。
- Vitest と同じく、真と評価される値なら何でもスキップします。
- スキップされるテストは `test(title, { skip: true }, fn)` と同じです。本体は実行せず、ほかのオプションは保持します。
- [`skip`](#skip) オプションがあれば条件にかかわらずスキップし、その理由文字列を報告します。
- 直列実行グループの外では、条件が偽と評価される場合、通常の `test` と同じように登録します。
- [`test`](#test) と同じ 2 つの形式を受け付け、同じフィクスチャを持ちます。拡張した `test` でも同様です。

| エラー | 発生条件 |
| --- | --- |
| `COLLECTION_ERROR` | 条件にかかわらず、直列実行グループ内で呼び出した場合。代わりに直列実行の `describe` に [`skip`](#skip) を設定してください。 |
| `COLLECTION_ERROR` | 条件が Promise の場合。型エラーにもなります。先に await してください。 |

#### `test.runIf`

`test(title, fn)` と同じようにテストを 1 つ登録する関数を返します。条件が偽と評価される場合、そのテストをスキップします。

```ts
test.runIf(process.platform === 'linux')('reads inotify events', async ({ app }) => {});
```

`test.runIf(condition)` は `test.skipIf(!condition)` と同じです。[`test.skipIf`](#test-skipif) のルールがすべて適用されます。

#### `test.fail`

失敗を期待するテストを登録するか、実行中のテストにその印を付けます。

```ts
test.fail('shows the cart badge', async ({ app, screen }) => {}); // at registration
test.fail(platform === 'web', 'tap on a display: contents element'); // inside a body
test.fail('known gap'); // inside a body, always
test('exports a PDF', { fail: 'PDF export is broken' }, async ({ app }) => {}); // by option
```

- 呼び出し後もテスト本体は続行します。`beforeEach` フックから印を付けることもできます。
- アサーションやアクションの失敗、スローされたエラー、タイムアウトは、テストを `passed` にします。レポートには理由とエラーが残ります。
- 成功した場合は `UNEXPECTED_PASS` で `failed` になります。原因が修正されたら印を外してください。
- インフラのエラー、中断、`beforeAll` や `afterAll` の失敗、`INVALID_ARGUMENT` のような API の誤用は、引き続きテストを失敗させます。
- 期待どおりの失敗はリトライしません。予期しない成功はリトライします。
- スキップはこの印より優先されます。

| エラー | 発生条件 |
| --- | --- |
| `INVALID_ARGUMENT` | セットアップテスト、直列実行グループのメンバー、`afterEach` フック、フィクスチャの後処理で、条件が true の場合。 |
| `COLLECTION_ERROR` | 条件付きの形式をテスト本体の外で呼び出した場合、または直列実行グループ内で `fail` オプションを使った場合。 |

#### `test.only`

ローカルで実行対象を絞るテストを 1 つ登録します。

```ts
test.only('pays', async ({ app }) => {
  await app.open('/checkout');
});
```

ほかのテストは `filtered` と報告します。CI でこの指定があると、`ONLY_IN_CI` で実行が失敗します。

#### `test.setup`

保存するセッションを宣言するセットアップテストを登録します。宣言したセッションは、それぞれ必ず 1 回だけ保存する必要があります。

```ts

test.setup('authenticate', { sessions: ['member'] }, async ({ app, screen, session }) => {
  await app.open('/login');
  await screen.getByLabel('Email').fill(credentials.user('member').username);
  await screen.getByLabel('Password').fill(credentials.user('member').password);
  await screen.getByRole('button', 'Sign in').tap();
  await session.save('member');
});
```

- `test.setup` は `describe` 内ではなく、トップレベルに置きます。
- [`sessions`](#sessions) オプションで名前を宣言します。
- テストは [`session`](#session) オプションで保存済みセッションを利用します。
- セットアップの本体には、追加のフィクスチャ `session` が渡されます。

```ts
export interface SetupSession {
  /** Saves state under a setup-declared name. */
  save(name: string): Promise<void>;
}
```

| エラー | 発生条件 |
| --- | --- |
| `SESSION_CONTRACT` | 実行時に、宣言したセッションが保存されなかったか、2 回保存された場合。 |

#### `test.extend`

追加のフィクスチャの型を持つ、新しい `test` を返します。呼び出し元の `test` は変わりません。

```ts

export const test = base.extend<{ device: Device }>(); // types only
```

- 引数なしの `extend` は型だけを絞り込みます。実行時には同じ `test` を返し、エンジンが提供するフィクスチャの型を付けます。実行時のフィクスチャは、引き続きターゲットのエンジンから解決します。グローバルな `declare module` による拡張なしで、デバイス、デスクトップ、Web の API に型を付けられます。
- 定義を渡すと、独自のフィクスチャを追加します。[独自のフィクスチャ](#your-own-fixtures)を参照してください。

#### `describe`

テストのグループを宣言します。オプションは省略できます。

```ts

describe('checkout', { tags: ['smoke'], serial: true }, () => {
  test('adds an item', async ({ screen }) => {});
  test('pays', async ({ screen }) => {});
});
```

- グループは `only` を除くテストの[オプション](#options)に加え、[`serial`](#serial) を受け取ります。
- 本体は同期的に実行します。

| エラー | 発生条件 |
| --- | --- |
| `COLLECTION_ERROR` | 本体が `async` の場合。型エラーにもなります。 |
| `COLLECTION_ERROR` | 本体内に `test.setup` がある場合。 |

### フック

| フック | 実行タイミング |
| --- | --- |
| [`beforeEach`](#beforeeach) | 各テストの試行前 |
| [`afterEach`](#aftereach) | 各テストの試行後 |
| [`beforeAll`](#beforeall) | スイートのインスタンスごとに 1 回 |
| [`afterAll`](#afterall) | スコープ内の最後のテスト後 |

フックの順序はファイル内の位置ではなく、スコープの入れ子関係で決まります。テストより後に宣言したフックも、そのテストに適用されます。

#### `beforeEach`

テストの各試行を準備するフックを登録します。

```ts
test.beforeEach(async ({ app }) => {
  await app.open('/');
});
```

- 最も外側のグループから実行し、同じグループ内では宣言順に実行します。
- `beforeEach` とテスト本体は、テストのタイムアウトを共有します。
- テストのフィクスチャを受け取ります。

#### `afterEach`

テストの各試行を後処理するフックを登録します。

```ts
test.afterEach(async ({ app }) => {
  await app.screenshot('after');
});
```

- 最も内側のグループから、宣言とは逆の順序で実行します。失敗やタイムアウトの後も実行します。
- 各 `afterEach` フックには、動作するフィクスチャと独立した `cleanupTimeout` が与えられます。そのため、テスト本体がタイムアウトしても、後処理でアプリを操作できます。
- テストのフィクスチャを受け取ります。

#### `beforeAll`

スイートのインスタンスを準備するフックを登録します。そのインスタンスで初めてスコープに入るときに、1 回実行します。

```ts
beforeAll(async ({ platform }) => {
  await seedDatabase(platform);
});
```

モジュールは、リトライ、直列実行グループ、セットアップテストごとに再インポートされるため、それぞれで `beforeAll` が再び実行されます。利用できるフィクスチャは `platform` だけです。

| エラー | 発生条件 |
| --- | --- |
| `HOOK_FAILED` | フックが例外をスローした場合。スイートのテストは原因 `hook-failed` でスキップされます。直列実行グループ内では、残りの全メンバーをスキップし、リトライせずにグループを失敗させます。 |

#### `afterAll`

スイートのインスタンスを後処理するフックを登録します。その実行領域でスコープ内の最後のテストが終わると、直ちに実行します。

```ts
afterAll(async () => {
  await resetDatabase();
});
```

失敗によって破棄する実行領域では、`beforeAll` が開始したすべてのスコープで `afterAll` を実行します。利用できるフィクスチャは `platform` だけです。例外をスローすると、[`beforeAll`](#beforeall) と同じく `HOOK_FAILED` になります。

#### イベントループのブロック

フィクスチャ、`beforeEach`、テスト本体、`afterEach` の `while (true) {}` などでワーカーのイベントループをブロックすると、そのワーカーのすべてのタイマーが止まります。そのため、ワーカー自身はタイムアウトを検出できません。

- テストのタイムアウトからさらに `cleanupTimeout`（最低 5 秒）が過ぎてもワーカーが応答しなければ、ランナーが強制終了します。
- その試行は、先行する試行の後に、`TEST_TIMEOUT` を伴う `timed-out` として報告します。アーティファクトはなく、リトライしません。
- ファイル内の残りのテストは、新しいワーカーで実行します。直列実行グループでは、その後のメンバーをスキップします。
- `beforeAll` または `afterAll` がブロックした場合は、実行全体が停止したままになります。

<Note>
テスト開始時にデバッガーが接続されているワーカー（エディターの自動接続や `NODE_OPTIONS=--inspect=0` など）は、この仕組みでは強制終了しません。ブレークポイントで停止したままにできるためです。インライン設定やメモリー上のテストによるプログラムからの実行は、ランナー自身のプロセスで動き、強制終了できるワーカーがありません。イベントループをブロックすると、そのまま停止します。
</Note>

### オプション

| オプション | 型 | デフォルト |
| --- | --- | --- |
| [`timeout`](#timeout) | `number` | `config.timeout` |
| [`retries`](#retries) | `number` | `config.retries` |
| [`tags`](#tags) | `readonly string[]` | - |
| [`skip`](#skip) | `boolean \| string` | - |
| [`fail`](#fail) | `boolean \| string` | - |
| [`only`](#only) | `boolean` | - |
| [`platforms`](#platforms) | `readonly string[]` | - |
| [`requires`](#requires) | `readonly Capability[]` | - |
| [`session`](#session) | `string` | - |
| [`agentContext`](#agentcontext) | `string` | - |
| [`agent`](#agent) | `string \| readonly string[]` | 実行全体のエージェント |
| [`trace`](#trace) | `RecordingMode` | 実行全体の設定 |
| [`video`](#video) | `RecordingMode` | 実行全体の設定 |
| [`serial`](#serial) | `boolean` | - |
| [`sessions`](#sessions) | `readonly string[]` | 必須 |

`test` は `serial` と `sessions` 以外を受け付けます。`describe` は `only`、`fail`、`sessions` 以外を受け付けます。`test.setup` では `sessions` が必須で、`session`、`only`、`skip`、`fail` は受け付けません。

優先順位は、テスト、最も近いグループ、外側のグループ、設定、組み込みのデフォルト値の順です。[直列実行グループ](#serial)内では、グループの `retries`、`trace`、`video` を適用します。

| エラー | 発生条件 |
| --- | --- |
| `COLLECTION_ERROR` | その呼び出しが受け付けないオプションキーがある場合（`{ timout: 1000 }`）。タイプミスと思われる場合は最も近い既知のキーを、それ以外は受け付けるすべてのキーをエラーに表示します。 |

#### `timeout`

試行の期限までの時間をミリ秒で指定します。最も内側の指定を優先します。

```ts
test('imports a large file', { timeout: 300_000 }, async ({ app }) => {}); // default: config.timeout
```

`timeout` は正の安全な整数で、最大 2147483647（約 24 日）です。

#### `retries`

失敗したテストをリトライする回数です。

```ts
test('checks out', { retries: 2 }, async ({ app }) => {}); // default: config.retries
```

0〜10 の整数で指定します。

#### `tags`

`--tag` で選択するためのタグです。すべての階層のタグを結合します。

```ts
describe('checkout', { tags: ['billing', 'smoke'] }, () => {});
```

タグ名は重複できず、空にもできません。カンマや前後の空白は使えません。

#### `skip`

収集時にテストをスキップします。文字列は理由になります。どれかの階層に真と評価される値があればスキップします。実行時の `test.skip` を含むスキップ理由は、報告前にシークレットの伏せ字化とサニタイズを行い、UTF-8 で 8,192 バイトに制限します。

```ts
test('exports a PDF', { skip: 'PDF export is off on staging' }, async ({ app }) => {});
```

#### `fail`

テストの失敗を期待します。[`test.fail`](#test-fail) を参照してください。文字列は理由になります。直列実行グループ内では使えません。

```ts
test('exports a PDF', { fail: 'PDF export is broken' }, async ({ app }) => {});
```

#### `only`

ローカルでこのテストに実行対象を絞ります。CI では `ONLY_IN_CI` で拒否します。

```ts
test('pays', { only: true }, async ({ app }) => {});
```

#### `platforms`

テストを実行するプラットフォームです。それ以外のターゲットではスキップします。最も内側の指定を優先します。

```ts
test('uses Face ID', { platforms: ['ios'] }, async ({ app }) => {});
```

#### `requires`

ターゲットに必要な機能です。1 つでも欠けていれば、選択時にテストをスキップします。最も内側の指定を優先します。

```ts
test('onboarding asks for the camera', { requires: ['native-app'] }, async ({ app, agent }) => {
  await app.open();
  await agent.assert('The app asks for camera access');
});
```

指定できる値は次のとおりです。

- ターゲットのエンジンが提供するハーネスの機能: `observation`、`actions`、`location`、`pointer`、`keyboard`、`computed-style`、`state`、`artifacts`。
- 提供するフィクスチャごとの値: `browser`、`device`。[エンジンの契約](https://e2e.com/docs/ja/reference/engine#engine)を参照してください。
- ターゲットが宣言するアプリの種類: `app.url` なら `browser`、`app.bundleId` または `app.appPath` なら `native-app`。

#### `session`

セットアップテストが保存したセッションです。テスト本体の実行前に復元します。

```ts
test('sees the dashboard', { session: 'member' }, async ({ app }) => {});
```

[`test.setup`](#test-setup) を参照してください。

#### `agentContext`

エージェントのステップに渡す追加のコンテキストです。各階層の値を、最も外側から順に連結します。

```ts
describe('pricing', { agentContext: 'Prices are shown in EUR.' }, () => {});
```

#### `agent`

このテストまたはグループで使う設定済みエージェント（`agents.<name>`）です。実行全体のエージェントの代わりに使います。

```ts
test('checks out', { agent: ['fast', 'smart'] }, async ({ agent }) => {}); // one result per agent
```

- リストを指定すると、各エージェントでテストを 1 回ずつ実行し、それぞれを 1 件の結果にします。
- 最も内側の指定を優先します。各呼び出し自身の `agent` オプションは、さらに優先されます。
- `--agent` はリストを両方に含まれる名前に絞ります。フラグに含まれない名前への固定指定を、別の名前で上書きすることはありません。
- セットアップテストはターゲットごとに 1 回実行するため、指定できるエージェントは最大 1 つです。

| エラー | 発生条件 |
| --- | --- |
| `COLLECTION_ERROR` | テスト開始前の選択時に、`agents` に定義のない名前が見つかった場合。 |

#### `trace`

実行全体の設定に代えて、このテストのトレースページを保持するかどうかを指定します。

```ts
test('checkout', { trace: 'retain-on-failure' }, async ({ agent }) => {});
```

- 設定の `trace` と同じ[記録モード](https://e2e.com/docs/ja/reference/config#recording)を受け付けます。`off`、`on`、`retain-on-failure`、`on-first-retry`、`on-all-retries` です。
- テストまたはグループの値は、`--trace`、ターゲット、設定ファイルの値より優先されます。全体では記録しない実行でも 1 テストだけ記録でき、全体を記録する実行で 1 テストだけ除外することもできます。

#### `video`

実行全体の設定に代えて、このテストのどの試行で動画を記録するかを指定します。

```ts
test('checkout', { video: 'on' }, async ({ agent }) => {
  await agent.act('Buy the first product in the catalog');
});
```

- `trace` や設定の `video` と同じ[記録モード](https://e2e.com/docs/ja/reference/config#recording)を受け付けます。
- テストまたはグループの値は、`--video`、ターゲット、設定ファイルの値より優先されます。

| エラー | 発生条件 |
| --- | --- |
| `UNSUPPORTED_ARTIFACT` | いずれかの試行を録画するモードで、ターゲットのエンジンが録画に対応しない場合。テスト開始前に、該当テスト名を示して失敗します。 |

#### `serial`

`describe` 専用です。アプリの状態を共有し、グループ全体を順序のある 1 つのリトライ単位として実行します。

```ts
describe('checkout', { serial: true }, () => {
  test('adds an item', async ({ screen }) => {});
  test('pays', async ({ screen }) => {});
});
```

- シークレットの状態も共有します。1 つのメンバーが解決した値は、そのグループの試行の残りでも伏せ字の対象になります。リトライでは新しい状態から始めます。
- メンバーには、直列実行の `describe` またはそれを囲むグループの `trace` と `video` を適用します。動画はグループの試行ごとに 1 本記録します。
- ファイルの読み込みやセッションの起動に失敗し、グループの試行が始まらないこともあります。その場合、最初のメンバーをそのエラーで失敗にし、残りは原因 `serial-predecessor-failed` でスキップします。起動中に実行が中断された場合は、代わりに全メンバーをスキップします。
- リトライが中断された場合や、メンバーの実行まで到達しなかった場合、各メンバーは最後に実行された試行の判定と所要時間を保持します。
- 終了コードは、ほかのテストと同じくエラーの分類に従います。

| エラー | 発生条件 |
| --- | --- |
| `COLLECTION_ERROR` | メンバーが `retries`、`trace`、`video`、`session`、`platforms`、`requires`、`skip`、`only`、または入れ子の `serial` を指定した場合。 |
| `COLLECTION_ERROR` | メンバーが `test.skipIf` または `test.runIf` で登録された場合。 |

#### `sessions`

`test.setup` 専用です。セットアップテストが保存しなければならないセッション名を指定します。

```ts
test.setup('authenticate', { sessions: ['member', 'admin'] }, async ({ session }) => {});
```

静的な空でない配列で、名前は重複できません。各名前は `/^[A-Za-z0-9_.-]{1,128}$/` に一致する必要があります。[`test.setup`](#test-setup) を参照してください。

### フィクスチャ

| フィクスチャ | 型 |
| --- | --- |
| [`agent`](https://e2e.com/docs/ja/reference/agent) | `Agent` |
| [`app`](https://e2e.com/docs/ja/reference/app) | `App` |
| [`screen`](https://e2e.com/docs/ja/reference/screen) | `Screen` |
| `platform` | `string` |
| [`session`](#test-setup) | `SetupSession` |

`agent`、`app`、`screen` はテスト本体、`beforeEach`、`afterEach` に渡されます。`platform` はすべてのフックにも渡され、`session` は `test.setup` の本体だけに渡されます。各フィクスチャの説明は [`TestFixtures`](#testfixtures) にあります。

それ以外は、ターゲットのエンジンが提供するフィクスチャか、[独自のフィクスチャ](#your-own-fixtures)です。`@e2e-dev/web` は [`browser`](https://e2e.com/docs/ja/reference/web)、デバイスエンジンは `device` を提供します。

| エラー | 発生条件 |
| --- | --- |
| `UNSUPPORTED_CAPABILITY` | エンジンが提供しないフィクスチャをテストが使おうとした場合。`requires: ['browser']` を宣言すれば、選択時のスキップにできます。 |

<Note>
上記のフィクスチャは遅延取得します。パラメーターリストで分割代入すると、テスト本体の最初の文より前に取得します。[独自のフィクスチャ](#your-own-fixtures)は遅延取得ではありません。
</Note>

#### 独自のフィクスチャ

`test.extend(fixtures)` は、各テストの前に準備し、失敗した場合も含めて終了後に後処理するリソースを定義します。各フィクスチャ関数では、`await use(value)` より前でリソースを準備します。テストに `value` が渡り、`use` より後のコードで後処理します。スイート全体の例を含むガイドは、[フィクスチャの作成](https://e2e.com/docs/ja/fixtures)を参照してください。

```ts

export const test = base.extend<{ workspace: Workspace }>({
  workspace: async ({ browser }, use) => {
    const workspace = await createWorkspace();
    await signIn(browser, workspace);
    await use(workspace); // the hooks and the body run here
    await workspace.cleanup(); // teardown, after the body even when it failed
  },
});

test('renames the workspace', async ({ workspace, screen }) => {
  await screen.getByLabel('Name').fill(`${workspace.name} (renamed)`);
});
```

定義の型から参照できるのは、拡張元の `test` のフィクスチャです。同じ呼び出し内のほかのフィクスチャではありません。別のフィクスチャに依存する場合は、2 回目の `extend` をつなげます。`base.extend({ a }).extend({ b })` なら、`b` はすでに `a` を持つフィクスチャオブジェクトを受け取ります。

各試行では、次の順に動作します。

1. テストの登録に使った `extend` チェーンの各定義を、エンジンのフィクスチャの後に宣言順で実行し、それぞれ `use` の呼び出しまで進めます。テストがそのフィクスチャを指定しなくても実行します。ページを開いたりアプリの状態を変えたりするフィクスチャは、その `test` のすべてのテストで同じ操作を行います。そのため、準備内容が異なるテストは別々の `extend` チェーンから登録します。準備時間はテストの `timeout` に含まれます。失敗は、どの `beforeEach` フックよりも前に、フェーズ `beforeEach` として報告します。
2. 同じフィクスチャオブジェクトで `beforeEach` フック、テスト本体、`afterEach` フックを順に実行します。フィクスチャ群はそのテスト自身のチェーンで決まります。たとえば `base` から登録したテストを囲むフックが `workspace` を読もうとすると、`UNSUPPORTED_CAPABILITY` で失敗します。
3. 最後の `afterEach` の後、テスト本体の成功・失敗にかかわらず、逆順に後処理を実行します。それぞれに独立した `cleanupTimeout` があります。後処理のエラーは、それまで成功していた試行をフェーズ `afterEach` で失敗させます。本体が失敗済みなら `secondaryErrors` に加えます。

| 誤り | 失敗のタイミングと内容 |
| --- | --- |
| 関数を値に持つプレーンオブジェクトではない定義、空の名前、コアの名前（`agent`、`app`、`screen`、`platform`、`session`）、またはチェーン内の前の `extend` で定義済みの名前 | インポート時に、フィクスチャ名を示す `COLLECTION_ERROR` |
| ターゲットのエンジンが提供する名前（Playwright ターゲットの `browser`） | 試行の `beforeEach` で `TEST_SETUP_FAILED` |
| `use` を呼ばずに戻る定義 | 試行の `beforeEach` で `TEST_SETUP_FAILED` |
| `use` を 2 回呼ぶ定義 | 試行の後処理で `TEST_SETUP_FAILED` |
| `use` の前に例外をスローする定義 | 試行の `beforeEach` で、そのエラー |
| `use` の後に例外をスローする定義 | 試行の `afterEach` で、そのエラー |

<Note>
テスト本体やフックが `timeout` に達した場合、処理自体はキャンセルせず、完了を待たなくなります。そのため、まだ動いている間に後処理が始まることがあります。このように待機を打ち切られた準備処理が後から `use` に到達すると、直ちに解決します。その後処理は実行全体から切り離して動くため、確保したリソースは解放されます。打ち切られた準備処理やフックが後から完了しても、後続のフィクスチャ、フック、テスト本体は開始しません。
</Note>

## 型

### `TestAPI`

```ts
/** The two call forms of `test`, shared with what `test.skipIf` and `test.runIf` return. */
export interface TestRegistrar<Fixtures = TestFixtures> {
  /** Registers one test synchronously during module evaluation. */
  (title: string, fn: TestFn<Fixtures>): TestCase;
  /** Registers one configured test synchronously during module evaluation. */
  (title: string, options: TestOptions, fn: TestFn<Fixtures>): TestCase;
}

export interface TestAPI<Fixtures = TestFixtures> extends TestRegistrar<Fixtures> {
  /** Registers one skipped test. */
  skip(title: string, fn: TestFn<Fixtures>): TestCase;
  /**
   * Inside a running test: skips it when `condition` is true (or always,
   * with no condition) by throwing, so nothing after the call runs. The
   * attempt is reported `skipped` with `reason`; steps that already ran stay
   * in the report without deciding the status, and teardown still runs. A
   * setup test cannot skip: its sessions are owed.
   * Outside a test body this form is `COLLECTION_ERROR`; use the `skip`
   * option to skip at collection.
   */
  skip(condition: boolean, reason?: string): void;
  skip(reason?: string): void;
  /**
   * Returns a function that registers one test, like `test(title, fn)`:
   * skipped when `condition` is truthy, as if it had the `skip` option. The
   * condition is read once, at this call, so it can only depend on what is
   * known while the file is collected (`process.platform`, `process.env.CI`):
   *
   *   test.skipIf(process.platform === 'win32')('file watcher', async () => {});
   *
   * A `skip` option skips the test whatever the condition. A serial group
   * rejects the call: set `skip` on the serial `describe` instead. A Promise
   * condition also fails the call: await it first.
   */
  skipIf<Condition>(condition: SynchronousCondition<Condition>): TestRegistrar<Fixtures>;
  /**
   * Returns a function that registers one test, like `test(title, fn)`:
   * skipped when `condition` is falsy, `test.skipIf(!condition)`.
   */
  runIf<Condition>(condition: SynchronousCondition<Condition>): TestRegistrar<Fixtures>;
  /** Registers one test that is expected to fail. */
  fail(title: string, fn: TestFn<Fixtures>): TestCase;
  /**
   * Inside a running test: marks it expected to fail when `condition` is
   * true (or always, with no condition). The body keeps running. A test
   * failure then passes the test, keeping the error and `reason` in the
   * report; a pass fails it with `UNEXPECTED_PASS`. Infrastructure failures
   * and interrupts are not covered. A setup test or a serial group member
   * cannot be marked. Outside a test body this form is `COLLECTION_ERROR`;
   * use `test.fail(title, fn)` or the `fail` option to mark at collection.
   */
  fail(condition: boolean, reason?: string): void;
  fail(reason?: string): void;
  /** Registers one focused local test. CI rejects focused tests. */
  only(title: string, fn: TestFn<Fixtures>): TestCase;
  /** Registers one setup test with statically declared session outputs. */
  setup(title: string, options: SetupOptions, fn: SetupFn<Fixtures>): TestCase;
  /**
   * Returns the same runtime `test`, typed with an engine's contributed
   * fixtures. A pure type refinement, the fixtures still resolve from the
   * target's engine at runtime, so a project types its device/desktop/web
   * surface without a global `declare module` augmentation:
   *
   *   export const test = base.extend<{ device: Device }>();
   */
  extend<Extra>(): TestAPI<Fixtures & Extra>;
  /**
   * Returns a new `test` whose registrations carry these fixture
   * definitions on top of the ones it already had. Each attempt sets them up
   * in declaration order after the engine's fixtures, runs the hooks and the
   * body with them, and tears them down in reverse order after `afterEach`:
   *
   *   export const test = base.extend<{ workspace: Workspace }>({
   *     workspace: async ({ browser }, use) => {
   *       const workspace = await createWorkspace();
   *       await use(workspace);
   *       await workspace.cleanup();
   *     },
   *   });
   */
  extend<Extra>(fixtures: FixtureDefinitions<Fixtures, Extra>): TestAPI<Fixtures & Extra>;
  /** Declares a group synchronously. */
  describe<Result>(title: string, body: SynchronousBody<Result>): void;
  /** Declares a configured group synchronously. */
  describe<Result>(
    title: string,
    options: DescribeOptions,
    body: SynchronousBody<Result>,
  ): void;
  /** Registers a test-attempt setup hook. */
  beforeEach(fn: TestHookFn<Fixtures>): void;
  /** Registers a test-attempt teardown hook. */
  afterEach(fn: TestHookFn<Fixtures>): void;
  /** Registers a suite-instance setup hook. */
  beforeAll(fn: SuiteHookFn): void;
  /** Registers a suite-instance teardown hook. */
  afterAll(fn: SuiteHookFn): void;
}

export const test: TestAPI;
export const describe: TestAPI['describe'];
export const beforeEach: TestAPI['beforeEach'];
export const afterEach: TestAPI['afterEach'];
export const beforeAll: TestAPI['beforeAll'];
export const afterAll: TestAPI['afterAll'];
```

### `TestOptions`

```ts
export interface TestOptions {
  /** Attempt deadline in milliseconds; defaults to `config.timeout`. Innermost wins. */
  timeout?: number;
  /** Retries, 0 through 10; defaults to `config.retries`. Inside a serial group the group's value applies. */
  retries?: number;
  /** Tags for `--tag`: distinct names, none blank, with no comma and no leading or trailing whitespace; every layer's tags are unioned. */
  tags?: readonly string[];
  /** Skips the test; a string is the reason. Any truthy layer skips. */
  skip?: boolean | string;
  /**
   * Expects the test to fail; a string is the reason. A test failure then
   * passes it, and a pass fails it with `UNEXPECTED_PASS`. Not allowed inside
   * a serial group.
   */
  fail?: boolean | string;
  /** Focuses the test locally. CI rejects it with `ONLY_IN_CI`. */
  only?: boolean;
  /** Platforms the test runs on; other targets skip it. Innermost wins. */
  platforms?: readonly string[];
  /** Capabilities the target must have; otherwise the test is skipped at selection. Innermost wins. */
  requires?: readonly Capability[];
  /** Session a setup test saved, restored before the body runs. */
  session?: string;
  /** Extra context for agent steps; layers are concatenated outermost first. */
  agentContext?: string;
  /**
   * The configured agent (`agents.<name>`) this test or group runs with, in
   * place of the run's agents. A list runs the test once per agent named, as
   * one result each. Innermost wins; a call's own `agent` option wins over
   * it. `--agent` narrows a list to the names both name and never overrides
   * a pin the flag does not name.
   */
  agent?: string | readonly string[];
  /**
   * Which of the test's attempts keep a trace, in place of the run's: the
   * same modes as the config's `trace`. Innermost wins, over `--trace` too;
   * inside a serial group the group's value applies, since the group runs as
   * one unit.
   */
  trace?: RecordingMode;
  /**
   * Which of the test's attempts record a video, in place of the run's:
   * the same modes as the config's `video`. Innermost wins, over `--video`
   * too; inside a serial group the group's value applies, since the group
   * records as one unit. A mode set here is required of the target's engine.
   */
  video?: RecordingMode;
}

export interface DescribeOptions extends Omit<TestOptions, 'only' | 'fail'> {
  /** Runs the group as one ordered retry unit with shared app state. Nesting one serial group in another is a `COLLECTION_ERROR`. */
  serial?: boolean;
}

export interface SetupOptions extends Omit<TestOptions, 'session' | 'only' | 'skip' | 'fail' | 'agent'> {
  /** Session names this setup test MUST save. */
  sessions: readonly string[];
  /** A setup test runs once per target, so it pins at most one agent. */
  agent?: string;
}
```

### `TestFixtures`

```ts
export interface TestFixtures {
  /** Agent steps. Acquiring the built-in agent without a configured model is `MODEL_UNAVAILABLE`. */
  readonly agent: Agent;
  /** App lifecycle: open, restart, clear state, back, screenshot, recording. */
  readonly app: App;
  /** Semantic queries and the actions on their matches. */
  readonly screen: Screen;
  /** The target's platform label: `web`, `ios`, `android`, or an engine's own string. */
  readonly platform: string;
}

export interface SetupFixtures extends TestFixtures {
  /** Saves the sessions the setup test declared. */
  readonly session: SetupSession;
}

export interface SuiteFixtures {
  /** The target's platform label: `web`, `ios`, `android`, or an engine's own string. */
  readonly platform: string;
}
```

### `FixtureDefinitions`

```ts
/**
 * Defines one fixture: everything before `await use(value)` is its setup,
 * everything after is its teardown. The body, its hooks, and later fixtures
 * run while `use` is pending; it resolves once they are done, whether or not
 * the body failed.
 */
export type FixtureFn<Fixtures, Value> = (
  fixtures: Fixtures,
  use: (value: Value) => Promise<void>,
) => Promise<void>;

/**
 * One definition per fixture `test.extend()` adds. A definition sees the
 * fixtures of the `test` it extends, not its siblings: a fixture that needs
 * another one goes in a chained `extend()`. A name the base already has is a
 * type error (and a `COLLECTION_ERROR` at runtime).
 */
export type FixtureDefinitions<Base, Extra> = {
  readonly [K in keyof Extra]: K extends keyof Base ? never : FixtureFn<Base, Extra[K]>;
};
```

### 関数の型

```ts
/** A test body. */
export type TestFn<Fixtures = TestFixtures> = (fixtures: Fixtures) => void | Promise<void>;

/** A setup test body; `session.save` is the extra fixture. */
export type SetupFn<Fixtures = TestFixtures> = (
  fixtures: Fixtures & SetupFixtures,
) => void | Promise<void>;

/** A `beforeEach` or `afterEach` body. */
export type TestHookFn<Fixtures = TestFixtures> = (fixtures: Fixtures) => void | Promise<void>;

/** A `beforeAll` or `afterAll` body. */
export type SuiteHookFn = (fixtures: SuiteFixtures) => void | Promise<void>;

/** A `describe` body. An async body is a type error. */
export type SynchronousBody<Result> = Extract<Result, PromiseLike<unknown>> extends never
  ? () => Result
  : never;

/** A `test.skipIf` or `test.runIf` condition. A Promise is a type error. */
export type SynchronousCondition<Condition> = Extract<Condition, PromiseLike<unknown>> extends never
  ? Condition
  : never;

/** Opaque handle of a registered test. */
export interface TestCase {
  readonly [testCaseBrand]: true;
}
```
