Um teste que espera cinco segundos para descobrir se uma tool expirou testa o relógio da máquina, não a política do agente. O caso fica mais perigoso quando a chamada chega ao serviço externo, o efeito acontece e a resposta se perde antes do prazo terminar.

Para testar essa fronteira, injete o atraso no executor falso, controle os timers com node:test e observe o efeito do domínio. O guia sobre verificar o efeito de uma tool call antes de repetir cobre a reconciliação. Este post mostra como transformar os estados dessa decisão em testes rápidos e reproduzíveis.

O objetivo não é provar que um provedor, uma fila ou uma API de produção se comporta sempre da mesma forma. A fixture prova que o seu runtime distingue timeout antes do efeito, conclusão antes do prazo e timeout depois do commit.

Diagrama mostra uma tool, um prazo controlado no teste e um estado desconhecido depois do timeout.

Resposta curta

  • Não use sleep real para testar o prazo. Avance o relógio falso do runner.
  • Injete a falha na fronteira que recebe o AbortSignal, mantendo a política de retry e o contador de efeitos reais na fixture.
  • Verifique o estado externo, não só a mensagem final do agente.
  • Se o efeito aconteceu antes do timeout, marque o resultado como desconhecido e reconcilie antes de repetir.

O que um teste de timeout precisa provar?

O teste precisa responder duas perguntas diferentes: o chamador recebeu uma resposta dentro do prazo e o sistema externo sofreu um efeito? A primeira pergunta pertence ao runtime. A segunda pertence ao executor ou ao estado que ele consegue consultar.

A documentação do Dev Proxy, da Microsoft, sobre testar falhas de tools separa o que um teste unitário do wrapper consegue observar do que só uma execução do agente mostra. Ela também lista os caminhos que costumam escapar do caso feliz: a tool pode travar, o agente pode repetir a chamada ou o código pode esconder o erro.

Um timeout não tem uma única posição na linha do tempo. Há pelo menos três casos úteis:

Caso O que o teste injeta Decisão esperada
Antes do efeito A tool não começou a mutação Timeout sem efeito; retry pode ser considerado pela política
Depois do efeito A mutação aconteceu, mas a resposta não chegou Estado desconhecido; consultar antes de repetir
Depois da resposta O resultado chegou antes do prazo Sucesso; nenhum timeout deve ser registrado

O artigo sobre timeout e reconciliação de tool calls já explica por que unknown é diferente de failure. Aqui, unknown vira uma asserção observável: o teste conta a mutação e impede que o runner trate qualquer timeout como ausência de efeito.

Torne o prazo injetável

Uma função de teste não deve esconder o timer dentro de uma espera impossível de controlar. O wrapper abaixo cria um AbortController, rejeita a corrida quando o prazo termina e passa o sinal à tool. O resultado identifica o timeout sem tentar decidir se uma operação externa foi aplicada.

function runToolWithTimeout({ tool, timeoutMs }) {
  const controller = new AbortController();
  let timer;

  const operation = Promise.resolve()
    .then(() => tool(controller.signal))
    .then(
      (value) => ({ status: "completed", value }),
      (error) => ({ status: "error", error }),
    );

  const deadline = new Promise((resolve) => {
    timer = setTimeout(() => {
      controller.abort(new Error("tool_timeout"));
      resolve({ status: "timeout" });
    }, timeoutMs);
  });

  return Promise.race([operation, deadline]).finally(() => {
    clearTimeout(timer);
  });
}

O AbortSignal só interrompe a operação se a implementação da tool o observar e repassar a bibliotecas como fetch. O Node.js documenta AbortSignal.timeout() como uma forma nativa de criar um sinal que expira, mas a fixture usa um timer explícito para que o runner consiga avançar o relógio e também para separar a política do domínio da API escolhida.

Esse wrapper não confirma o estado remoto. Se a tool fizer uma escrita antes de rejeitar, o resultado local continuará sendo timeout. A camada seguinte precisa consultar a pós-condição, usar a chave de idempotência do serviço ou deixar o caso pendente.

