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

# エンジンを作る

> 別の UI プラットフォーム向けに、e2e のエンジン契約を実装します。

エンジンは、`e2e/engine` の契約を通して、`screen`、`app`、エージェントの呼び出しを UI プラットフォームにつなぎます。デスクトップアプリ、テレビ、その他のプラットフォームをテストしたい場合に実装します。`@e2e-dev/web` と `@e2e-dev/mobile` も同じ公開 `defineEngine` API を使っており、完全な実装例として参照できます。

このページでは、TypeScript でエンジンを実装し、ランナーのプロセス内で提供します。別のプロセスや言語で動かすには、[エンジンサーバー](https://e2e.com/docs/ja/engine-servers)を参照してください。

エンジンが扱うのはユーザーインターフェースだけです。受信箱、データベース、テスト API には、[`test.extend`](https://e2e.com/docs/ja/reference/test#your-own-fixtures) でフィクスチャを作ってください。

## 責任の分担

ランナーはテストとポリシーを管理します。エンジンは UI を観測し、操作します。

| 担当 | 責任範囲 |
| --- | --- |
| ランナー | 収集、ターゲット、リトライ、フック、セッション。検索とアサーションのポーリング、一致がひとつだけであることの厳密な確認、ステップ記録、タイムアウト。エージェントの計画、プロンプト、予算、ステップ履歴。ツールの認可、シークレットの解決、多層防御としてのマスキング |
| エンジン | その時点の 1 回の検索、1 回のノード読み取り。ノードの操作可否と入力の送出。プロセス、ページ、デバイスの仕組み。セキュアな観測内容の取得元でのマスキング |

`locate` は現在の一致を即座に返すか、空配列を返します。検索をリトライしたり、複数一致を拒否したりしないでください。

## エンジンの構造

`defineEngine` からハンドルを返します。設定読み込み時にマニフェストを検証し、エンジンの機能を決定します。

<Note>
型とヘルパーは `@e2e-dev/core/engine` だけからインポートしてください。内部サブパスはありません。エンジン、ランナー、[@e2e-dev/core](https://e2e.com/docs/ja/core) のプログラムが同じエラークラスを共有できるよう、`@e2e-dev/core` を peer 依存として宣言します。`e2e/engine` も同じモジュールを再エクスポートするため、それをインポートして `e2e` を peer 依存にするエンジンも、ランナー上で動きます。
</Note>

次のひな形は、プラットフォーム用の `createClient` アダプターがあることを前提としています。ノードは[セマンティックツリーのルール](#nodes-and-refs)に従う必要があります。

```ts title="src/index.ts" expandable

export function hyperdrive(options: { device: string }): EngineHandle {
  const client = createClient(options);
  let bundleId = '';
  return defineEngine({
    name: 'hyperdrive',
    version: '1.0.0',
    spiVersion: 1,
    platform: 'ios',
    validateApp(app, { targetName }) {
      if (app.bundleId === undefined) {
        throw new ConfigurationError('INVALID_CONFIG', `target "${targetName}" needs app.bundleId`);
      }
    },
    async init(info) {
      bundleId = info.app.bundleId!;
      await client.boot();
    },
    async dispose(context) { await client.shutdown({ signal: context.signal }); },
    async observe() {
      const screen = await client.snapshot();
      return {
        location: screen.title,
        // One root with a stable id: `perform(root, swipe)` is the viewport swipe.
        root: { ref: { id: 'root', revision: '' }, role: 'window', children: screen.nodes },
        viewport: screen.viewport,
      };
    },
    async locate(expression) {
      const screen = await client.snapshot();
      return resolveExpression(expression, screen.nodes);
    },
    actions: ['tap', 'fill', 'swipe'],
    async perform(ref, action) {
      switch (action.kind) {
        case 'tap': return client.tap(ref.id);
        case 'fill': return client.type(ref.id, action.value);
        case 'swipe': return client.scroll(ref.id === 'root' ? undefined : ref.id, action.direction);
      }
    },
    session: {
      async back() { await client.back(); },
      async restart() { await client.relaunch(bundleId); },
    },
  });
}
```

```ts title="e2e.config.ts"
targets: [{ name: 'phone', engine: hyperdrive({ device: 'iPhone 16' }), app: { bundleId: 'com.example.app' } }],
```

- `version` は必須です。レポートに表示され、保存済みセッションは保存時と同じバージョンでだけ復元されます。リプレイキャッシュのキーには含まれません。
- `locate` は `screen` の検索に応答します。エクスポートされている `resolveExpression` は、標準の検索ルールをセマンティックツリーに適用します。
- テスト対象アプリは、エンジンオプションではなくターゲットの `app` です。`validateApp` が設定読み込み時に検証します。`prepare` と `init` には `info.app` として渡ります。

## 対応機能

実装した任意のメソッドによって、エンジンの対応機能が決まります。存在しない機能を呼び出すと、`UNSUPPORTED_CAPABILITY` で失敗します。まずは次を実装してください。

| メンバー | 使えるようになる機能 |
| --- | --- |
| `observe(context, options?)` | エージェントの観測とリプレイキャッシュ |
| `perform(ref, action, context)` + `actions` | 宣言した種類のノード操作。`swipe` による表示領域のスクロールも含む |
| `locate(expression, context)` | `screen`、`Locator`、`expect(locator)` |
| `validateApp(app, info)` | 設定読み込み時のターゲットの `app` の検証。プラットフォームに必要なフィールドがない、または扱えないフィールドがある場合、`info.targetName` を示す `INVALID_CONFIG` を投げます。[リファレンス](https://e2e.com/docs/ja/reference/engine#app) |
| `session.{open?,back?,resize?,switchTab?,closeTab?,restart?,reset?}` | `app.open()`、`app.back()`、`app.restart()`、`app.clearState()`、およびエージェントの `navigate`、`back`、`resize_viewport`、`switch_tab`、`close_tab` |

ポインター操作、キーボード、状態の保存、アーティファクト、追加フィクスチャも任意の機能です。`actions`、`location`、`pointer`、`keyboard` には `observe` が必要です。エージェントには、宣言した種類で有効になるツールだけが渡されます。[エンジンリファレンス](https://e2e.com/docs/ja/reference/engine#capabilities)には、すべてのメンバーと、各種類が有効にするツールを記載しています。

エージェントとロケーターの操作は、どちらも `LocatorAction` として `perform` に届きます。宣言済みの操作を特定のノードで実行できない場合は、`UNSUPPORTED_CAPABILITY` を投げてください。

`session.open` には、ランナーが解決済みの URL が渡ります。`restart` または `reset` の後、ランナーは `open` を通して設定済みアドレスを開き直します。エンジンに `open` がない場合は、それらのフック内でアプリを再起動してください。

## ライフサイクル

| フック | 実行タイミング | 用途 |
| --- | --- | --- |
| `prepare` | 実行するテストがある場合、ランナープロセス内でターゲットごとに 1 回 | ランタイムのインストール。返した `env` は全ワーカーに渡る |
| `init` | ワーカーごとに、最初の試行の前に 1 回 | デバイスの起動。dispose 済みのエンジンでも動くこと |
| `startAttempt` | 各試行の前 | テスト用 UI の作成 |
| `settleAttempt` | テスト本体の後と、後処理の後 | ダイアログハンドラーなど、どのステップも待機しなかったテストコールバックのエラーを投げる |
| `endAttempt` | 各試行の後。開始に失敗した場合も含む | テスト用 UI の片付け。何度実行しても問題ないこと |
| `dispose` | ワーカー終了時。`init` が実行されなかった場合も含む | ワーカーのリソースの解放 |
| `finish` | `prepare` が実行された場合、最後のワーカーが終了した後、ターゲットごとに 1 回 | `prepare` が取得したリソースの解放 |

起動するプロセスには `info.env` を使い、進捗の報告には `info.log` を使います。各フックの引数と予算は[エンジンリファレンス](https://e2e.com/docs/ja/reference/engine#lifecycle)を参照してください。

## ノードと参照

`observe` は `SemanticNode` ツリーを返し、`locate` は一致するノードを返します。各ノードには、UI の存続期間を通して一意な ID を付けてください。ランナーがリビジョンを割り当て、参照が古くなっていないか確認します。

- ルート ID は観測間で固定します。エージェントの `scroll` と `screen.swipe()` は、`perform(root, { kind: 'swipe' })` を呼び出します。他のノードへの swipe は、そのノード内をスクロールします。
- `perform` が `{ id, revision }` を受け取ったら、ID からノードを探します。存在しなければ `NODE_STALE` を投げてください。
- `locate` の読み取り中に一致要素が UI から消えた場合は、リトライ可能な `NODE_STALE` を投げます。削除済みの要素から読んだノードを返さないでください。削除済みの要素はサイズがないため、置き換え後の要素が画面にあっても `toBeHidden` が成功してしまいます。ランナーは呼び出し元の制限時間内に再解決します。
- プラットフォームが無制限のツリーを返す可能性がある場合は、スナップショットのサイズを制限します。その制限でノードを省略したら、`truncated` を設定します。
- ノード名には、プラットフォームのアクセシブルネームを使います。
- テスト用識別子は `testId` に入れます。ドキュメントの属性、iOS の accessibility identifier、Android のリソース ID、デスクトップの automation ID などです。`testId` の検索は、このフィールドだけを照合します。

観測の任意の `location`（URL や画面タイトルなど）は、モデルとレポートに渡り、リプレイキャッシュエントリーの基準になります。

## キーボード

エージェントがフォーカスしたコントロールに入力するには、`keyboard` を実装します。`keyboard.type` は、プラットフォームのキーボード経路を通す必要があります。ブラウザなら文字ごとの `keydown`、`keypress`、`input`、`keyup`、デバイスならデバイスのキーボードを使い、人が入力したときと同じイベントをアプリに届けます。キー入力なしで値だけを設定する実装は契約に適合しません。

- 編集可能なコントロールにフォーカスがなければ、`NOT_ACTIONABLE` を投げます。
- 画面キーボードのないプラットフォームでは、`dismiss` を省略します。
- `locator.pressSequentially` は、`focus` 操作の後に同じフックを使います。

`press` では、エクスポートされた `parseKey` で `Enter` や `ControlOrMeta+a` などのキーを読み取ります。ランナーは不正な表記を `INVALID_ARGUMENT` で拒否します。有効なキーをプラットフォームに対応付け、送れないキーには `UNSUPPORTED_CAPABILITY` を投げてください。[キーの文法](https://e2e.com/docs/ja/reference/engine#keys)を参照してください。

## 画像だけで操作する UI

セマンティックツリーのない UI では、`observe` から子を持たない `root` と `pixels` を返します。`performAt` を実装し、対応する種類を `pointerActions` に宣言します。

エージェントは `tap_at` などのツールで操作します。その座標に列挙済みのノードがない場合、ランナーは座標を `performAt` に渡します。座標操作は、記録時と同じビューポートサイズでだけ再生されます。

## シークレットを扱う

シークレットの入力は、`sensitive: true` を持つ `fill` 操作としてエンジンに届きます。専用の機能フラグはありません。エージェントの `type_secret` では、ランナーが認証情報、観測結果、フィールドを確認済みです。テストの `fill(secret)` はこれらの[確認](https://e2e.com/docs/ja/reference/security#secret-fills)を省略します。入力を安全に処理するか、`UNSUPPORTED_CAPABILITY` を投げてください。その後のスクリーンショットも、[セキュアなフィールドをマスキングして](https://e2e.com/docs/ja/reference/security#screenshots-after-a-secret-fill)モデルに渡されます。

エンジンがアプリに送るパスワードなど、エンジンオプションでもシークレットを受け取れます。

1. `string | Secret` を受け取ります。`@e2e-dev/core/engine` の `isSecret` で区別します。
2. 各ハンドルをエンジンの `secrets` に列挙します。存在しないシークレット名は、設定読み込み時に拒否されます。
3. `startAttempt` 内で `context.resolveSecret(secret)` を使って値を読み取ります。

ランナーは解決した時点から値をマスキングします。エンコード済みヘッダーなど、別の形式でアプリに渡す場合は、`resolveSecret(secret, { derived })` からその形式を返すと、同じ名前でマスキングできます。保護するのはテキストだけです。エンジンがシークレットを解決したセッションでも、スクリーンショットは引き続き保持します。

## 状態も認証情報として扱う

`state` のスナップショットには Cookie やトークンが含まれる可能性があります。ランナーは実行ごとに暗号化し、実行、ターゲット、エンジン、アプリに結び付け、終了後に削除します。スナップショットを永続化、キャッシュ、ログ出力したり、エラーに含めたりしないでください。`restore` は、アプリの永続状態全体を置き換える必要があります。既存の状態へマージしてはいけません。

## エラー

[エンジンリファレンス](https://e2e.com/docs/ja/reference/engine)のコードを使って `EngineError` を投げます。

- リトライ可能にできるのは `NODE_STALE` と `FRAME_NOT_FOUND` だけです。
- 操作がすでに反映された可能性がある場合は、ランナーが繰り返さないよう `ACTION_MAY_HAVE_COMMITTED` を使います。
- `INVALID_STATE` は `APP_NOT_OPEN` になり、`UNSUPPORTED_CAPABILITY` は設定エラーになります。
- 未知のエラーはインフラ障害になります。

## エンジンが提供するフィクスチャ

エンジンは `browser` や `device` のようなフィクスチャを提供できます。各メソッドを `context.fixture` で包むと、呼び出しごとに独自のアーティファクトと失敗情報を持つ `<fixture>.<method>` ステップとして記録できます。フィクスチャは、テストと同じランナープロセス内で動きます。エンジンサーバーでは `connectEngine` から渡します。[ホスト側の処理をクライアントに置く](https://e2e.com/docs/ja/engine-servers#keep-host-work-on-the-client)を参照してください。

```ts
fixtures: {
  device: (context) => context.fixture('device', {
    async setNetwork(state: 'online' | 'offline') { await client.network(state); },
    async home() { await client.home(); },
  }, {
    setNetwork: { kind: 'resource', label: (state) => state },
    home: { kind: 'resource' },
  }),
},
```

```ts title="tests/fixtures.ts"

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

フィクスチャコンテキストは、URL ポリシーの確認、タイムアウト、予算、アーティファクト、ロケーターとアサーションのファクトリーも提供します。たとえば `expect(fixture)` 用の `expectable(target, factory)` があります。[エンジンリファレンス](https://e2e.com/docs/ja/reference/engine#contributed-fixtures)を参照してください。

## ツールセットを公開する

操作セットにないプラットフォーム固有の操作は、`defineTool` で作った[プロジェクトツール](https://e2e.com/docs/ja/tools)として公開します。`@e2e-dev/mobile/tools` と同様に `platforms` を設定し、対応するターゲットだけに表示されるようにしてください。

## パッケージ名で開けるようにする

エンジンのファクトリーを、パッケージのデフォルトエクスポートにします。すると、コーディングエージェントが設定ファイルのないディレクトリでも、そのエンジンの [MCP セッション](https://e2e.com/docs/ja/reference/mcp#without-a-config)を開けます。

```ts title="src/index.ts"
export default function kiosk(options?: KioskOptions) {
  return defineEngine({ /* ... */ });
}
```

```txt
open_session {engine: {package: "kiosk-engine", options: {lane: 2}}}
```

ファクトリーには `options` が渡ります。エージェントがパッケージ名だけを指定した場合は `undefined` です。各セッションが独自のエンジンを持てるよう、呼び出しごとに新しいエンジンを返してください。

## 動作を検証する

実装したエンジンでテストファイルを実行します。ライフサイクルの順序、観測、操作、エラー、未対応機能を確認してください。[`engine-contract.test.ts`](https://github.com/e2e-inc/e2e/blob/main/packages/e2e/tests/integration/engine-contract.test.ts) に、これらの確認例があります。

## 次のステップ

<CardGroup cols={2}>
  <Card title="エンジン契約" icon="gear" href="/reference/engine">
    `e2e/engine` のすべての型とフックを確認します。
  </Card>
  <Card title="モバイルエンジンリファレンス" icon="mobile-screen" href="/reference/mobile">
    完全なデバイスエンジンの実装と併せて読みます。
  </Card>
  <Card title="エンジンサーバー" icon="network-wired" href="/engine-servers">
    別のプロセス、マシン、言語でエンジンを動かします。
  </Card>
</CardGroup>
