Probar y observar un cron

Un cron programado para 0 3 * * * plantea un problema práctico incómodo: no vas a esperar a las tres de la madrugada UTC para ver si tu handler funciona, y menos aún en cada iteración del desarrollo. La tarea programada es, por naturaleza, difícil de observar: nadie la pide, nadie recibe su respuesta, y tanto su éxito como su fracaso son silenciosos. Esta lección cierra ese hueco por los dos extremos: en local, cómo disparar el scheduled handler bajo demanda y simular cualquier expresión; en producción, cómo leer la huella que deja cada ejecución para saber que corrió, cuándo y si terminó bien.

Disparar el reloj a voluntad

Normalmente wrangler dev levanta tu Worker y sirve el handler fetch. Para probar scheduled necesitas una puerta que, en local, imite al programador de Cloudflare. Esa puerta la abre una bandera:

npx wrangler dev --test-scheduled

Con ella, el servidor de desarrollo registra una ruta especial, /__scheduled, que al recibir una petición invoca tu scheduled handler como si el cron acabara de dispararse. El bucle de desarrollo se vuelve inmediato: editas, guardas, golpeas el endpoint y lees los console.log en la misma terminal.

curl "http://localhost:8787/__scheduled"

El servidor de desarrollo imprime además el desenlace de cada disparo —si el handler resolvió limpiamente o lanzó una excepción— junto a tus propios registros, así que un fallo no pasa inadvertido mientras iteras. Editas, guardas, golpeas el endpoint y lees el resultado sin salir de la terminal.

El disparo manual es perfecto para iterar, pero no para una suite que corra en integración continua. Para eso, la integración de Vitest para Workers te deja invocar el handler programado desde una prueba y afirmar sobre sus efectos —lo que escribió, lo que encoló— sin tocar la red ni esperar a un horario:

import { env, SELF } from "cloudflare:test";
import { expect, it } from "vitest";

it("el cron deja su latido", async () => {
  const r = await SELF.scheduled({ cron: "0 8 * * *" });
  expect(r.outcome).toBe("ok");
  expect(await env.KV.get("cron:ultimo-ok")).not.toBeNull();
});

El endpoint /__scheduled

Cuando un mismo Worker atiende varios horarios y ramifica con switch (controller.cron), necesitas ejercitar cada rama por separado. El endpoint acepta dos parámetros de consulta para ello. cron fija el controller.cron —y por tanto selecciona la rama—; time fija el controller.scheduledTime en milisegundos desde época, para probar lógica que dependa de la fecha de forma determinista.

# simula el trigger de las 08:00 (0 8 * * *); el espacio se codifica como +
curl "http://localhost:8787/__scheduled?cron=0+8+*+*+*"

# fija ademas el instante programado, para logica dependiente de la fecha
curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*&time=1735732800000"

Así conviertes un handler dependiente del reloj en algo tan comprobable como una función pura: cada rama tiene su URL, cada fecha crítica su time, y ninguna prueba exige que el mundo llegue a una hora concreta.

Y como el endpoint responde con normalidad, puedes automatizarlo: un pequeño script que recorra tus expresiones y golpee /__scheduled con cada una es una prueba de humo barata que ejercita todas las ramas de tu switch en segundos.

Observar la ejecución real

Lo que corre en local no garantiza lo que corre desplegado. En producción dispones de dos lentes complementarias. La primera es en vivo: wrangler tail transmite los eventos de tu Worker según ocurren, y cada disparo del cron aparece como un evento con su resultado.

npx wrangler tail --format pretty

Verás tus console.log, cualquier excepción lanzada y el desenlace de la invocación —ok, canceled, o un error de límite—. Es la herramienta para atrapar un cron en el acto, especialmente si su cadencia es corta y no quieres esperar al panel.

Conviene saber leer esos desenlaces, porque cada uno cuenta una historia distinta: ok es una invocación que terminó sin lanzar; canceled suele indicar que se cortó antes de completar —por ejemplo, al superar el techo de tiempo—; y un desenlace de excepción apunta a un throw sin capturar en tu código. Ninguno dice lo mismo sobre por qué tu cron no dejó el efecto que esperabas.

La segunda lente es histórica: en el dashboard, dentro de tu Worker, el panel de Cron Events lista las ejecuciones programadas recientes con su marca de tiempo, la expresión que las disparó, el estado —éxito o error— y la duración. Es el registro de auditoría que responde a las tres preguntas que de verdad importan: ¿corrió a la hora prevista?, ¿terminó bien?, ¿cuánto tardó?

Conviene recordar que Cron Events conserva un historial reciente, no eterno: es un panel para vigilancia continua y diagnóstico a corto plazo, no un archivo permanente. Si necesitas auditoría a largo plazo, exporta tus propios registros con la telemetría que dejas viva en ctx.waitUntil.

Entre --test-scheduled para explorar a mano, la prueba en integración continua para blindar contra regresiones y Cron Events para vigilar producción, tienes el cron cubierto en sus tres fases: desarrollo, integración y operación.

Ninguna de las dos lentes sirve de nada si tu handler no deja rastro propio. El hábito que se paga solo es la autoinstrumentación: que cada ejecución escriba, como último gesto, una huella durable —un latido— con la que después puedas afirmar no solo si hubo errores, sino si hubo ejecución.

async scheduled(controller, env, ctx) {
  try {
    await tareaPrincipal(env);
    ctx.waitUntil(
      env.KV.put("cron:ultimo-ok", String(controller.scheduledTime)),
    );
  } catch (e) {
    console.error("cron fallo", e);
    throw e; // que el desenlace en Cron Events sea un error visible
  }
}

Ese throw final es deliberado: al propagar la excepción, la invocación se marca como error en Cron Events en lugar de fingir un éxito. Y el latido en KV habilita la alerta que de verdad protege un cron —la de la ausencia—: si cron:ultimo-ok no se ha movido en el plazo esperado, es que algo dejó de dispararse, y esa es justo la avería que nadie te va a reportar.

flowchart TB
subgraph Local
  Editar[editar y guardar] --> Curl[curl a __scheduled]
  Curl --> Term[logs en la terminal]
end
subgraph Produccion
  Cron[el cron dispara] --> Tail[wrangler tail en vivo]
  Cron --> Panel[Cron Events historico]
end