Engenharia de test-safety: o kill que não erra

A Lição 6 contou a história do vazamento de workers órfãos — 16 processos vitest perdidos, fixando ~1550% de CPU. Esta lição é a engenharia por baixo da correção: como um grupo de processo UNIX funciona, por que detached:true cria um, por que kill(-pgid) alcança todo descendente onde kill(pid) não consegue, e como a defesa em três camadas — um vitest.config.ts endurecido, mais um wrapper scripts/safe-test.mjs que mata o grupo de processo, mais uma varredura pós-execução — torna o vazamento estruturalmente impossível. É um arquivo pequeno, mas cada linha é sustentadora, e a lição generaliza para qualquer ferramenta que cria uma árvore de workers.

01 · O problema raiz: órfãos escapam do pai

O tinypool do Vitest roda testes em processos filhos (workers). Imagine um chefe (o processo pai) com vários funcionários (os workers). Se você demite só o chefe, os funcionários não somem — eles continuam trabalhando, agora sem ninguém para encerrá-los. É exatamente o que acontece num SO POSIX: se um teste trava sem teardown (um socket aberto, uma promise não resolvida, um interval vivo) e o pai é morto só por PID, os workers não morrem — eles são reparentados ao PID 1 (o processo init) e seguem rodando, cada um fixando um core.

A consequência crucial: matar o processo pai não basta. Você tem que matar a árvore inteira — e uma árvore que já reparentou ao PID 1 não é mais alcançável a partir do pai, porque o vínculo pai→filho que você usaria para alcançá-la deixou de existir.

02 · Anatomia de um grupo de processo (a estrutura que salva)

Em linguagem simples: um grupo de processo é como um sobrenome de família. Em vez de chamar cada pessoa pelo nome (um PID de cada vez), você chama "a família Silva" e todos respondem. No POSIX, esse "sobrenome" é o PGID (process group id), e existe uma forma de sinalizar a família inteira numa única chamada — desde que todos os workers compartilhem o mesmo PGID.

03 · A ideia central: kill(pid) vs kill(-pgid)

Aqui está o coração da lição, e cabe numa frase: um PID negativo é um grupo de processo. No POSIX, kill(pid, sig) sinaliza um processo; kill(-pgid, sig) sinaliza todo processo daquele grupo. Como detached:true tornou o filho um líder de grupo (PID == PGID), process.kill(-child.pid, …) alcança o vitest principal e todo fork tinypool numa única syscall.

Veja a mesma ideia no código real do wrapper. O killGroup sempre usa -child.pid (negativo); o try/catch apenas absorve o caso em que o grupo já se foi:

// scripts/safe-test.mjs:38-44
const killGroup = (signal) => {
  try {
    process.kill(-child.pid, signal);   // PID NEGATIVO = o grupo inteiro
  } catch {
    /* group already gone */
  }
};

Mas qual sinal mandar para o grupo? O wrapper usa dois, em ordem, e a diferença entre eles é a razão da ordem: SIGTERM pode ser capturado (um processo bem-comportado faz teardown ao recebê-lo); SIGKILL não pode ser capturado nem ignorado — o kernel encerra o processo na hora. Pedir com SIGTERM primeiro dá chance de limpeza; forçar com SIGKILL depois garante a morte de quem ignorou.

É exatamente a sequência das linhas 52-56 do safe-test.mjs: killGroup('SIGTERM'), depois — 5 s adiante — killGroup('SIGKILL'). O primeiro respeita quem ainda pode limpar; o segundo não negocia com quem travou.

04 · Camada 1 — faça um travamento FALHAR em vez de travar

A defesa em profundidade começa a montante: a melhor forma de não vazar é o travamento nunca acontecer. A config compartilhada do Vitest define timeouts limitados e o pool forks, para que um arquivo preso falhe rápido e seja morto à força no teardown — em vez de girar para sempre:

// vitest.config.ts:20-27 — o endurecimento anti-órfão
// Anti-orphan hardening: a hung test (server/socket/MCP/interval/unresolved
// promise with no teardown) must FAIL on a bounded timeout, never hang a
// worker forever. The `forks` pool isolates hangs in child processes that
// Vitest force-kills on teardown, so a stuck file cannot pin a CPU core.
testTimeout: 15_000,
hookTimeout: 15_000,
teardownTimeout: 10_000,
pool: 'forks',