Simule os três momentos sem sleep

Uma fixture útil controla dois instantes: quando a mutação acontece e quando a resposta chegaria. O signal cancela timers que ainda não começaram. Se o timer do efeito já rodou, o abort não apaga o efeito, que é exatamente a situação que costuma faltar nos testes.

function scriptedTool({ commitAtMs, responseAtMs, onEffect }) {
  return (signal) => new Promise((resolve, reject) => {
    let committed = false;
    const effectTimer = setTimeout(() => {
      committed = true;
      onEffect();
    }, commitAtMs);
    const responseTimer = setTimeout(() => {
      clearTimeout(effectTimer);
      resolve({ receiptId: "receipt-1" });
    }, responseAtMs);

    signal.addEventListener("abort", () => {
      if (!committed) clearTimeout(effectTimer);
      clearTimeout(responseTimer);
      if (signal.reason?.message === "tool_timeout") {
        reject(signal.reason);
      }
    }, { once: true });
  });
}

Quando o timeout ocorre antes de commitAtMs, o listener cancela o timer do efeito. Quando o commit já aconteceu, o listener só impede a resposta tardia. O contador de efeitos continua em um, mesmo que o agente tenha visto apenas timeout.

Use node:test para avançar o relógio

O runner nativo do Node.js oferece timers simulados. A documentação do test runner mostra context.mock.timers.enable() e tick() para disparar timers sem esperar a duração real. O arquivo abaixo é executável com node --test tool-timeout.test.mjs depois de incluir as duas funções anteriores.

import assert from "node:assert/strict";
import { test } from "node:test";

test("timeout antes do commit não deixa efeito", async (t) => {
  t.mock.timers.enable({ apis: ["setTimeout"] });
  let effects = 0;

  const pending = runToolWithTimeout({
    timeoutMs: 100,
    tool: scriptedTool({
      commitAtMs: 200,
      responseAtMs: 400,
      onEffect: () => { effects += 1; },
    }),
  });

  await Promise.resolve();
  t.mock.timers.tick(100);
  assert.deepEqual(await pending, { status: "timeout" });
  t.mock.timers.tick(300);
  assert.equal(effects, 0);
});

test("timeout depois do commit preserva o estado ambíguo", async (t) => {
  t.mock.timers.enable({ apis: ["setTimeout"] });
  let effects = 0;

  const pending = runToolWithTimeout({
    timeoutMs: 100,
    tool: scriptedTool({
      commitAtMs: 50,
      responseAtMs: 500,
      onEffect: () => { effects += 1; },
    }),
  });

  await Promise.resolve();
  t.mock.timers.tick(50);
  await Promise.resolve();
  t.mock.timers.tick(50);

  assert.deepEqual(await pending, { status: "timeout" });
  assert.equal(effects, 1);
});

test("resposta antes do prazo não vira timeout", async (t) => {
  t.mock.timers.enable({ apis: ["setTimeout"] });
  let effects = 0;

  const pending = runToolWithTimeout({
    timeoutMs: 100,
    tool: scriptedTool({
      commitAtMs: 200,
      responseAtMs: 50,
      onEffect: () => { effects += 1; },
    }),
  });

  await Promise.resolve();
  t.mock.timers.tick(50);
  assert.deepEqual(await pending, {
    status: "completed",
    value: { receiptId: "receipt-1" },
  });
  assert.equal(effects, 0);
});

Os três casos verificam a ordem, não a passagem de tempo. O primeiro prova que a política pode encerrar uma leitura lenta sem efeito. O segundo prova que um timeout não autoriza uma segunda mutação. O terceiro impede que um timer antigo ou uma asserção ampla classifique um sucesso como falha.

Como testar o retry sem duplicar a mutação?

Não coloque o retry dentro do mesmo teste que deveria provar o timeout. Primeiro fixe a observação: timeout com zero efeitos, ou timeout com um efeito já aplicado. Depois teste a política de recuperação usando uma função de verificação que devolve confirmed, not_found ou unknown.

