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

# Conceitos principais

> Objetivos, asserções e localizadores, e como estruturar e rodar testes com eles.

Um teste combina três tipos de passo:

| Passo | API | Chamada ao modelo |
| --- | --- | --- |
| [Objetivo](#goals) | `agent.act` | Sim, a menos que o [cache](https://e2e.com/docs/pt/cache) o reproduza |
| [Asserção](#assertions) | `agent.assert`, `agent.waitFor`, `agent.extract` | Sim |
| [Localizador](#locators) | `screen` e `expect` | Não |

Com um [executor personalizado](https://e2e.com/docs/pt/executors), `act` e `assert` não precisam de
modelo.

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

Cada teste verifica um comportamento em três blocos: prepare o estado inicial,
acione o comportamento e depois faça asserções sobre o resultado.

Aguarde (await) cada chamada ao agente, cada chamada à tela e cada
`expect.poll`. Se um teste retornar enquanto um passo ainda estiver em
execução, o teste falha com `STEP_NOT_AWAITED`.

## Objetivos

`agent.act` recebe um objetivo e executa as ações de que ele precisa. Ele
retorna quando o objetivo é concluído e lança um erro quando o objetivo falha.

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

Mantenha cada objetivo atômico: um resultado que uma única verificação
confirma. Quando duas partes de uma instrução deixam, cada uma, um estado que
vale a pena verificar, elas são dois objetivos. Um teste pode ter muitos
objetivos.

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

Os objetivos de preparação vêm primeiro e terminam com uma espera pelo estado
que eles alcançam. O objetivo em teste vem em seguida. As asserções sobre o
resultado dele vêm por último. Assim, uma falha indica o objetivo que quebrou.
Cada objetivo é reproduzido a partir da sua própria gravação e recebe seus
próprios [orçamentos](https://e2e.com/docs/pt/reference/agent#budgets) de chamadas ao modelo e de
ações. As ações que levam a um mesmo resultado não são objetivos: abrir a tela
ou o menu que contém um controle, rolar até ele, fechar um banner ou preencher
os campos de um mesmo formulário.

- Você controla a ordem dos objetivos. O agente escolhe as ações.
- Termine o teste com um `expect` sobre o resultado. O
  [cache de replay](https://e2e.com/docs/pt/cache) grava um objetivo somente depois que uma
  verificação ou espera posterior passa.
- Use as palavras que a tela mostra.
- Passe os dados de teste em `params`. Para uma senha, passe um `Secret`. O
  modelo nunca recebe o valor dele como texto. Veja
  [Autenticação](https://e2e.com/docs/pt/authentication).
- Para um valor que muda a cada execução, use `unique()` para que o
  [cache possa reproduzir o passo](https://e2e.com/docs/pt/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` obtém capturas de tela quando precisa delas. Em algumas engines, ele
pode tocar e digitar em pontos da imagem.

Se um objetivo falhar, leia o relatório e torne a instrução mais específica.
Coloque no [`context`](https://e2e.com/docs/pt/agents) do agente as palavras que muitos objetivos
usam.

## Asserções

Uma asserção avalia a tela. O modelo vê a afirmação, um snapshot em texto da
tela atual com dados sensíveis ocultados, a localização da tela e o contexto
do agente. Ele não vê os passos anteriores nem os resumos de `act`.

- `agent.assert` examina a tela neste momento. Uma afirmação falsa falha com
  `ASSERTION_FAILED`. Quando as evidências não bastam, a asserção falha com
  `ASSERTION_INCONCLUSIVE`.
- `agent.waitFor` espera até que uma condição seja verdadeira. Ele chama o
  modelo somente quando a tela ou a localização dela muda.
- `agent.extract` lê dados da tela para um tipo
  [Standard Schema](https://standardschema.dev), por exemplo 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');
```

Para um texto que o modelo escreveu, examine o significado, não a frase
completa. Quando o texto exato importa, use um [localizador](#locators).

Para uma verificação visual, como um gráfico ou um layout, adicione
`vision: true`. Para avaliar apenas a captura de tela, use `vision: 'only'`.
Imagens acrescentam tokens de entrada. Veja a
[referência do agente](https://e2e.com/docs/pt/reference/agent#vision).

## Localizadores

Um localizador encontra um controle conhecido, sem chamada ao modelo. Use um
quando você souber a ação exata ou o valor exato.

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

- Uma ação, uma leitura ou uma asserção de nó único falha quando a consulta
  dela encontra mais de um nó. Use `.filter()`, `.first()` ou `.nth()` para
  encontrar um único nó.
- Uma leitura direta, como `textContent()`, espera pela correspondência,
  depois lê uma vez e não tenta novamente em busca de um valor.

Veja a [referência de screen](https://e2e.com/docs/pt/reference/screen) e a
[referência de expect](https://e2e.com/docs/pt/reference/expect#locator-matchers). Para rotas,
cookies, diálogos e downloads, veja
[Trabalhando com o navegador](https://e2e.com/docs/pt/browser).

## Organize os testes

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

- Cada teste roda na sua própria tentativa. Comece-o perto da tela que ele
  verifica, para que cada execução pule os cliques que levam até lá. Crie os
  dados dele em fixtures ou hooks. Em um navegador, restaure uma
  [sessão salva](https://e2e.com/docs/pt/authentication) e abra a tela pelo caminho dela. Em um
  dispositivo, abra um [deep link](https://e2e.com/docs/pt/mobile#the-device-fixture).
- `test.skip(condition, reason)` interrompe o teste como `skipped` quando a
  condição é verdadeira.
- Para um fluxo que atravessa muitos testes, defina `{ serial: true }` no
  grupo. Os testes rodam em sequência em um único worker e fazem novas
  tentativas juntos.
- Para preparação e limpeza, use `test.extend`. Veja
  [Escrevendo fixtures](https://e2e.com/docs/pt/fixtures).
- Importe `test` de `@e2e-dev/web` ou `@e2e-dev/mobile` para tipar a fixture
  `browser` ou `device`.

A [referência de test](https://e2e.com/docs/pt/reference/test) mostra todas as opções.

## Rode um teste

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

A [referência da CLI](https://e2e.com/docs/pt/reference/cli#e2e-run) mostra todas as flags.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cache" icon="box-archive" href="/cache">
    Reproduza os objetivos que passaram, sem chamadas ao modelo.
  </Card>
  <Card title="Como funcionam os passos do agente" icon="list-check" href="/agent-steps">
    Vereditos, códigos de saída e o que o modelo vê.
  </Card>
</CardGroup>
