> ## Documentation Index > Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260623-1106.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Testes > Testes unitários, testes E2E e utilitários de teste failproofai possui duas suítes de testes: **testes unitários** (rápidos, com mocks) e **testes end-to-end** (invocações reais de subprocessos). *** ## Executando os testes ```bash theme={null} # Executar todos os testes unitários uma vez bun run test:run # Executar testes unitários em modo watch bun run test # Executar testes E2E (requer configuração - veja abaixo) bun run test:e2e # Verificar tipos sem compilar bunx tsc --noEmit # Lint bun run lint ``` *** ## Testes unitários Os testes unitários ficam em `__tests__/` e usam [Vitest](https://vitest.dev) com `jsdom`. ```text theme={null} __tests__/ hooks/ builtin-policies.test.ts # Lógica de políticas para cada builtin hooks-config.test.ts # Carregamento de configuração e mesclagem de escopos policy-evaluator.test.ts # Injeção de parâmetros e ordem de avaliação custom-hooks-registry.test.ts # Registro globalThis: add/get/clear custom-hooks-loader.test.ts # Loader ESM, imports transitivos, tratamento de erros manager.test.ts # Operações install/remove/list components/ sessions-list.test.tsx # Componente de lista de sessões project-list.test.tsx # Componente de lista de projetos ... lib/ logger.test.ts paths.test.ts date-filters.test.ts telemetry.test.ts ... actions/ get-hooks-config.test.ts get-hook-activity.test.ts ... contexts/ ThemeContext.test.tsx AutoRefreshContext.test.tsx ``` ### Escrevendo um teste unitário de política ```typescript theme={null} import { describe, it, expect, beforeEach } from "vitest"; import { getBuiltinPolicies } from "../../src/hooks/builtin-policies"; import { allow, deny } from "../../src/hooks/policy-types"; describe("block-sudo", () => { const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!; it("denies sudo commands", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, toolName: "Bash", toolInput: { command: "sudo apt install nodejs" }, params: { allowPatterns: [] }, }; expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai")); }); it("allows non-sudo commands", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, toolName: "Bash", toolInput: { command: "ls -la" }, params: { allowPatterns: [] }, }; expect(policy.fn(ctx)).toEqual(allow()); }); it("allows patterns in allowPatterns", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, toolName: "Bash", toolInput: { command: "sudo systemctl status nginx" }, params: { allowPatterns: ["sudo systemctl status"] }, }; expect(policy.fn(ctx)).toEqual(allow()); }); }); ``` *** ## Testes end-to-end Os testes E2E invocam o binário real do `failproofai` como subprocesso, enviam um payload JSON via stdin e verificam a saída no stdout e o código de saída. Isso testa o caminho completo de integração que o Claude Code utiliza. ### Configuração Os testes E2E executam o binário diretamente a partir do código-fonte do repositório. Antes da primeira execução, compile o bundle CJS que os arquivos de hooks customizados utilizam ao importar de `'failproofai'`: ```bash theme={null} bun build src/index.ts --outdir dist --target node --format cjs ``` Em seguida, execute os testes: ```bash theme={null} bun run test:e2e ``` Recompile o `dist/` sempre que alterar a API pública de hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`). ### Estrutura dos testes E2E ```text theme={null} __tests__/e2e/ helpers/ hook-runner.ts # Inicializa o binário, envia payload JSON, captura código de saída + stdout + stderr fixture-env.ts # Diretórios temporários isolados por teste com arquivos de configuração payloads.ts # Fábricas de payload compatíveis com Claude para cada tipo de evento hooks/ builtin-policies.e2e.test.ts # Cada política builtin com subprocesso real custom-hooks.e2e.test.ts # Carregamento e avaliação de hooks customizados config-scopes.e2e.test.ts # Mesclagem de configuração entre escopos project/local/global policy-params.e2e.test.ts # Injeção de parâmetros para cada política parametrizada ``` ### Usando os utilitários E2E **`FixtureEnv`** — ambiente isolado por teste: ```typescript theme={null} import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - diretório temporário; passe como payload.cwd para carregar .failproofai/policies-config.json // env.home - diretório home isolado; sem vazamentos do ~/.failproofai real env.writeConfig({ enabledPolicies: ["block-sudo"], policyParams: { "block-sudo": { allowPatterns: ["sudo systemctl status"] }, }, }); ``` `createFixtureEnv()` registra a limpeza via `afterEach` automaticamente. **`runHook`** — invoca o binário: ```typescript theme={null} import { runHook } from "../helpers/hook-runner"; import { Payloads } from "../helpers/payloads"; const result = await runHook( "PreToolUse", Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd), { homeDir: env.home } ); expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` **`Payloads`** — fábricas de payload prontas para uso: ```typescript theme={null} Payloads.preToolUse.bash(command, cwd) Payloads.preToolUse.write(filePath, content, cwd) Payloads.preToolUse.read(filePath, cwd) Payloads.postToolUse.bash(command, output, cwd) Payloads.postToolUse.read(filePath, content, cwd) Payloads.notification(message, cwd) Payloads.stop(cwd) ``` ### Escrevendo um teste E2E ```typescript theme={null} import { describe, it, expect } from "vitest"; import { createFixtureEnv } from "../helpers/fixture-env"; import { runHook } from "../helpers/hook-runner"; import { Payloads } from "../helpers/payloads"; describe("block-rm-rf (E2E)", () => { it("denies rm -rf", async () => { const env = createFixtureEnv(); env.writeConfig({ enabledPolicies: ["block-rm-rf"] }); const result = await runHook( "PreToolUse", Payloads.preToolUse.bash("rm -rf /", env.cwd), { homeDir: env.home } ); expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); }); it("allows non-recursive rm", async () => { const env = createFixtureEnv(); env.writeConfig({ enabledPolicies: ["block-rm-rf"] }); const result = await runHook( "PreToolUse", Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd), { homeDir: env.home } ); expect(result.exitCode).toBe(0); expect(result.stdout).toBe(""); // allow → stdout vazio }); }); ``` ### Formatos de resposta E2E | Decisão | Código de saída | stdout | | ------------------- | --------------- | --------------------------------------------------------------------------------------- | | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (não-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | | Stop instruct | `2` | stdout vazio; motivo no stderr | | Allow | `0` | string vazia | ### Configuração do Vitest Os testes E2E usam `vitest.config.e2e.mts` com: * `environment: "node"` — sem globals de navegador * `pool: "forks"` — isolamento real de processos (os testes inicializam subprocessos) * `testTimeout: 20_000` — 20s por teste (inicialização do binário + avaliação do hook) O pool `forks` é importante: workers baseados em threads compartilham `globalThis`, o que pode interferir em testes que inicializam subprocessos. Forks baseados em processos evitam esse problema. *** ## CI A execução completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve passar antes do merge. A suíte E2E é executada como um job de CI separado, em paralelo. Consulte [Contributing](../CONTRIBUTING.md) para o checklist completo de pré-merge.