O caso mais importante é este:

  1. O executor aceita a operação.
  2. A fixture registra o efeito.
  3. A resposta é perdida antes de chegar ao agente.
  4. O runtime recebe timeout.
  5. A política consulta o estado externo.
  6. Um resultado confirmed encerra a ação sem uma segunda chamada.

O post sobre testar idempotência de uma API sem duplicar efeitos aprofunda a proteção do receptor. O teste de timeout continua necessário porque uma chave de idempotência sem uma asserção sobre o efeito pode existir no código e nunca ser exercitada.

Onde testes de timeout costumam mentir?

Esperar o tempo real

Um setTimeout de cinco segundos torna a suíte lenta e ainda pode passar sem exercitar o cancelamento. Use timers simulados para provar a transição e deixe um teste de integração menor verificar a biblioteca ou transporte que realmente aceita o AbortSignal.

Mockar o agente inteiro

Se o mock já devolve completed ou timeout, o parser, o dispatcher, o contador de efeitos e a política ficam fora do caminho. Controle a dependência lenta e mantenha a fronteira de decisão real.

Contar somente chamadas

Uma chamada pode ter produzido um efeito antes de falhar. O contador ajuda, mas a asserção principal deve consultar o estado da fixture, como uma lista de mensagens, uma linha de banco ou um recibo associado ao actionId.

Rejeitar e limpar tudo

Cancelar uma promessa local não desfaz uma mutação remota. O post sobre cancelar um agente quando uma tool trava explica a diferença entre interromper a espera e apagar um efeito. O teste deve manter essa diferença visível.

Confundir relógio com deadline

O guia sobre testar código dependente do tempo em JavaScript separa data corrente de timers. Aqui, o prazo da tool é um limite de execução. Se o agente também tem deadline do run, teste esse limite em outra camada ou documente qual timer está sendo avançado.

Checklist para o CI

  • O timeout pode ser disparado sem sleep real?
  • O teste injeta a falha na fronteira que recebe o sinal de cancelamento?
  • Há um caso antes do efeito, um depois do commit e um de resposta dentro do prazo?
  • A suíte verifica o estado externo, e não apenas a mensagem final?
  • Um timeout depois do commit impede retry automático até a reconciliação?
  • A fixture usa o mesmo actionId ou chave de idempotência nas tentativas?
  • O teste deixa claro o que ele não prova sobre o provedor ou serviço real?

Perguntas frequentes

AbortSignal.timeout() basta para testar uma tool?

Não por si só. Ele cria um sinal que expira, mas o teste ainda precisa provar que a tool observa o sinal e que a política classifica o resultado. Para avançar o relógio de forma explícita, um wrapper com timer injetável pode ser mais fácil de verificar.

Um timeout antes da resposta significa que o efeito não aconteceu?

Não. Se a operação externa já foi aceita, o efeito pode existir mesmo que o cliente não tenha recebido o recibo. Modele esse caso e consulte a pós-condição antes de repetir.

Posso testar um agente com um modelo real?

Pode, mas essa é outra camada. O teste determinístico deve proteger parser, timeout, trace, política e efeito. Um eval com modelo real pode acrescentar variação de escolha, mas não deve substituir as asserções do runtime.

Como este artigo foi produzido

Samuel Fajreldines é o responsável por este artigo. A pesquisa comparou a documentação do Node.js para AbortSignal e timers simulados, a orientação da Microsoft sobre falhas de tools e a documentação de timeout de tools do OpenAI Agents SDK. As discussões públicas ajudaram a escolher o caso “timeout depois do commit”; não foram usadas como prova técnica.

Executei a fixture em memória com Node.js v25.5.0 em 17 de novembro de 2026. Ela cobre timeout antes do efeito, timeout depois do commit e resposta antes do prazo. Isso prova o comportamento declarado da fixture, não a semântica de um provedor, banco, fila ou API externa.

Usei o RemoteCode como ferramenta minha para organizar contexto e revisar a estrutura. Ele não executou a fixture nem forneceu evidência de produção.

Fontes consultadas