vek1-qa

Você escreve e roda testes do vek1 com Vitest (vitest.config.ts,
src/**/__tests__/). Rodar: npm run test / npm run test:watch /
npm run test:coverage. Para um arquivo específico:
npx vitest run caminho/do/arquivo.test.ts.

O que mockar (e o que NÃO mockar)

O vek1 é um BFF: server actions e API routes não tocam o banco diretamente, elas chamam
apiClient.<recurso>.* (que por sua vez chama o backend externo vek1-api via HTTP). Logo:

• Mocke @/lib/api-client (o objeto apiClient e seus métodos) — é o ponto de
  fronteira real. Ver src/app/actions/__tests__/billing-actions.test.ts como referência
  atual e correta:

  vi.mock('@/lib/auth-server', () => ({ requireUser: vi.fn(), getCurrentUser: vi.fn() }));
  vi.mock('@/lib/api-client', async () => {
    const actual = await vi.importActual<typeof import('@/lib/api-client')>('@/lib/api-client');
    return { ...actual, apiClient: { billing: { getSummary: vi.fn(), /* ... */ } } };
  });
  vi.mock('next/cache', () => ({ revalidatePath: vi.fn() }));
  

• Mocke @/lib/auth-server (getCurrentUser/requireUser) para simular usuário
  autenticado/não-autenticado.
• NÃO mocke @supabase/ssr, createServerClient, ou qualquer coisa de Supabase — o
  projeto migrou para Drizzle + Better Auth. src/app/actions/__tests__/store-actions.test.ts
  é um exemplo do padrão antigo e obsoleto: está com describe.skip e um comentário
  TODO(migration): mocks Supabase obsoletos explícito. Não copie desse arquivo — é dívida
  técnica conhecida, não referência.
• NÃO mocke Drizzle/db.* em testes de action/route de produto — se você sentir
  necessidade de mockar db.insert/db.select num teste de document-actions.ts ou
  similar, é sinal de que confundiu o BFF com um app de DB direto (ver vek1-frontend).
  Drizzle direto só faz sentido em testes de código de auth.
• Para embeddings.ts/chamadas a vek1-api (/embed, /extract-lead, etc.), mocke o
  fetch — não bata em serviço real durante teste automatizado.

Convenções

• Nome de teste descreve comportamento, não implementação: retorna 401 quando usuário não está autenticado, não testa createDocument.
• Arquivo de teste ao lado do domínio: src/app/actions/__tests__/,
  src/lib/queries/__tests__/, src/lib/utils/__tests__/, src/components/__tests__/.
• Testes que dependem de banco real (DATABASE_URL) costumam vir com skip condicional —
  isso é esperado neste repo (ver src/lib/queries/__tests__/documents.test.ts), não é
  teste quebrado.

Antes de escrever um teste novo

1. Rode a suíte relevante primeiro para ter baseline (npx vitest run <path>) — o repo
   tem débito técnico conhecido (describe.skip em testes com mock Supabase obsoleto);
   não confunda isso com regressão da sua mudança.
2. Verifique se já existe teste cobrindo o caso antes de duplicar.
3. Para actions/routes novas, siga o padrão de billing-actions.test.ts
   (api-client + auth-server mockados), não o de store-actions.test.ts.
4. Ambiente Windows: se vitest/tsc falharem com Cannot find module '@rollup/rollup-win32-x64-msvc', é um bug conhecido de optional-dependency do npm no
   Windows — rode npm install @rollup/rollup-win32-x64-msvc --no-save (não mexa no
   lockfile por causa disso).

Antes de considerar terminado

• npx tsc --noEmit -p . limpo (ignorando erros pré-existentes não relacionados — confirme
  rodando a mesma checagem em main/antes da sua mudança se não tiver certeza).
• npx eslint <arquivos alterados> limpo.
• Suíte relevante passando, sem introduzir novos skip.