# Execuções de teste

> Fonte: https://astrallab.dev/pt/docs/test-runs

Uma execução de teste transforma um script em evidências. O agente envolve um fluxo em `astral.test`, divide-o em passos, declara o que deve ser verdadeiro, e o Astral registra o que aconteceu.

As execuções de teste usam a ferramenta `run_script`, que executa JavaScript escrito pelo agente em um sandbox que chama as outras ferramentas. O grupo `script` vem desligado por padrão; o grupo `tests` vem ligado por padrão, mas só tem efeito enquanto `script` estiver ligado. Veja [o grupo script](https://astrallab.dev/pt/docs/tools.md#group-script).

## Um exemplo

```js
return await astral.test('Login demo', async () => {
  await astral.step('Open the store', () => astral.navigate({url: 'http://localhost:3000/'}));
  await astral.step('Sign in', async () => {
    await astral.type({locator: {role: 'textbox', name: 'Username'}, text: 'demo'});
    await astral.type({locator: {role: 'textbox', name: 'Password'}, text: 'demo', submit: true});
    await astral.expect.visible({role: 'button', name: 'Sign out'});
    await astral.expect.noErrors();
  });
  await astral.step('Pay', async () => {
    await astral.click({locator: {role: 'button', name: 'Pay'}});
    await astral.expect.request({urlContains: '/api/', method: 'POST', status: '2xx'});
  });
}, {continueOnFailure: true, record: 'actions'});
```

Passe a `run_script` um `timeoutMs` de 60000 a 120000 para um teste: as evidências levam tempo.

## astral.test e astral.step

Opções de `astral.test(name, fn, options)`: `tabId`, `continueOnFailure` (padrão false) e `record`. Ele não lança exceção quando um passo falha: verifique o `status` no resultado, que também traz os totais, um `summary` em Markdown e os caminhos do relatório.

`astral.step(name, fn)` agrupa ações. Ao final, e sempre que falha, o Astral salva uma captura de tela, a URL e o título, as requisições feitas durante o passo (as que falham, com cabeçalhos e corpos ocultados), erros e avisos do console e quaisquer novos grupos de erros. Um passo falha quando a sua função lança uma exceção ou uma expectativa dentro dele falha. Sem `continueOnFailure`, o teste para no primeiro passo que falhar.

`run_script` também aceita `test: {name, continueOnFailure, ...}` para tratar o script inteiro como um único teste.

## Expectativas

| Chamada | Passa quando |
| --- | --- |
| `expect.visible(locator)` | O elemento está visível, esperando até `timeoutMs` (padrão 5000). |
| `expect.hidden(locator)` | O elemento não está visível. |
| `expect.text(locator, 'contains')` / `expect.text('text')` | O elemento contém o texto, ou o texto aparece em qualquer lugar da página. |
| `expect.url('/dashboard')` / `expect.url(/regex/)` | A URL da aba corresponde. |
| `expect.request({urlContains, method, status})` | Uma requisição correspondente foi feita desde que o passo começou. `status` é um número, `'2xx'` ou `'error'`. |
| `expect.noErrors({kinds, waitMs, ignoreStatus, ignore})` | Nenhum grupo de erros novo apareceu desde que o passo começou. Ignore status como 401 ou mensagens por substring. |
| `expect.layout({rules, ignore})` | O layout responsivo da página não tem erros no viewport da execução. Veja [a verificação de layout](https://astrallab.dev/pt/docs/saved-tests.md#layout). |

Um localizador é `{role, name, text, nth, exact}`, uma referência de snapshot como `"e12"`, ou um texto. Uma expectativa que falha lança um erro de asserção com o que era esperado e o que foi encontrado, e o relatório o mostra. `astral.screenshot({name, fullPage})` dentro de um teste adiciona uma captura de tela nomeada ao passo atual.

## Modos de gravação

| Modo | O que é capturado |
| --- | --- |
| `'off'` | Capturas de tela somente das falhas. |
| `'steps'` (padrão) | Uma captura de tela ao final de cada passo. |
| `'actions'` | Também uma após cada clique, digitação, seleção, tecla pressionada e navegação, tirada enquanto um marcador indica o alvo: uma caixa, uma onda no ponto do clique e uma legenda como _click "Sign in"_. |
| `'video'` | Também quadros da aba a 4 por segundo (até 5 minutos ou 200 MB), salvos como um `recording.png` animado, e `recording.mp4` onde o Astral consegue codificá-lo (macOS), com um player de quadros no relatório. |

Os marcadores são desenhados em todos os modos, exceto `'off'`, desaparecem após 2,5 segundos e ao final da execução, e nunca capturam cliques. O texto digitado em um campo de senha, de código de uso único ou de cartão nunca é gravado: as legendas mostram •••••• e o valor é mascarado no resto do relatório. Veja [Plataformas](https://astrallab.dev/pt/docs/platforms.md) para saber onde há suporte a vídeo.

## O que uma execução deixa

Cada execução grava uma pasta no diretório de dados do Astral contendo:

- `report.html`: um relatório legível com um resumo, um cartão por passo com suas capturas de tela, a asserção que falhou, requisições com falha, erros do console, erros de página agrupados, uma linha do tempo de ações e uma seção de desempenho.
- `report.json`: os mesmos dados, mais um resumo em Markdown escrito para ser colado em uma issue.
- As capturas de tela como arquivos PNG e a gravação, se você pediu uma.

As 50 execuções mais recentes são mantidas (configurável em Settings → Developer, onde as execuções de teste também podem ser desativadas). O agente lê as execuções de volta com `test_runs_list` e `test_run_get`.

## Evidências para tickets

O resumo em Markdown é feito para ser colado em uma issue, junto com as capturas de tela e o relatório. Se o seu agente está conectado à sua ferramenta de tickets, ele pode publicar essas evidências lá por você. O Astral em si não se integra a nenhuma ferramenta de tickets: ele escreve as evidências e deixa a publicação para você ou para o seu agente.

Os nomes dos testes, os passos, os nomes das capturas de tela e tudo o que o Astral escreve sobre uma execução ficam em inglês, seja qual for o idioma que você, o ticket ou a página usem. Somente os localizadores mantêm o texto da própria página.