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