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

Dependências JavaScript já estão listadas em package.json (vitest, @vitest/browser-playwright, playwright, jsdom, etc.).
Baixe os binários do Playwright uma vez:
```
pnpm exec playwright install chromium
```

Em ambientes Linux “puros”, instale as bibliotecas de sistema recomendadas:

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.

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:

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

Rode pnpm test localmente antes de abrir PRs.
Para alterações visuais/lógicas que afetem UI, adicione/atualize um teste em tests/browser e valide com pnpm test:browser.
Se novos snapshots forem criados ou alterados, confirme visualmente e inclua os arquivos em commit.
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.***

3.7 KiB Raw Blame History