Skip to content

test: DST & timezone guarantees (spec 3.1-3.4) + CI in UTC#540

Merged
merencia merged 1 commit into
mainfrom
test/dst-guarantees
Jun 17, 2026
Merged

test: DST & timezone guarantees (spec 3.1-3.4) + CI in UTC#540
merencia merged 1 commit into
mainfrom
test/dst-guarantees

Conversation

@merencia

Copy link
Copy Markdown
Member

First PR of the DST hardening work (spec 05-spec-dst, staged into separate PRs). This one locks in the behavior we already have with an exhaustive guarantee matrix, and makes the test environment honest.

What's here

  • DST guarantee matrix (src/time/dst.test.ts, 30 cases) covering §3.1 spring-forward, §3.2 fall-back, §3.3 negative controls, §3.4 long stress, across the spec's reference zones: New York, Lord Howe (30-min DST), Chatham (45-min offset), Havana (midnight DST), Auckland (southern hemisphere), London, Tokyo, UTC.
  • Sequences are asserted against the spec's invariants, not magic numbers: strictly monotonic in absolute time, consecutive gap >= the expression interval (no rapid-fire), and every returned instant satisfies the expression — which by construction proves no non-existent spring-forward wall-clock ever fires.
  • CI runs in TZ=UTC, plus a dedicated Timezone independence job that runs the whole suite under TZ=America/Sao_Paulo to prove a task with an explicit timezone is unaffected by the system timezone.

Note

The current matcher (after the recent MatcherWalker/localTimeToTimestamp rewrite) already passes all 30 scenarios — including 30-min and 45-min zones, midnight gaps, and 1000-iteration per-second/minute monotonicity. This PR is characterization: it proves and pins the guarantees so future changes can't regress them.

Skipped (depend on features that don't exist yet)

  • FI-6 startAt/stopAt, FI-7 getNextRuns(n), FI-2 LockProvider — out of scope for DST.

Next PRs

  • PR2: utcOffset (fixed numeric offset, no DST) + its scenarios (CN-3).
  • PR3: fuzz testing (§3.6).
  • DST model docs (§1 → nodecron.com) — separate, in the site repo.

Note: touches .github/workflows/, so merge via the GitHub UI.

Full suite green: 310 tests under both TZ=UTC and TZ=America/Sao_Paulo.

Add a DST guarantee matrix covering spring-forward gaps, fall-back overlaps,
negative controls, and long stress enumerations across the spec's reference
zones (New York, Lord Howe 30-min, Chatham 45-min offset, Havana midnight,
Auckland southern hemisphere, London, Tokyo, UTC). Sequences are checked for the
core invariants: strictly monotonic in absolute time, gaps >= the expression's
interval (no rapid-fire), and every returned instant satisfies the expression
(which proves no non-existent spring-forward wall-clock ever fires). The current
matcher already satisfies every scenario; these tests prove and pin it.

Run the unit suite under TZ=UTC, and add a dedicated job that runs it under
TZ=America/Sao_Paulo to prove a task with an explicit timezone is unaffected by
the system timezone.
@merencia
merencia merged commit 3e8edca into main Jun 17, 2026
6 checks passed
@merencia
merencia deleted the test/dst-guarantees branch June 17, 2026 17:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant