Engenharia de test-safety: o kill que não pode falhar

O tinypool do Vitest roda os testes em processos-filho (workers). Se um teste pendura sem teardown — um socket aberto, uma promise não resolvida, um setInterval vivo — e o pai é morto só pelo PID, os workers não morrem: eles são reparenteados ao PID 1 (o init) e continuam girando, cada um prendendo um núcleo.

Matar o processo-pai não basta. Você tem de matar a árvore inteira — e uma árvore que já reparenteou não é mais alcançável a partir do pai, porque o pai já morreu. Esse é o coração do bug.

Toda a correção gira em torno de uma única regra POSIX. kill(pid, sig) sinaliza um processo. kill(-pgid, sig) — com o número negativo — sinaliza todos os processos daquele grupo. O sinal de menos é a diferença entre matar o pai e matar a família.

Veja a hierarquia de processos viva. Clique entre os dois modos de kill e observe o que sobrevive:

PID positivo mira um processo e abandona os filhos; PID negativo mira o grupo inteiro. detached:true é o que cria esse grupo.

A primeira defesa impede o hang de acontecer logo de cara. A config compartilhada fixa timeouts limitados e o pool forks, então um arquivo travado falha rápido e é force-killado no teardown, em vez de girar para sempre:

export default defineConfig({
  test: {
    environment: 'node',
    // Anti-orphan hardening: um teste pendurado (server/socket/MCP/interval/
    // promise não resolvida sem teardown) DEVE falhar num timeout limitado,
    // nunca pendurar um worker para sempre. O pool 'forks' isola hangs em
    // processos-filho que o Vitest force-killa no teardown.
    testTimeout: 15_000,
    hookTimeout: 15_000,
    teardownTimeout: 10_000,
    pool: 'forks',
  },
});

A config sozinha não cobre todo escape (um handle nativo, um pai morto por SIGKILL no meio da run). Então scripts/safe-test.mjs roda a suíte inteira em seu próprio process group e mata o grupo, não o PID. A chave é detached:true:

// detached:true => POSIX setsid => o filho lidera um NOVO process group,
// então kill(-pid) alcança todo descendente (vitest main + todos os forks).
const child = spawn(bin, args, { stdio: 'inherit', detached: true });

const killGroup = (signal) => {
  try {
    process.kill(-child.pid, signal);   // PID NEGATIVO = o grupo inteiro
  } catch {
    /* grupo já se foi */
  }
};

Repare na simetria com a Camada 1: lá, o número era um timeout; aqui, o número-chave é o sinal de menos em -child.pid. Um caractere — e ele decide se o kill atinge um processo ou uma família inteira.

Um cronômetro de wall-clock limitado escala educadamente-depois-à-força. Primeiro SIGTERM (deixa limpar), SIGKILL 5 segundos depois (força), então uma varredura, e sai com 124 (o código convencional de "estourou o tempo"):

const timer = setTimeout(() => {
  timedOut = true;
  process.stderr.write(
    `\n[safe-test] HARD TIMEOUT after ${TIMEOUT_MS}ms — killing process group -${child.pid}\n`,
  );
  killGroup('SIGTERM');              // pede com jeitinho
  setTimeout(() => {
    killGroup('SIGKILL');            // depois força, 5s mais tarde
    sweep();
    process.exit(124);              // código convencional de "timed out"
  }, 5_000);
}, TIMEOUT_MS);
timer.unref();                       // não segura o event loop só pelo timer

O valor do timeout vem do ambiente, com um default seguro de 10 minutos:

const TIMEOUT_MS = Number(process.env.SAFE_TEST_TIMEOUT_MS ?? 600_000); // 600000 = 10 min

Se um worker reparenteou para o PID 1 antes do kill-de-grupo, ele já não está no grupo — o kill-de-grupo não o alcança. A varredura de último recurso alcança, espelhando a rede manual do operador pgrep -f vitest | kill -9:

/** Rede de último recurso: mata qualquer `vitest` que o kill-de-grupo
 *  perdeu (ex.: já reparenteado ao PID 1). */
const sweep = () => {
  try {
    execFileSync('pkill', ['-9', '-f', 'vitest'], { stdio: 'ignore' });
  } catch {
    /* nada para matar — pkill sai != 0 quando não há match */
  }
};

A varredura roda em todo caminho de saída — saída normal, sinal e timeout — então o vazamento "não pode acumular" (safe-test.mjs:80). Numa saída limpa, o wrapper ainda chama killGroup('SIGKILL') para "reapear qualquer fork ainda persistindo no grupo", e então varre. Cinto e suspensório, porque o custo de um vazamento é horas de CPU presa.

child.on('exit', (code, signal) => {
  if (timedOut) return;       // o caminho do timeout é dono da saída
  clearTimeout(timer);
  killGroup('SIGKILL');          // reapeia qualquer fork ainda no grupo
  sweep();                       // e qualquer um que fugiu para o PID 1
  process.exit(typeof code === 'number' ? code : signal ? 1 : 0);
});

Cada camada tem uma falha conhecida — que é exatamente o trabalho da camada seguinte. O piso é a varredura por nome.

A falha de cada camada é o trabalho da próxima. Isso é defesa em profundidade: nenhum mecanismo isolado é confiado como perfeito, e o modo de falha (um núcleo preso por horas) é severo o bastante para justificar a redundância.

Você abre o monitor de atividade e vê processos vitest velhos comendo CPU depois que a suíte já "terminou". Qual camada deveria ter pego cada cenário?