Test across timezone boundaries
CI usually runs in UTC, which hides every local-time bug. A green suite in TZ=UTC and a red one in TZ=America/New_York is the signature of an unmodelled local-time dependency.
Procedure
- Find code that reads the ambient zone rather than an injected one:
rg -n 'TZ|localtime|mktime|strftime|gettimezone|Calendar\.getInstance' src/ | head -40
- Run the suite under a matrix of zones. A one-liner sweep catches the common cases:
for z in UTC America/New_York Europe/London Asia/Tokyo Australia/Sydney Asia/Kolkata; do
echo "== $z"; TZ=$z pytest -q || break
done
- Pin a transition day inside the test, not just the zone — the DST bug only fires on the changeover:
import os, datetime
from zoneinfo import ZoneInfo
def test_rollover_on_dst_day(monkeypatch):
monkeypatch.setenv("TZ", "America/New_York")
day = datetime.datetime(2026, 3, 8, 3, 0, tzinfo=ZoneInfo("America/New_York"))
assert billing_period_end(day).isoformat().endswith("Z")
- Include a half-hour offset (India
+05:30) and a quarter-hour one (Nepal+05:45) to catch offset truncation. - Test the season boundary both ways: run the DST cases for
2026-03-08and2026-11-01(US) and2026-03-29/2026-10-25(EU). - Add the matrix to CI as a job, not a manual step:
strategy:
matrix:
tz: [UTC, America/New_York, Asia/Kolkata]
env:
TZ: ${{ matrix.tz }}
- If a case genuinely must fail under some zone, mark it and link the ticket — do not let the sweep
breaksilently.
Pitfalls
export TZin the parent shell does not override aTZbaked into the container or the test's own fixtures; assert the effective zone in a first test.- Node reads
process.env.TZat firstDateuse; setting it mid-test may not take effect unless you restart the worker. - Testing only the summer date misses the winter offset and vice versa; both offsets must be exercised.
- Databases may evaluate
now()in the server zone regardless of the clientTZ; test the query, not just the application. - A passing sweep in-process can hide a subprocess that inherits a different zone; cover subprocess paths too.
Verification
for z in UTC America/New_York Asia/Kolkata; do TZ=$z pytest -q tests/test_billing.py -k timezone || echo "FAIL $z"; done
Every zone passes, and a deliberately naive datetime.now() case fails in America/New_York = the matrix has teeth. Report: "suite green in 6 zones; DST-day cases 2026-03-08 / 2026-11-01 covered; CI matrix job added."