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

# Concepts clés

> Objectifs, assertions et locators, et comment structurer et lancer des tests avec eux.

Un test combine trois types d'étapes :

| Étape | API | Appel au modèle |
| --- | --- | --- |
| [Objectif](#goals) | `agent.act` | Oui, sauf si le [cache](https://e2e.com/docs/fr/cache) le rejoue |
| [Assertion](#assertions) | `agent.assert`, `agent.waitFor`, `agent.extract` | Oui |
| [Locator](#locators) | `screen` et `expect` | Non |

Avec un [exécuteur personnalisé](https://e2e.com/docs/fr/executors), `act` et `assert` n'ont besoin d'aucun modèle.

```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"');
  });
});
```

Chaque test vérifie un comportement en trois blocs : préparer l'état de départ,
agir sur le comportement, puis vérifier le résultat.

Attendez chaque appel à l'agent, chaque appel à l'écran et `expect.poll`. Si un test se termine
alors qu'une étape est encore en cours, le test échoue avec `STEP_NOT_AWAITED`.

## Objectifs

`agent.act` prend un objectif et effectue les actions nécessaires. Il rend la main quand
l'objectif est atteint et lève une erreur quand l'objectif échoue.

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

Gardez chaque objectif atomique : un résultat qu'une seule vérification confirme. Quand deux parties
d'une instruction laissent chacune un état qui mérite d'être vérifié, ce sont deux objectifs.
Un test peut contenir de nombreux objectifs.

```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();
});
```

Les objectifs de préparation viennent en premier et se terminent par une attente de l'état qu'ils atteignent.
L'objectif testé vient ensuite. Les assertions sur son résultat viennent en dernier. Un
échec désigne alors l'objectif qui a cassé. Chaque objectif est rejoué depuis son propre
enregistrement et dispose de ses propres
[budgets](https://e2e.com/docs/fr/reference/agent#budgets) d'appels au modèle et d'actions. Les actions menant à un même résultat ne sont pas
des objectifs : ouvrir l'écran ou le menu qui contient un contrôle, faire défiler jusqu'à lui,
fermer une bannière, ou remplir les champs d'un formulaire.

- Vous contrôlez l'ordre des objectifs. L'agent choisit les actions.
- Terminez le test par un `expect` sur le résultat. Le [cache de rejeu](https://e2e.com/docs/fr/cache)
  n'enregistre un objectif qu'après la réussite d'une vérification ou d'une attente ultérieure.
- Utilisez les mots affichés à l'écran.
- Fournissez les données de test dans `params`. Pour un mot de passe, fournissez un `Secret`. Le modèle
  ne reçoit jamais sa valeur sous forme de texte. Consultez [Authentification](https://e2e.com/docs/fr/authentication).
- Pour une valeur qui change à chaque exécution, utilisez `unique()` afin que le
  [cache puisse rejouer l'étape](https://e2e.com/docs/fr/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` prend des captures d'écran quand il en a besoin. Sur certains moteurs, il peut appuyer et
saisir du texte à des points précis de l'image.

Si un objectif échoue, lisez le rapport et rendez l'instruction plus précise.
Placez les termes utilisés par de nombreux objectifs dans le [`context`](https://e2e.com/docs/fr/agents) de l'agent.

## Assertions

Une assertion évalue l'écran. Le modèle voit l'énoncé, un snapshot
textuel de l'écran actuel aux secrets masqués, son emplacement et le contexte de l'agent. Il ne
voit ni les étapes précédentes ni les résumés de `act`.

- `agent.assert` examine l'écran à l'instant présent. Un énoncé faux échoue avec
  `ASSERTION_FAILED`. Quand les éléments ne suffisent pas, il échoue avec
  `ASSERTION_INCONCLUSIVE`.
- `agent.waitFor` attend qu'une condition soit vraie. Il n'appelle le modèle que
  lorsque l'écran ou son emplacement change.
- `agent.extract` lit des données de l'écran dans un type
  [Standard Schema](https://standardschema.dev), par exemple Zod.

```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');
```

Pour un texte rédigé par le modèle, examinez le sens, pas la phrase entière.
Quand le texte exact compte, utilisez un [locator](#locators).

Pour une vérification visuelle, comme un graphique ou une mise en page, ajoutez `vision: true`. Pour
évaluer uniquement la capture d'écran, utilisez `vision: 'only'`. Les images ajoutent des tokens en entrée.
Consultez la [référence de l'agent](https://e2e.com/docs/fr/reference/agent#vision).

## Locators

Un locator trouve un contrôle connu, sans appel au modèle. Utilisez-en un quand vous connaissez
l'action exacte ou la valeur exacte.

```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');
```

- Une action, une lecture ou une assertion sur un seul nœud échoue quand sa requête trouve
  plus d'un nœud. Utilisez `.filter()`, `.first()` ou `.nth()` pour en trouver un
  seul.
- Une lecture directe, comme `textContent()`, attend sa correspondance, puis lit une seule fois
  et ne relance pas pour obtenir une valeur.

Consultez la [référence de screen](https://e2e.com/docs/fr/reference/screen) et la
[référence d'expect](https://e2e.com/docs/fr/reference/expect#locator-matchers). Pour les routes, les cookies,
les boîtes de dialogue et les téléchargements, consultez [Utiliser le navigateur](https://e2e.com/docs/fr/browser).

## Organiser les tests

```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');
});
```

- Chaque test s'exécute dans sa propre tentative. Démarrez-le près de l'écran qu'il vérifie, pour que
  chaque exécution évite les clics qui y mènent. Créez ses données dans des fixtures
  ou des hooks. Dans un navigateur, restaurez une [session enregistrée](https://e2e.com/docs/fr/authentication) et
  ouvrez l'écran par son chemin. Sur un appareil, ouvrez un
  [lien profond](https://e2e.com/docs/fr/mobile#the-device-fixture).
- `test.skip(condition, reason)` arrête le test avec le statut `skipped` quand la
  condition est vraie.
- Pour un parcours réparti sur plusieurs tests, définissez `{ serial: true }` sur le groupe. Les
  tests s'exécutent en séquence sur un seul worker et sont relancés ensemble.
- Pour la préparation et le nettoyage, utilisez `test.extend`. Consultez
  [Écrire des fixtures](https://e2e.com/docs/fr/fixtures).
- Importez `test` depuis `@e2e-dev/web` ou `@e2e-dev/mobile` pour typer la fixture
  `browser` ou `device`.

La [référence de test](https://e2e.com/docs/fr/reference/test) présente toutes les options.

## Lancer un test

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

La [référence de la CLI](https://e2e.com/docs/fr/reference/cli#e2e-run) présente toutes les options.

## Pour aller plus loin

<CardGroup cols={2}>
  <Card title="Mise en cache" icon="box-archive" href="/cache">
    Rejouez les objectifs réussis sans appel au modèle.
  </Card>
  <Card title="Fonctionnement des étapes d'agent" icon="list-check" href="/agent-steps">
    Verdicts, codes de sortie et ce que voit le modèle.
  </Card>
</CardGroup>
