chore: document and stabilize vitest browser setup

docs/testes-vitest.md

@@ -0,0 +1,70 @@
+# 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
+
+- `pnpm test` → roda a suíte unitária em ambiente Node/JSdom.
+- `pnpm test:browser` → executa os testes de navegador via Playwright (Chromium headless).
+- `pnpm 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
+   pnpm exec playwright install chromium
+   ```
+3. Em ambientes Linux “puros”, instale as bibliotecas de sistema recomendadas:
+   ```bash
+   sudo apt-get install libnspr4 libnss3 libasound2t64
+   # ou
+   sudo pnpm exec playwright install-deps
+   ```
+
+Se o Playwright avisar sobre dependências ausentes ao rodar `pnpm 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 `pnpm 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 `pnpm 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.***