Por que pool:'forks' e não as worker threads padrão? Um travamento dentro de uma thread pode emperrar o processo host; um travamento dentro de um fork (um processo de SO separado) é isolado — e "Vitest force-kills on teardown, so a stuck file cannot pin a CPU core" (vitest.config.ts:22-23). Os timeouts transformam uma espera infinita numa falha de teste: visível, limitada e vermelha no CI.

Por que 'forks' isola e 'threads' (o padrão) não? Uma thread divide o mesmo espaço de memória e o mesmo event loop do processo host — um loop preso numa thread pode emperrar o host inteiro. Um fork é um processo de SO separado, com memória e event loop próprios; quando ele trava, o host continua são e pode matá-lo à força no teardown. É a fronteira de isolamento que torna a camada 1 confiável:

05 · Camada 2 — o wrapper que possui um grupo de processo

A config sozinha não cobre toda fuga: um handle nativo que o Vitest não consegue ceifar, ou um pai morto com SIGKILL no meio da execução (um Ctrl-C impaciente, um OOM killer do SO). Então scripts/safe-test.mjs roda a suíte inteira no seu próprio grupo de processo e mata o grupo, não o PID. A chave, de novo, é detached:true:

// scripts/safe-test.mjs:34-36
// detached:true => POSIX setsid => the child leads a NEW process group, so
// `kill(-pid)` reaches every descendant (vitest main + all tinypool forks).
const child = spawn(bin, args, { stdio: 'inherit', detached: true });

O hard timeout: SIGTERM, depois SIGKILL, depois varredura

Um timer de wall-clock limitado escala educadamente-e-depois-à-força. Como demitir alguém: primeiro o aviso (SIGTERM, "encerre e limpe"), depois — se ignorar — a escolta para a saída (SIGKILL, 5 s depois), depois uma varredura, e sai com 124 (o código convencional de timeout):

// scripts/safe-test.mjs:46-58
let timedOut = false;
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 jeito
  setTimeout(() => {
    killGroup('SIGKILL');               // depois força, 5s depois
    sweep();
    process.exit(124);                 // conventional "timed out" code
  }, 5_000);
}, TIMEOUT_MS);
timer.unref();                          // não mantenha o event loop vivo só pelo timer

06 · A escalada na mão (passo a passo → agora você)

Você viu a escalada no código. Agora percorra-a na mão, devagar, com o caso do timeout — depois um exercício é seu. Recuperar a ordem dos sinais (não só vê-la pronta) é o que fixa de verdade.

07 · O fluxograma do safe-test.mjs (todos os caminhos de saída)

Junte tudo num único fluxograma. O safe-test.mjs tem quatro caminhos de saída — spawn falhou, sinal externo, timeout, saída normal — e todos terminam na varredura. Cada caminho carrega um exit code próprio, por convenção, para que o CI saiba o que aconteceu só pelo número. Esse é o contrato:

Agora siga as setas do fluxograma; cada losango é uma pergunta que escolhe o caminho.

Vale ver a corrida de perto, porque é um bug clássico de concorrência evitado por uma única linha. Quando o timeout dispara o SIGKILL, o filho morre — e morrer dispara o handler child.on('exit'). Ou seja: o mesmo evento (a morte do filho) ativaria dois caminhos que ambos chamam process.exit com códigos diferentes. O flag timedOut é o árbitro:

08 · Camada 3 — a varredura: pega o que já escapou

Resta um caso que nem a config nem o kill-do-grupo cobrem: se um worker reparentou ao PID 1 antes do kill-do-grupo disparar, ele não está mais no grupo — o kill(-pgid) não o alcança (ele saiu da família). A varredura de último recurso alcança, espelhando a rede manual do operador pgrep -f vitest | kill -9:

// scripts/safe-test.mjs:24-32
/** Last-resort net: kill any `vitest` the group-kill missed (e.g. already
 *  reparented to PID 1). Mirrors the operator net `pgrep -f vitest | kill -9`. */
const sweep = () => {
  try {
    execFileSync('pkill', ['-9', '-f', 'vitest'], { stdio: 'ignore' });
  } catch {
    /* nothing left to kill — pkill exits non-zero when no match */
  }
};

A diferença essencial: o kill-do-grupo casa por pertencimento (mesmo PGID); a varredura casa por nome (-f vitest). Por isso ela alcança até um órfão que já deixou o grupo. O try/catch existe porque pkill sai com código não-zero quando não há nada para matar — o que é o caso normal e desejável, não um erro.

