Blog

Testing Timezones Without Waiting for Next Tuesday

September 6, 2026Xerat023 min read
Share
Testing Timezones Without Waiting for Next Tuesday

A specific, recurring category of production incident: everything worked in testing, and then a real user in a different timezone — or the clocks changing for Daylight Saving Time — produced a result nobody saw coming, because the bug only exists at a specific moment that testing happened not to occur near.

Why timezone bugs concentrate at specific moments

A date-only bug (treating a date as if it always has a time component, or vice versa) can misbehave any day of the year. A genuine timezone bug is often much narrower: it only shows up for users in a timezone whose offset from UTC isn't a whole number of hours (a handful of real timezones sit at a 30 or 45 minute offset), or only during the specific week when a particular region's clocks shift for Daylight Saving Time — meaning "we tested this in March and it worked fine" tells you almost nothing about whether it'll behave correctly the week clocks change in November.

A few of the specific, recurring failure patterns:

  • Storing a local time without its offset, then interpreting it as UTC (or as the server's local time) later — silently shifting every timestamp by whatever the original offset was.
  • A "day" boundary computed in the wrong timezone. A report meant to cover "today" for a user in Tokyo, computed using the server's US-based timezone, can be a report for entirely the wrong calendar day from that user's point of view.
  • An appointment or reminder scheduled "at 9am" that shifts by an hour the week DST changes, because it was stored as a fixed UTC instant instead of "9am in this timezone, whatever UTC offset that currently maps to."
  • Date arithmetic that assumes every day is 24 hours, which is false exactly twice a year in regions that observe DST — the day the clocks change is 23 or 25 hours long, and code that adds 86,400 seconds to get "the same time tomorrow" gets it wrong specifically on those two days.

Why "just test it in March" doesn't catch this

Because these bugs are concentrated at specific real-world moments (a DST transition, a non-hour-offset timezone, a leap-year February), a test suite that only ever runs with "today's real date and the server's real timezone" simply never exercises the conditions that trigger them. The bug isn't rare because it's unlikely — it's rare in your testing because your testing never happens to be looking at the one week a year it would show up.

Making the date and timezone controllable

The fix is the same shape as most of the timing-dependent bugs in this series: don't wait for the calendar to cooperate, control the input directly. A mocked API response with a deliberately chosen, awkward timestamp — a date right at a DST transition, an offset like +05:45 (a real timezone offset, not a convenient whole hour) — run against your actual date-handling code, tells you in a five-minute test what waiting for the actual transition would tell you once a year, if anyone happened to be watching when it happened. Dynamic templates with a fixed, deliberately awkward received_at or scheduled_for value are a direct way to hand your client code exactly the date it's least prepared for, on whatever day you happen to be testing.

X

Xerat02

Building MockBase.