Vai al contenuto principale
failproofai dispone di due suite di test: unit test (veloci, con mock) e test end-to-end (invocazioni reali di subprocess).

​
Esecuzione dei test

# Esegui tutti gli unit test una sola volta
bun run test:run

# Esegui gli unit test in modalità watch
bun run test

# Esegui i test E2E (richiede setup - vedi sotto)
bun run test:e2e

# Verifica i tipi senza compilare
bunx tsc --noEmit

# Linting
bun run lint

​
Unit test

Gli unit test si trovano in __tests__/ e utilizzano Vitest con happy-dom. 
__tests__/
  hooks/
    builtin-policies.test.ts      # Logica delle policy per ogni builtin
    hooks-config.test.ts          # Caricamento della config e merge dello scope
    policy-evaluator.test.ts      # Iniezione di parametri e ordine di valutazione
    custom-hooks-registry.test.ts # Registry di globalThis add/get/clear
    custom-hooks-loader.test.ts   # Loader ESM, importazioni transitive, gestione errori
    manager.test.ts               # Operazioni install/remove/list
  components/
    sessions-list.test.tsx        # Componente lista sessioni
    project-list.test.tsx         # Componente lista progetti
    ...
  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 unit test per una policy

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 binario failproofai reale come subprocess, inviano un payload JSON a stdin e effettuano asserzioni sull’output stdout e il codice di uscita. Questo verifica il percorso di integrazione completo che utilizza Claude Code.

​
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': 
bun build src/index.ts --outdir dist --target node --format cjs
Quindi esegui i test: 
bun run test:e2e
Ricompila dist/ ogni volta che modifichi l’API pubblica dei hook (src/hooks/custom-hooks-registry.ts, src/hooks/policy-helpers.ts, o src/hooks/policy-types.ts).

​
Struttura dei test E2E

__tests__/e2e/
  helpers/
    hook-runner.ts      # Avvia il binario, invia payload JSON, cattura codice di uscita + stdout + stderr
    fixture-env.ts      # Directory temp isolate per test con file di config
    payloads.ts         # Factory di payload conformi a Claude per ogni tipo di evento
  hooks/
    builtin-policies.e2e.test.ts   # Ogni policy builtin con subprocess reale
    custom-hooks.e2e.test.ts       # Caricamento e valutazione di custom hook
    config-scopes.e2e.test.ts      # Merge della configurazione tra project/local/global
    policy-params.e2e.test.ts      # Iniezione di parametri per ogni policy parametrizzata

​
Utilizzo degli helper E2E

FixtureEnv - ambiente isolato per ogni test: 
import { createFixtureEnv } from "../helpers/fixture-env";

const env = createFixtureEnv();
// env.cwd    - directory temporanea; passa come payload.cwd per raccogliere .failproofai/policies-config.json
// env.home   - directory home isolata; nessun vero ~/.failproofai in conflitto

env.writeConfig({
  enabledPolicies: ["block-sudo"],
  policyParams: {
    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
  },
});
createFixtureEnv() registra la pulizia afterEach automaticamente. runHook - invoca il binario: 
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 già pronti: 
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

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

DecisioneCodice di uscitastdout
PreToolUse deny0{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}
PostToolUse deny0{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}
Instruct (non-Stop)0{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}
Stop instruct2stdout vuoto; ragione in stderr
Allow0stringa vuota

​
Config di Vitest

I test E2E utilizzano vitest.config.e2e.mts con:
  • environment: "node" - nessuna global del browser necessaria
  • pool: "forks" - vera isolazione dei processi (i test avviano subprocess)
  • testTimeout: 20_000 - 20s per test (startup del binario + valutazione hook)
Il pool forks è importante: i worker basati su thread condividono globalThis, il che può interferire con i test che avviano subprocess. I fork basati su processi evitano questo problema.

​
CI

L’esecuzione CI completa (bun run lint && bunx tsc --noEmit && bun run test:run && bun run build) è richiesta per essere approvata prima di fare merge. La suite E2E viene eseguita come un job CI separato in parallelo. Consulta Contributing per la checklist completa pre-merge.