A varredura roda em todo caminho de saída — spawn falhou, sinal, timeout e saída normal — para que o vazamento "must not accumulate" (safe-test.mjs:80). Mesmo numa saída limpa, o wrapper ainda chama killGroup('SIGKILL') para "reap any fork still lingering in the group" (l.79) e depois varre. Cinto e suspensório, porque o custo de um vazamento é horas de CPU fixada.

09 · Três camadas, lado a lado — e o que cada uma deixa passar

A tese da lição: nenhum mecanismo único é confiado a ser perfeito. Cada camada pega a maioria e entrega à próxima exatamente o caso que ela não consegue cobrir. O que a camada anterior deixa passar é a razão de existir da seguinte.

Sinta a escalada: o timer de timeout, passo a passo

Arraste para ver onde no relógio cada sinal dispara. A janela de graça entre SIGTERM e SIGKILL é fixa em 5 s (l.57); o TIMEOUT_MS é o que você ajusta (default 600.000):

A prova: o done-when da correção (verificação da Lição 06)

Uma correção de test-safety só está pronta quando provada na fronteira real — não basta "deve funcionar". A condição de pronto tem duas partes que precisam ser verdadeiras ao mesmo tempo: a suíte fica verde e pgrep -f vitest volta vazio depois. Verde sozinho não basta (poderia ter deixado órfãos); vazio sozinho não basta (poderia ter quebrado testes). As duas juntas são a prova.

10 · Como isso se encaixa

Esta lição não é um truque de UNIX isolado: é o endurecimento que nasceu de uma cicatriz e que hoje protege cada iteração da fábrica. A linha do tempo é direta — primeiro veio o incidente (Lição 06: 16 workers órfãos, ~1550% de CPU), e a engenharia desta lição (test:safe) foi a resposta que o tornou estruturalmente impossível. A partir daí, todo loop AFK que roda pnpm -w test herda essa rede automaticamente. Veja o fluxo da peça no maquinário:

Acenda o fluxo, passo a passo

Clique Próximo para seguir a peça pelo maquinário: a cicatriz que a originou, a peça em si, e cada lugar que ela passa a proteger. Recuperar a ordem (causa → peça → efeito) fixa o lugar dela na metodologia melhor do que vê-la pronta.

As peças que esta lição conecta

Cada link abaixo é uma peça vizinha no maquinário — siga o "porque conecta" para ver o fio:

11 · Na prática

Chega de teoria — rode você mesmo. O wrapper desta lição é exposto por um único script no package.json: "test:safe": "node scripts/safe-test.mjs" (verbatim). Sem argumentos, o safe-test.mjs roda o comando padrão pnpm -w test (a suíte inteira do workspace) dentro do seu próprio grupo de processo. O comando que você digita é:

# roda a suíte inteira sob o wrapper anti-órfão (config + kill-grupo + sweep)
pnpm test:safe

# saída esperada (resumida) — o vitest roda normalmente, e o wrapper
# faz a faxina silenciosa no fim (killGroup + sweep em TODO caminho de saída):
#   Test Files  NN passed (NN)
#        Tests  565 passed (565)
#   ...sem "[safe-test] HARD TIMEOUT" = nenhum timeout disparou
# exit code = o do vitest (0 se verde); 124 se tivesse estourado o timeout

O safe-test.mjs escreve [safe-test] HARD TIMEOUT after … no stderr só quando o timer estoura (default SAFE_TEST_TIMEOUT_MS=600000, 10 min). Numa run saudável você não vê linha nenhuma do wrapper — ele é invisível até precisar matar algo. O número de testes (565 acima) é ilustrativo: é o valor verificado na Lição 06; o seu pode diferir conforme o repositório cresce. [uncertain] a contagem exata de "Test Files" varia com o número de pacotes — confira a sua na saída real.

A prova de que a rede funcionou tem duas partes (o mesmo done-when da Lição 06): a suíte fica verde e, logo depois, pgrep -f vitest volta vazio. Verifique as duas, nesta ordem:

# 1) rode a suíte protegida
pnpm test:safe
# 2) imediatamente depois, confirme que NÃO sobrou nenhum vitest vivo
pgrep -fl vitest
# saída esperada: (vazio) — pgrep sai com código 1 quando não há match,
# e "vazio" É a prova de que o sweep/kill-grupo não deixou órfão.

Note o que não existe: não há alembic test nem flag de CLI para isto. Test-safety vive na camada de build (o package.json + vitest.config.ts + scripts/), não na CLI do produto — é a fundação que mantém pnpm -r typecheck && pnpm -r build && pnpm -w test seguro de rodar em loop, que é o baseline de toda mudança de código no repositório.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.

Confusões comuns