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

# Agentes de código

> Dê a um agente de código a skill, uma sessão ao vivo do app e relatórios que ele pode usar para escrever e depurar testes.

Um agente de código como Claude Code, Codex ou Cursor pode escrever, rodar e
depurar testes e2e. Ele aprende o e2e pela skill, usa o app pelo servidor
`e2e mcp` e lê a página de trace de um teste que falhou.

## Instale a skill

<CodeGroup>
```bash npm
npx e2e init
```

```bash pnpm
pnpm dlx e2e init
```

```bash bun
bunx e2e init
```
</CodeGroup>

| Caminho | Usado por |
| --- | --- |
| `.agents/skills/e2e/` | Codex, Cursor, OpenCode e outros agentes que leem `.agents/skills` |
| `.claude/skills/e2e/` | Claude Code. Um link simbólico para `.agents/skills/e2e/` quando os dois estão instalados. |

A cópia contém o `SKILL.md` e referências por tópico.
[`e2e upgrade`](https://e2e.com/docs/pt/reference/cli#e2e-upgrade) a atualiza, também depois que você
atualiza pelo seu gerenciador de pacotes. Sem o `init`,
`npx skills add e2e-inc/e2e` instala a skill, e `npx e2e guide [topic]` a
imprime a partir do pacote instalado. O plugin abaixo instala as três skills
do e2e para todos os projetos.

O `init` não altera as instruções do seu projeto. Para agentes que precisam de
uma indicação, adicione esta linha:

```md title="AGENTS.md"
End-to-end tests use e2e; read .agents/skills/e2e/SKILL.md before writing or running one.
```

O pacote também inclui esta documentação como páginas `.mdx` para leitura
offline, em `node_modules/e2e/docs` em um projeto de pacote único. Um link como
`/reference/cli` corresponde a `docs/reference/cli.mdx`.

<Accordion title="Instale o plugin para Claude Code, Codex ou Cursor">

O repositório do e2e é um marketplace de plugins para Claude Code e Codex, e
para o Grok Build, que lê os arquivos do Claude Code. O Cursor carrega o plugin
da sua pasta de plugins locais:

<CodeGroup>
```bash Claude
claude plugin marketplace add e2e-inc/e2e
claude plugin install e2e@e2e
```

```bash Codex
codex plugin marketplace add e2e-inc/e2e
codex plugin add e2e@e2e
```

```bash Cursor
repo=$(mktemp -d)
git clone --depth 1 https://github.com/e2e-inc/e2e "$repo"
mkdir -p ~/.cursor/plugins/local
rm -rf ~/.cursor/plugins/local/e2e
cp -R "$repo/plugins/e2e" ~/.cursor/plugins/local/
```
</CodeGroup>

Inicie uma nova sessão. No Cursor, rode **Developer: Reload Window**. No Cursor
Teams e Enterprise, plugins locais precisam da configuração de administrador
**Allow Local Plugin Imports**, ou um administrador importa `e2e-inc/e2e` como
marketplace da equipe. O plugin adiciona as skills
`e2e`, `create-verification-skill` e `migrate-to-e2e` e o
[servidor MCP](https://e2e.com/docs/pt/mcp-server), não o pacote npm. Invoque as outras duas sob o nome
do plugin, `/e2e:<skill>` no Claude Code e `$e2e:<skill>` no Codex, e como
`/<skill>` no Cursor.

A versão do plugin acompanha os lançamentos do e2e. Para atualizá-lo, rode
estes comandos e inicie uma nova sessão. No Cursor, rode de novo os comandos
acima.

<CodeGroup>
```bash Claude
claude plugin marketplace update e2e
claude plugin update e2e@e2e
```

```bash Codex
codex plugin marketplace upgrade e2e
```
</CodeGroup>

</Accordion>

<Accordion title="Instale no OpenClaw ou no Hermes Agent">

As três skills estão publicadas no [ClawHub](https://clawhub.ai/) sob
`@e2e`. O Hermes Agent lê o repositório como um tap:

<CodeGroup>
```bash OpenClaw
openclaw skills install @e2e/e2e
openclaw skills install @e2e/create-verification-skill
openclaw skills install @e2e/migrate-to-e2e
```

```bash Hermes
hermes skills tap add e2e-inc/e2e
hermes skills install e2e-inc/e2e/e2e
```
</CodeGroup>

</Accordion>

## Deixe o agente usar o app

O `e2e mcp` dá ao agente uma sessão ao vivo no seu app. O agente confere seus
localizadores na tela antes de escrevê-los e verifica as próprias mudanças na
UI. O `init` registra o servidor. Veja [Servidor MCP](https://e2e.com/docs/pt/mcp-server) para
configuração e prompts.

## Como um agente escreve e roda um teste

A skill instrui o agente a ler primeiro a configuração e um teste existente.
Com o `e2e mcp`, ele percorre o fluxo em uma sessão e escreve cada passo à
medida que o executa. Campos conhecidos e valores exatos viram chamadas de
`screen`, a partir de localizadores que corresponderam a um único nó:

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

test('a signed-in user reaches checkout', async ({ screen, app, agent }) => {
  const user = credentials.user('customer');
  await app.open('/login');
  await screen.getByLabel('Email').fill(user.username);
  await screen.getByLabel('Password').fill(user.password);
  await screen.getByRole('button', 'Sign in').click();
  await expect(screen.getByRole('heading', 'Welcome back')).toBeVisible();

  await agent.act('Add the cheapest item on the page to the cart');
  await expect(screen.getByRole('status', 'Cart')).toHaveText('1 item');
  await agent.act('Open the cart');
  await expect(screen.getByRole('heading', 'Your cart')).toBeVisible();
});
```

- **Um `agent.act` por [objetivo atômico](https://e2e.com/docs/pt/core-concepts#goals), depois um
  `expect`.** O `expect` falha quando o agente fez a coisa errada. Um matcher
  de localizador, ou outra
  [verificação](https://e2e.com/docs/pt/cache#when-a-recording-is-written), também permite que o
  cache reproduza o passo.
- **Sem sleeps.** Os localizadores fazem polling, as ações esperam pelo
  elemento-alvo e o `expect` tenta novamente até o seu tempo limite.
- **Segredos via `credentials.user(name)`.** Declare-os na configuração.
  Nunca os escreva em um teste.

Enquanto itera, o agente roda só o teste em que está trabalhando, pela linha
em que o seu `test(` começa. Com `--action-timeout 5000`, um localizador errado
falha após 5 s em vez de 30 s:

<CodeGroup>
```bash npm
npx e2e run tests/checkout.e2e.ts:3 --action-timeout 5000
```

```bash pnpm
pnpm exec e2e run tests/checkout.e2e.ts:3 --action-timeout 5000
```

```bash bun
bunx e2e run tests/checkout.e2e.ts:3 --action-timeout 5000
```
</CodeGroup>

O agente corrige erros de CLI, de configuração e de coleta antes de rodar de
novo. Ele não edita gravações do cache.

O agente mantém o cache de replay ligado, então um objetivo cuja verificação
passou é reproduzido sem chamadas ao modelo. Ele desliga as novas tentativas,
já que uma nova tentativa roda todos os objetivos ao vivo. Quando o teste
passa, o agente remove `--action-timeout` e o roda uma vez com `--no-cache`
para verificar que o agente ao vivo alcança todos os objetivos. Veja
[Rode um teste de novo enquanto o corrige](https://e2e.com/docs/pt/cache#rerun-a-test-while-you-fix-it).

## Como um agente lê uma falha

Por padrão ([`trace`](https://e2e.com/docs/pt/reference/config#trace)), uma execução escreve uma
página de trace para cada teste que falhou, excedeu o tempo limite, foi
interrompido ou se mostrou instável, no diretório do teste em
`.e2e/results/`. `.e2e` é o `output` padrão. O terminal indica a página abaixo
de cada teste que falhou, como `❯ trace .e2e/results/<test>/trace.md`.

O agente lê essa página, não o `.e2e/report.json`, que guarda os mesmos fatos
para [scripts](https://e2e.com/docs/pt/debugging). A página tem a linha que falhou e cada passo com o
que ele fez: o nó que uma ação atingiu, os valores que uma asserção leu, a
decisão do cache, erros do console e requisições que falharam. Ela também tem
os últimos turnos do agente e a tela no momento da falha.

O agente corrige o teste a partir dessas evidências. Ele corrige todas as
linhas que as evidências cobrem, não só a que falhou. Um teste para no
primeiro passo que falha, então o agente também confere as linhas depois dele
antes da próxima execução.

Para ver uma tela que a página não mostra, o agente a abre em uma sessão MCP
pelo caminho mais curto, como a URL dela na web. Ele não percorre o fluxo de
novo desde o início.

Para detalhes das chamadas ao modelo, o agente adiciona `--ai-trace` e lê o
trace com o [unbox-ai](https://e2e.com/docs/pt/debugging#agent-steps). Combine com `--no-cache` para
capturar todas as chamadas ao modelo no fluxo. Não abra o trace bruto no
contexto de um agente. Ele repete prompts e pode ter vários megabytes.

## Gere uma skill de verificação para o seu app

A skill do e2e ensina o runner, não o seu app. A skill
`create-verification-skill` escreve uma skill local do projeto,
`.agents/skills/verify-<app>/`, que ensina o app, e a testa uma vez antes de
entregá-la.

<CodeGroup>
```bash npm
npx skills add e2e-inc/e2e --skill create-verification-skill
```

```bash pnpm
pnpm dlx skills add e2e-inc/e2e --skill create-verification-skill
```

```bash bun
bunx skills add e2e-inc/e2e --skill create-verification-skill
```
</CodeGroup>

Depois, peça ao agente `/create-verification-skill`.

<Accordion title="O que a skill gerada contém">
- Comandos de inicialização e de doctor a partir da sua configuração.
- As duas formas de controlar o app: uma sessão ao vivo do `e2e mcp` e um
  teste.
- As evidências que uma prova guarda.
- Um mapa de funcionalidades com um charter de `e2e explore` para cada
  funcionalidade, para que um [bug bash](https://e2e.com/docs/pt/bug-bash) se distribua a partir do
  mapa.

A skill gerada diz só o que é verdade sobre o seu app e aponta para a skill do
e2e para o resto. Ela é baseada na
[create-verification-skill](https://github.com/cursor/plugins/tree/main/pstack/skills/create-verification-skill)
do pstack de poteto, com o e2e no lugar de um harness feito à mão.
</Accordion>

## Migre uma suíte existente

A skill `migrate-to-e2e` move uma suíte de Playwright, Cypress, Selenium,
Appium, Detox, Maestro ou TesterArmy para o e2e, uma fatia por sessão. A suíte
antiga continua rodando ao lado dos novos testes, então você pode parar depois
de qualquer sessão.

<CodeGroup>
```bash npm
npx skills add e2e-inc/e2e --skill migrate-to-e2e
```

```bash pnpm
pnpm dlx skills add e2e-inc/e2e --skill migrate-to-e2e
```

```bash bun
bunx skills add e2e-inc/e2e --skill migrate-to-e2e
```
</CodeGroup>

Depois, peça ao agente `/migrate-to-e2e`. Ele porta a fatia que você escolher
e roda cada teste portado três vezes em cada alvo. Um arquivo `MIGRATION.md`
registra o progresso para a próxima sessão. Opcionalmente, o agente planta um
bug temporário no app, como um total errado no checkout, e verifica se as duas
suítes falham com ele. O agente só apaga um teste antigo quando você confirma.
Primeiro, ele lê o guia de migração do seu runner:
[Playwright](https://e2e.com/docs/pt/migrate/playwright), [Cypress](https://e2e.com/docs/pt/migrate/cypress),
[Selenium](https://e2e.com/docs/pt/migrate/selenium), [Appium](https://e2e.com/docs/pt/migrate/appium), [Detox](https://e2e.com/docs/pt/migrate/detox),
[Maestro](https://e2e.com/docs/pt/migrate/maestro) ou [TesterArmy](https://e2e.com/docs/pt/migrate/testerarmy).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência da CLI" icon="terminal" href="/reference/cli">
    init, guide, mcp e run, flag por flag.
  </Card>
  <Card title="Depurar uma execução" icon="bug" href="/debugging">
    O relatório, os artefatos e as flags do agente.
  </Card>
</CardGroup>
