70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
# Guia de Testes com Vitest 4
|
|
|
|
Este documento resume a configuração atual de testes e como aproveitá-la para automatizar novas verificações.
|
|
|
|
## Comandos principais
|
|
|
|
- `bun test` → roda a suíte unitária em ambiente Node/JSdom.
|
|
- `bun run test:browser` → executa os testes de navegador via Playwright (Chromium headless).
|
|
- `bun run test:all` → executa as duas suítes de uma vez (requer Playwright instalado).
|
|
|
|
> Sempre que adicionar novos testes, priorize mantê-los compatíveis com esses dois ambientes.
|
|
|
|
## Pré-requisitos
|
|
|
|
1. Dependências JavaScript já estão listadas em `package.json` (`vitest`, `@vitest/browser-playwright`, `playwright`, `jsdom`, etc.).
|
|
2. Baixe os binários do Playwright uma vez:
|
|
```bash
|
|
bun x playwright install chromium
|
|
```
|
|
3. Em ambientes Linux “puros”, instale as bibliotecas de sistema recomendadas:
|
|
```bash
|
|
sudo apt-get install libnspr4 libnss3 libasound2t64
|
|
# ou
|
|
sudo bun x playwright install-deps
|
|
```
|
|
|
|
Se o Playwright avisar sobre dependências ausentes ao rodar `bun run test:browser`, instale-as e repita o comando.
|
|
|
|
## Estrutura de setup
|
|
|
|
- `vitest.setup.node.ts` → executado apenas na suíte Node. Aqui é seguro acessar `process`, configurar variáveis de ambiente, carregar `tsconfig-paths/register`, etc.
|
|
- `tests/setup.browser.ts` → setup vazio para a suíte de navegador. Não use `process` ou APIs do Node aqui; adicione polyfills/mocks específicos do browser quando necessário.
|
|
|
|
O arquivo `vitest.config.mts` seleciona automaticamente o setup correto com base na env `VITEST_BROWSER`.
|
|
|
|
```ts
|
|
setupFiles: process.env.VITEST_BROWSER
|
|
? ["./tests/setup.browser.ts"]
|
|
: ["./vitest.setup.node.ts"],
|
|
```
|
|
|
|
## Boas práticas para novos testes
|
|
|
|
- **Aliases (`@/`)**: continuam funcionando em ambos os ambientes graças ao `vite-tsconfig-paths`.
|
|
- **Variáveis de ambiente no browser**: use `import.meta.env.VITE_*`. Evite `process.env` no código que será executado no navegador.
|
|
- **Mocks Playwright**: para testes de browser, use os helpers de `vitest/browser`. Exemplo:
|
|
```ts
|
|
import { expect, test } from "vitest"
|
|
import { page } from "vitest/browser"
|
|
|
|
test("exemplo", async () => {
|
|
await page.goto("https://example.com")
|
|
await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
|
|
})
|
|
```
|
|
No nosso exemplo atual (`tests/browser/example.browser.test.ts`) manipulamos o DOM diretamente e geramos screenshots com `expect(...).toMatchScreenshot(...)`.
|
|
- **Snapshots visuais**: os arquivos de referência ficam em `tests/browser/__screenshots__/`. Ao criar ou atualizar um snapshot, revise e commite apenas se estiver correto.
|
|
- **Mocks que dependem de `vi.fn()`**: quando mockar classes/constructores (ex.: `ConvexHttpClient`), use funções nomeadas ou `class` ao definir a implementação para evitar os erros do Vitest 4 (“requires function or class”).
|
|
|
|
## Fluxo sugerido no dia a dia
|
|
|
|
1. Rode `bun test` localmente antes de abrir PRs.
|
|
2. Para alterações visuais/lógicas que afetem UI, adicione/atualize um teste em `tests/browser` e valide com `bun run test:browser`.
|
|
3. Se novos snapshots forem criados ou alterados, confirme visualmente e inclua os arquivos em commit.
|
|
4. Para tarefas de automação futuras (por exemplo, smoke-tests que renderizam componentes críticos), utilize a mesma estrutura:
|
|
- Setup mínimo no `tests/setup.browser.ts`.
|
|
- Testes localizados em `tests/browser/**.browser.test.ts`.
|
|
- Utilização de Playwright para interagir com a UI e gerar screenshots/asserts.
|
|
|
|
Seguindo este guia, conseguimos manter a suíte rápida no ambiente Node e, ao mesmo tempo, aproveitar o modo browser do Vitest 4 para validações visuais e regressões de UI. Quilas regressões detectadas automaticamente economizam tempo de QA manual e agilizam o ciclo de entrega.***
|