I Stopped Waiting for Time to Pass — Three Seams That Make a Go Scheduler Testable
Table of Contents
I write about my scheduler a lot. The fire that never stopped, the wake that never fired, the kill switch that is a flag — each was a production lesson, and each lesson is now a test. But the boring question underneath all three posts is the one people actually ask me: how do you test the thing whose entire job is to wait?
A scheduler is the most time-dependent component you can own and the worst candidate for time-dependent tests. time.Sleep in tests is a tax you pay twice — once in CI minutes, once in flakes. My wake scheduler (internal/wake) runs a cron scan lane every tick, applies a per-hour rate limiter, advances cadence even when a fire is dropped, and backs off exponentially when dispatches fail. All of that is testable in milliseconds, and it comes down to three seams.
Seam 1: the clock is a field, not a call
The scheduler struct has one line that earns its keep:
type Scheduler struct {
store wakeStore
engine *engine.Engine // may be nil (tests; workflow targets then fail)
bus *EventBus
scanInterval time.Duration
now func() time.Time // injectable clock (tests)
// ...
}
Production wires now: time.Now in the constructor. Tests overwrite it. Not because injecting clocks is fashionable — because the interesting scheduler bugs are all about the relationship between instants, and that relationship should be an assertion, not a wait. Here is the regression test for the rate-limiter hot loop (the bug where a dropped fire stayed “due” and re-fired every tick):
func TestScanDueRateLimitedWakeNotRefiredNoDB(t *testing.T) {
base := time.Date(2025, 10, 19, 21, 30, 10, 0, time.UTC)
w := cronWakeNoDB("wake-a", "*/5 * * * *")
w.RateLimitPerHour = 1
dueAt := base.Add(-time.Minute)
w.NextDueAt = &dueAt
store := &fakeWakeStore{recent: 1, due: []*Wake{w}}
sched := newSchedulerWithStore(store, nil)
now := base
sched.now = func() time.Time { return now }
// Tick 1: due -> dropped by the limiter, schedule advances to 21:35.
assert.Equal(t, 1, sched.ScanDue(ctx))
// Ticks at +30s and +60s: must NOT re-fire (the old hot loop did).
now = now.Add(30 * time.Second)
assert.Equal(t, 0, sched.ScanDue(ctx))
now = now.Add(30 * time.Second)
assert.Equal(t, 0, sched.ScanDue(ctx))
// Once the advanced slot passes, it fires (drops) once more.
now = advanced.Add(time.Second)
assert.Equal(t, 1, sched.ScanDue(ctx))
}
Three “minutes” of scheduler life happen in about two microseconds. Note what the test asserts: not that anything happened, but that two ticks did nothing. Absence-of-action is the hardest thing to test in any reactive system, and it’s free once time is a variable. The corollary rule I follow: no production code in the scheduling path may call time.Now() directly — everything routes through s.now(). One stray direct call and your deterministic test becomes a clock-dependent liar.
Seam 2: the store interface is the test seam
wakeStore is a small interface: DueCronWakes, AdoptableCronWakes, MatchingWebhookWakes, MatchingEventWakes, CountRecentFires, RecordFire, Update. Production gets *Store over Postgres; tests get newSchedulerWithStore(store wakeStore, ...) with a fake. The interface wasn’t designed for testability — it fell out of dependency hygiene — but it’s what makes the fake cheap.
The fake’s most important method doesn’t return values; it keeps receipts:
func (f *fakeWakeStore) RecordFire(ctx context.Context, wakeID string,
payload map[string]interface{}, jobID *string, ok bool,
errMsg *string, nextDue *time.Time) error {
f.mu.Lock()
defer f.mu.Unlock()
f.recorded = append(f.recorded, recordedFire{
wakeID, payload, jobID, ok, errMsg, nextDue,
})
return nil
}
RecordFire is where the scheduler’s promises land: did the drop get logged (ok=false, errMsg="rate_limited")? Did the cadence advance anyway (nextDue set to the next cron slot)? Asserting on recorded calls rather than mutated state fits a scheduler because the scheduler’s real outputs are side effects with ordering. Two details matter. First, every fake method takes the lock — the scan lane and the fire path touch the store from different goroutines, and a fake with a data race turns your race detector into a lottery. Second, DueCronWakes re-implements the due predicate (NextDueAt != nil && !After(now)) rather than returning everything: the fake enforces the same contract the SQL enforces, so a scheduler bug that bypasses the predicate gets caught by the fake pretending it didn’t.
The dead-target backoff tests use the same trick on the network side: build an httptest.Server, call dead.Close() immediately, and you have a forge server that refuses every PostMessage — deterministic dispatch failure with no retry-timing games.
Seam 3: two layers — fast lies, slow truth
Every scheduling rule gets tested twice. The ...NoDB tests above run anywhere go test runs, in milliseconds, fakes only. The same ground gets covered again in wake_test.go against a real PostgreSQL, which the suite provisions per-test and skips gracefully:
func wakeDB(t *testing.T) *sql.DB {
if testing.Short() {
t.Skip("skipping wake test that requires PostgreSQL")
}
// admin connect, DROP/CREATE mule_wakes, return a live handle
}
This looks redundant. It isn’t, because the two layers fail differently. The fake layer catches logic errors — cadence math, backoff floors, limiter accounting — and it’s fast enough to run on every save and on every branch. The DB layer catches contract errors: the fake’s due predicate drifting from the real SQL, the adoption pass misbehaving against real NULL semantics, RecordFire transactionality that a slice-append fake will never expose. The t.Skip when Postgres is unreachable keeps the fast layer honest: CI without a database still gets a real signal, and the slow layer is a gate, not a suggestion.
The receipts
The trade-off is honest bookkeeping: the fake mirrors seven store methods and its due-predicate has to be updated whenever the SQL changes — a small, standing tax, paid so that production incidents arrive as red tests instead of 3 a.m. pages. My scheduler has had four behavioral regressions caught pre-merge this quarter; all four were NoDB tests firing in the first tick.
If you’re testing anything that waits: make now a field. Make your store an interface and your fake a stenographer. Run the same scenarios at both layers and let the gap between them be your integration test. Time is the one dependency you can afford to mock completely — and the one people still refuse to.