Scheduler — test client - Refract Documentation

The test scheduler client (SchedulerClientType.TEST, package tooling-scheduler-test) runs schedule handlers on demand in backend tests. It does not register BullMQ job schedulers and does not fire cron ticks.

Why it exists

Production uses BullMQ job schedulers in the consumer process. Backend Jest suites need the same schedule handlers without Redis, without a running consumer, and without waiting for cron. The test client is that adapter — similar to MailerClientType.LOCAL or other test doubles in the tooling system.

Behavior

API	Test client	BullMQ client
`registerSchedules(tools)`	No-op (`success: true`)	Reconciles job schedulers from `tools.scheduler.schedules`
`runScheduleNow(name, tools)`	Runs handler once	Not available
Wall-clock cron	None	Redis job schedulers on `schedulerQueueName`
Config `schedules[]`	Optional (ignored for timing)	Required array (may be empty)

Handlers live in apps/backend/src/tools/scheduler/schedules/ and are shared between both clients.

Configuration

Only apps/backend/src/configuration/test.ts:

scheduler: {
  client: SchedulerClientType.TEST,
},

Dev/staging/prod use SchedulerClientType.BULLMQ with connection, schedulerQueueName, schedulerTickJobName, and schedules[]. See BullMQ scheduler.

Using in tests

const result = await tools.scheduler.runScheduleNow(
  ScheduleName.MY_SCHEDULE,
  tools,
);

expect(result.success).toBe(true);

The handler receives { scheduleName, firedAt } and tools, same as a production tick. Use buildEnqueueJobId from shared when enqueueing from the handler. When tools.logger / tools.metrics are present, runScheduleNow emits scheduler-test logs and scheduler.run_now.* metrics (see Scheduler overview monitoring table).

Mental model

BullMQ  →  consumer + Redis  →  cron fires  →  handler(tick, tools)
Test    →  Jest only         →  you call runScheduleNow  →  handler(tick, tools)

What’s next?

Scheduler overview — handlers, registry, adding schedules.
BullMQ scheduler — production Redis client and config options.
Configuration — env-specific tools.* config.

Getting Started

Architecture

Frontend

Deployment

Quality

Reference

Scheduler — test client

Why it exists

Behavior

Configuration

Using in tests

Mental model

What’s next?

​Why it exists

​Behavior

​Configuration

​Using in tests

​Mental model

​What’s next?

Why it exists

Behavior

Configuration

Using in tests

Mental model

What’s next?