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.
Resposta curta
- Não use
sleepreal 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:
- O executor aceita a operação.
- A fixture registra o efeito.
- A resposta é perdida antes de chegar ao agente.
- O runtime recebe
timeout. - A política consulta o estado externo.
- Um resultado
confirmedencerra 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
sleepreal? - 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
actionIdou 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
- Node.js, "Global objects: AbortSignal.timeout()", consultado em 17/11/2026.
- Node.js, "Test runner", consultado em 17/11/2026.
- Microsoft Learn, "How to test what your AI agent does when its tools fail", consultado em 17/11/2026.
- OpenAI Agents SDK, "Tools", consultado em 17/11/2026.