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

# 基本概念

> ゴール、アサーション、ロケーターと、それらを使ったテストの構成・実行方法。

テストは 3 種類のステップを組み合わせます。

| ステップ | API | モデル呼び出し |
| --- | --- | --- |
| [ゴール](#goals) | `agent.act` | あり。ただし [キャッシュ](https://e2e.com/docs/ja/cache) からリプレイする場合を除きます |
| [アサーション](#assertions) | `agent.assert`, `agent.waitFor`, `agent.extract` | あり |
| [ロケーター](#locators) | `screen` と `expect` | なし |

[カスタムエグゼキューター](https://e2e.com/docs/ja/executors) を使う場合、`act` と `assert` にモデルは不要です。

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

describe('todos', () => {
  test('the Done filter shows only completed todos', async ({ app, agent, screen }) => {
    await app.open('/todos');
    await agent.act('add todos "Buy milk" and "Walk the dog"');
    await agent.act('complete "Buy milk"');
    await agent.waitFor('"Buy milk" is completed and "Walk the dog" is open');

    await screen.getByRole('tab', 'Done').tap();

    await expect(screen.getByTestId('todo')).toHaveCount(1);
    await agent.assert('the only todo listed is "Buy milk"');
  });
});
```

各テストは、初期状態の準備、対象の操作、結果の検証という 3 つのブロックで 1 つの動作を確認します。

エージェントと screen の各呼び出し、および `expect.poll` には await を付けてください。
ステップの実行中にテストが return すると、`STEP_NOT_AWAITED` で失敗します。

## ゴール

`agent.act` は 1 つのゴールを受け取り、必要な操作を実行します。
ゴールを達成すると戻り、失敗するとエラーをスローします。

```ts
await agent.act('complete checkout with the test card');
await agent.act('invite {email} as an editor', { params: { email: 'ada@example.test' } });
```

各ゴールは、1 回のチェックで確認できる 1 つの結果に絞ってください。
指示の 2 つの部分がそれぞれ確認すべき状態を生むなら、2 つのゴールに分けます。
1 つのテストに複数のゴールを含められます。

```ts title="Bad: three goals in one call, no check between them"
await agent.act('open the Pro plan, set the seats to {seats}, and check out', {
  params: { seats: 3 },
});
```

```ts title="Good: one atomic goal per call, arrange, act, assert"
test('checks out the Pro plan', async ({ app, agent, screen }) => {
  await app.open('/plans');
  await agent.act('open the Pro plan');
  await agent.act('set the seats to {seats}', { params: { seats: 3 } });
  await agent.waitFor('the cart shows the Pro plan with 3 seats');

  await agent.act('check out');

  await expect(screen.getByText('Order confirmed')).toBeVisible();
});
```

まず準備のゴールを実行し、目的の状態になるまで待ちます。次にテスト対象のゴールを実行し、
最後に結果を検証します。こうすると、失敗したゴールを特定できます。
各ゴールはそれぞれの記録からリプレイされ、モデル呼び出しと操作の
[予算](https://e2e.com/docs/ja/reference/agent#budgets) も個別に割り当てられます。
1 つの結果に至るための操作は、個別のゴールではありません。
たとえば、コントロールのある画面やメニューを開く、そこまでスクロールする、
バナーを閉じる、1 つのフォームのフィールドに入力する、といった操作です。

- ゴールの順序は自分で決めます。操作はエージェントが選びます。
- テストの最後に `expect` で結果を確認します。[リプレイキャッシュ](https://e2e.com/docs/ja/cache) がゴールを記録するのは、
  後続のチェックまたは待機が成功した後だけです。
- 画面に表示されている言葉を使います。
- テストデータは `params` で渡します。パスワードには `Secret` を使います。
  モデルにその値がテキストとして渡されることはありません。[認証](https://e2e.com/docs/ja/authentication) を参照してください。
- 実行ごとに変わる値には `unique()` を使うと、
  [キャッシュからステップをリプレイできます](https://e2e.com/docs/ja/cache#what-must-match)。

```ts

const email = `ada+${Date.now()}@example.test`;
await agent.act('sign up with email {email}', { params: { email: unique(email) } });
```

`act` は必要に応じてスクリーンショットを取得します。
一部のエンジンでは、画像上の位置を指定してタップや入力ができます。

ゴールが失敗したら、レポートを読み、指示を具体的にしてください。
多くのゴールで使う言葉は、エージェントの [`context`](https://e2e.com/docs/ja/agents) に記述します。

## アサーション

アサーションは画面を判定します。モデルには、判定する文、現在の画面のマスキング済みテキストスナップショット、
その場所、エージェントのコンテキストが渡されます。
それ以前のステップや `act` の要約は渡されません。

- `agent.assert` は現在の画面を調べます。文が偽なら `ASSERTION_FAILED` で失敗します。
  根拠が不十分なら `ASSERTION_INCONCLUSIVE` で失敗します。
- `agent.waitFor` は条件が真になるまで待ちます。画面またはその場所が変わった場合にだけモデルを呼び出します。
- `agent.extract` は、Zod などの [Standard Schema](https://standardschema.dev) の型に沿って
  画面からデータを読み取ります。

```ts

await agent.assert('the dashboard shows a trial badge');
await agent.waitFor('a download link appears', { timeout: 120_000 });
await agent.assert('the chart trends upward', { vision: true });

const data = await agent.extract('every todo title', {
  schema: z.object({ titles: z.array(z.string()) }),
});
expect(data.titles).toContain('Buy milk');
```

モデルが書いたテキストは、文全体の一致ではなく意味を確認してください。
正確な文字列が重要な場合は、[ロケーター](#locators) を使います。

グラフやレイアウトなどを視覚的に確認するには、`vision: true` を追加します。
スクリーンショットだけで判定するには、`vision: 'only'` を使います。
画像は入力トークンを増やします。[agent リファレンス](https://e2e.com/docs/ja/reference/agent#vision) を参照してください。

## ロケーター

ロケーターは、モデルを呼び出さずに既知のコントロールを見つけます。
正確な操作や値がわかっている場合に使います。

```ts
// Role and name first, label second, test ID last.
await screen.getByRole('button', 'Sign in').tap();
await screen.getByLabel('Email').fill('ada@example.test');

// Scope into a row.
const row = screen.getByRole('listitem').filter({ hasText: 'Design review' });
await row.getByRole('button', 'Archive').tap();

// Gestures and coordinates.
await screen.swipe({ direction: 'up' });
await screen.getByRole('image', 'Seat map').tap({ position: { x: 120, y: 48 } });

// Assertions retry until they pass or time out.
await expect(screen.getByRole('status')).toHaveText('2 remaining');
```

- 操作、読み取り、単一ノードのアサーションは、クエリが複数のノードに一致すると失敗します。
  `.filter()`、`.first()`、`.nth()` を使って 1 つのノードに絞ってください。
- `textContent()` などの直接読み取りは、一致するノードを待ってから 1 回だけ読み取ります。
  値を得るためのリトライはしません。

[screen リファレンス](https://e2e.com/docs/ja/reference/screen) と
[expect リファレンス](https://e2e.com/docs/ja/reference/expect#locator-matchers) を参照してください。
ルート、Cookie、ダイアログ、ダウンロードについては、[ブラウザの操作](https://e2e.com/docs/ja/browser) を参照してください。

## テストを整理する

```ts

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

  test('upgrades', { retries: 2, timeout: 60_000 }, async ({ agent }) => {
    await agent.act('upgrade to Pro');
  });
});

test('needs two organizations', async ({ app }) => {
  test.skip((await countOrganizations()) < 2, 'nothing to switch to');
  await app.open('/organizations');
});
```

- 各テストは独立した試行で実行されます。確認する画面の近くから始めると、
  毎回そこまで移動するクリックを省けます。データはフィクスチャやフックで作成します。
  ブラウザでは [保存済みセッション](https://e2e.com/docs/ja/authentication) を復元し、パスで画面を開きます。
  デバイスでは [ディープリンク](https://e2e.com/docs/ja/mobile#the-device-fixture) を開きます。
- `test.skip(condition, reason)` は、条件が真ならテストを `skipped` として停止します。
- 複数のテストにまたがるフローでは、グループに `{ serial: true }` を設定します。
  テストは 1 つのワーカーで順番に実行され、まとめてリトライされます。
- セットアップとクリーンアップには `test.extend` を使います。[フィクスチャの作成](https://e2e.com/docs/ja/fixtures) を参照してください。
- `browser` または `device` フィクスチャに型を付けるには、
  `@e2e-dev/web` または `@e2e-dev/mobile` から `test` をインポートします。

すべてのオプションは [test リファレンス](https://e2e.com/docs/ja/reference/test) にあります。

## 1 つのテストを実行する

<CodeGroup>
```bash npm
npx e2e run tests/signup.e2e.ts:12   # the test at line 12
npx e2e run --grep checkout          # tests with a matching title
npx e2e run --target web             # one target
```

```bash pnpm
pnpm exec e2e run tests/signup.e2e.ts:12   # the test at line 12
pnpm exec e2e run --grep checkout          # tests with a matching title
pnpm exec e2e run --target web             # one target
```

```bash bun
bunx e2e run tests/signup.e2e.ts:12   # the test at line 12
bunx e2e run --grep checkout          # tests with a matching title
bunx e2e run --target web             # one target
```
</CodeGroup>

すべてのフラグは [CLI リファレンス](https://e2e.com/docs/ja/reference/cli#e2e-run) にあります。

## 次のステップ

<CardGroup cols={2}>
  <Card title="キャッシュ" icon="box-archive" href="/cache">
    成功したゴールをモデル呼び出しなしでリプレイします。
  </Card>
  <Card title="エージェントステップの仕組み" icon="list-check" href="/agent-steps">
    判定、終了コード、モデルに渡される情報を確認します。
  </Card>
</CardGroup>
