Un test que espera cinco segundos para saber si una tool agotó el tiempo está probando el reloj de la máquina, no la política del agente. El caso se vuelve más peligroso cuando la llamada llega al servicio externo, el efecto ocurre y la respuesta se pierde antes de que termine el plazo.
Para probar esta frontera, inyecta el retraso en un executor falso, controla los timers con node:test y observa el efecto del dominio. La guía para verificar si una tool call tuvo efecto antes de repetirla cubre la reconciliación. Este artículo muestra cómo convertir esas decisiones en tests rápidos y repetibles.
El objetivo no es demostrar que un proveedor, una cola o una API de producción siempre se comporta igual. La fixture demuestra que tu runtime distingue un timeout antes del efecto, una respuesta antes del plazo y un timeout después del commit.
Respuesta breve
- No uses
sleepreal para probar un plazo. Avanza el reloj falso del runner.- Inyecta el fallo en la frontera que recibe el
AbortSignal, manteniendo la política de retry y el contador de efectos reales dentro de la fixture.- Comprueba el estado externo, no solo el mensaje final del agente.
- Si el efecto ocurrió antes del timeout, marca el resultado como desconocido y reconcilia antes de repetir.
¿Qué debe demostrar un test de timeout?
El test debe responder dos preguntas distintas: ¿el llamador recibió una respuesta antes del plazo y el sistema externo recibió un efecto? La primera pregunta pertenece al runtime. La segunda pertenece al executor o al estado que puede consultar.
La guía de Microsoft Dev Proxy sobre cómo probar fallos de tools de agentes separa lo que puede observar un test unitario del wrapper de lo que solo muestra un agente en ejecución. También enumera caminos que suelen quedar fuera del caso feliz: la tool puede quedarse bloqueada, el agente puede repetir la llamada o el código puede ocultar el error.
Un timeout puede ocupar más de una posición útil en la línea de tiempo:
| Caso | Qué inyecta el test | Decisión esperada |
|---|---|---|
| Antes del efecto | La tool todavía no inició la mutación | Timeout sin efecto; la política puede considerar un retry |
| Después del efecto | La mutación ocurrió, pero la respuesta no llegó | Estado desconocido; consultar antes de repetir |
| Después de la respuesta | El resultado llegó antes del plazo | Éxito; no debe registrarse un timeout |
El artículo sobre verificar el efecto de una tool call antes de repetirla explica por qué unknown es distinto de failure. Aquí, unknown se convierte en una aserción observable: el test cuenta la mutación e impide que el runner trate cada timeout como prueba de ausencia.
Haz que el plazo sea inyectable
Una función de test no debe ocultar su timer dentro de una espera que no se puede controlar. El wrapper siguiente crea un AbortController, resuelve la carrera cuando termina el plazo y pasa la señal a la tool. El resultado identifica el timeout sin decidir si una operación externa se aplicó.
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);
});
}
Un AbortSignal solo interrumpe la operación si la implementación de la tool lo observa y lo pasa a librerías como fetch. Node.js documenta AbortSignal.timeout() como una forma nativa de crear una señal que expira, pero esta fixture usa un timer explícito para que el runner pueda avanzar el reloj y para mantener separada la política de dominio de la API elegida.
Este wrapper no confirma el estado remoto. Si la tool escribe antes de rechazar, el resultado local sigue siendo timeout. La siguiente capa debe consultar la poscondición, usar la clave de idempotencia del servicio o dejar el caso pendiente.
Simula los tres momentos sin sleep
Una fixture útil controla dos instantes: cuándo ocurre la mutación y cuándo llegaría la respuesta. El signal cancela los timers que todavía no empezaron. Si el timer del efecto ya se ejecutó, abortar no borra el efecto. Ese es el caso que muchas suites de caso feliz no cubren.
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 });
});
}
Cuando el timeout ocurre antes de commitAtMs, el listener cancela el timer del efecto. Cuando el commit ya ocurrió, el listener solo evita la respuesta tardía. El contador de efectos se queda en uno aunque el agente solo haya visto timeout.
Usa node:test para avanzar el reloj
El runner incluido en Node.js ofrece timers simulados. La documentación del test runner muestra context.mock.timers.enable() y tick() para disparar timers sin esperar la duración real. El archivo siguiente se ejecuta con node --test tool-timeout.test.mjs después de incluir las dos funciones anteriores.
import assert from "node:assert/strict";
import { test } from "node:test";
test("el timeout antes del commit no deja efecto", 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("el timeout después del commit conserva el estado ambiguo", 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("la respuesta antes del plazo no se convierte en 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);
});
Los tres casos verifican el orden, no el paso del tiempo. El primero demuestra que la política puede terminar una lectura lenta sin efecto. El segundo demuestra que un timeout no autoriza una segunda mutación. El tercero evita que un timer antiguo o una aserción amplia clasifique un éxito como fallo.
¿Cómo probar el retry sin duplicar la mutación?
No pongas el retry dentro del mismo test que debe demostrar el timeout. Primero fija la observación: timeout con cero efectos o timeout con un efecto ya aplicado. Después prueba la política de recuperación con una función de verificación que devuelva confirmed, not_found o unknown.
El recorrido importante es este:
- El executor acepta la operación.
- La fixture registra el efecto.
- La respuesta se pierde antes de llegar al agente.
- El runtime recibe
timeout. - La política consulta el estado externo.
- Un resultado
confirmedtermina la acción sin una segunda llamada.
La guía para probar la idempotencia de una API profundiza en la protección del receptor. El test de timeout sigue siendo necesario porque una clave de idempotencia puede existir en el código sin que ninguna aserción compruebe el efecto.
¿Dónde suelen mentir los tests de timeout?
Esperar en tiempo real
Un setTimeout de cinco segundos vuelve lenta la suite y todavía puede pasar sin ejercitar la cancelación. Usa timers simulados para demostrar la transición y deja un test de integración pequeño para la librería o el transporte que realmente acepta el AbortSignal.
Mockear el agente completo
Si el mock ya devuelve completed o timeout, el parser, el dispatcher, el contador de efectos y la política quedan fuera del recorrido. Controla la dependencia lenta y mantén real la frontera de decisión.
Contar solo las llamadas
Una llamada puede haber producido un efecto antes de fallar. El contador ayuda, pero la aserción principal debe revisar el estado de la fixture, como una lista de mensajes, una fila de base de datos o un recibo asociado a un actionId.
Rechazar y limpiar todo
Cancelar una promesa local no deshace una mutación remota. El artículo sobre cancelar un agente cuando una tool se bloquea explica la diferencia entre interrumpir la espera y borrar un efecto. Mantén esa diferencia visible en el test.
Confundir reloj con deadline
La guía para probar código JavaScript dependiente del tiempo separa la fecha actual de los timers. Aquí, el plazo de la tool es un límite de ejecución. Si el agente también tiene un deadline para todo el run, prueba ese límite en otra capa o documenta qué timer estás avanzando.
Checklist para CI
- ¿El timeout puede dispararse sin
sleepreal? - ¿El test inyecta el fallo en la frontera que recibe la señal de cancelación?
- ¿Existe un caso antes del efecto, otro después del commit y otro con respuesta dentro del plazo?
- ¿La suite comprueba el estado externo y no solo el mensaje final?
- ¿Un timeout después del commit bloquea el retry automático hasta la reconciliación?
- ¿La fixture usa el mismo
actionIdo clave de idempotencia en los intentos? - ¿El test deja claro qué no puede demostrar sobre el proveedor o servicio real?
Preguntas frecuentes
¿AbortSignal.timeout() basta para probar una tool?
No por sí solo. Crea una señal que expira, pero el test todavía debe demostrar que la tool observa la señal y que la política clasifica el resultado. Un wrapper con un timer inyectable puede hacer más fácil la verificación mediante avance explícito del reloj.
¿Un timeout antes de la respuesta significa que el efecto no ocurrió?
No. Si la operación externa ya fue aceptada, el efecto puede existir aunque el cliente no recibiera el recibo. Modela ese caso y consulta la poscondición antes de repetir.
¿Puedo probar un agente con un modelo real?
Sí, pero esa es otra capa. El test determinista debe proteger el parser, el timeout, el trace, la política y el efecto. Un eval con un modelo puede añadir variación de decisión, pero no debe reemplazar las aserciones del runtime.
Cómo se produjo este artículo
Samuel Fajreldines es responsable de este artículo. La investigación comparó la documentación de Node.js para AbortSignal y timers simulados, la orientación de Microsoft sobre fallos de tools y la documentación de OpenAI Agents SDK sobre timeouts de tools. Las discusiones públicas ayudaron a elegir el caso de timeout después del commit, pero no se usaron como prueba técnica.
Ejecuté la fixture en memoria con Node.js v25.5.0 el 17 de noviembre de 2026. Cubre un timeout antes del efecto, un timeout después del commit y una respuesta antes del plazo. Eso demuestra el comportamiento declarado de la fixture, no la semántica de un proveedor, una base de datos, una cola o una API externa.
Usé RemoteCode como herramienta mía para organizar el contexto y revisar la estructura. No ejecutó la fixture ni proporcionó evidencia de producción.
Fuentes consultadas
- Node.js, "Global objects: AbortSignal.timeout()", consultado el 17/11/2026.
- Node.js, "Test runner", consultado el 17/11/2026.
- Microsoft Learn, "How to test what your AI agent does when its tools fail", consultado el 17/11/2026.
- OpenAI Agents SDK, "Tools", consultado el 17/11/2026.