> ## 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. # Test > Test unitari, test end-to-end e helper per i test failproofai ha due suite di test: **test unitari** (veloci, con mock) e **test end-to-end** (invocazioni reali di subprocess). *** ## Esecuzione dei test ```bash theme={null} # Esegui tutti i test unitari una volta bun run test:run # Esegui i test unitari in modalità watch bun run test # Esegui i test E2E (richiede setup - vedi sotto) bun run test:e2e # Type-check senza compilare bunx tsc --noEmit # Lint bun run lint ``` *** ## Test unitari I test unitari si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.dev) con `jsdom`. ```text theme={null} __tests__/ hooks/ builtin-policies.test.ts # Policy logic per ogni builtin hooks-config.test.ts # Caricamento config e scope merging policy-evaluator.test.ts # Param injection e evaluation order custom-hooks-registry.test.ts # globalThis registry add/get/clear custom-hooks-loader.test.ts # ESM loader, transitive imports, error handling manager.test.ts # Operazioni install/remove/list components/ sessions-list.test.tsx # Componente sessions list project-list.test.tsx # Componente project list ... 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 ``` ### Scrivere un test unitario per una policy ```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()); }); }); ``` *** ## Test end-to-end I test E2E invocano il vero binario `failproofai` come subprocess, inviano un payload JSON su stdin e verificano l'output su stdout e il codice di uscita. Questo testa il percorso di integrazione completo che Claude Code utilizza. ### Setup I test E2E eseguono il binario direttamente dal codice sorgente del repository. Prima della prima esecuzione, compila il bundle CJS che i file di custom hook utilizzano quando importano da `'failproofai'`: ```bash theme={null} bun build src/index.ts --outdir dist --target node --format cjs ``` Quindi esegui i test: ```bash theme={null} bun run test:e2e ``` Ricompila `dist/` ogni volta che modifichi la public hook API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`). ### Struttura del test E2E ```text theme={null} __tests__/e2e/ helpers/ hook-runner.ts # Spawn del binario, pipe del payload JSON, cattura exit code + stdout + stderr fixture-env.ts # Directory temporanea isolata per test con file config payloads.ts # Factory di payload accurati di Claude per ogni event type hooks/ builtin-policies.e2e.test.ts # Ogni builtin policy con vero subprocess custom-hooks.e2e.test.ts # Caricamento e valutazione di custom hook config-scopes.e2e.test.ts # Config merging tra project/local/global policy-params.e2e.test.ts # Parameter injection per ogni policy parametrizzata ``` ### Utilizzo degli helper E2E **`FixtureEnv`** - ambiente isolato per ogni test: ```typescript theme={null} import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - directory temp; passa come payload.cwd per leggere .failproofai/policies-config.json // env.home - home dir isolata; nessuna leakage reale da ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], policyParams: { "block-sudo": { allowPatterns: ["sudo systemctl status"] }, }, }); ``` `createFixtureEnv()` registra la pulizia `afterEach` automaticamente. **`runHook`** - invoca il binario: ```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`** - factory di payload pronti all'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) ``` ### Scrivere un test 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 vuoto }); }); ``` ### Forme di risposta E2E | Decisione | Exit code | stdout | | ------------------- | --------- | --------------------------------------------------------------------------------------- | | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | | Stop instruct | `2` | stdout vuoto; motivo in stderr | | Allow | `0` | stringa vuota | ### Config Vitest I test E2E utilizzano `vitest.config.e2e.mts` con: * `environment: "node"` - nessun browser global necessario * `pool: "forks"` - vera isolazione dei processi (i test spawnnano subprocess) * `testTimeout: 20_000` - 20s per test (avvio binario + hook eval) Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che spawnnano subprocess. I fork basati su processo evitano questo problema. *** ## CI L'esecuzione CI completa (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) è richiesta prima del merge. La suite E2E viene eseguita come job CI separato in parallelo. Vedi [Contributing](../CONTRIBUTING.md) per la lista di controllo completa pre-merge.