What Test Verifies Timestamp Time-Zone Handling?
From the earlier reference collection. Read the current software blog.
Test that timestamps with explicit offsets resolve to the same expected instant, even when their displayed local times differ.
Make the instant the assertion
A focused time-zone test parses timestamps that include explicit UTC offsets, then compares the resulting instants with a known reference. The purpose is to catch code that treats a wall-clock reading as if it were already UTC, or that discards the offset during parsing.
For example, 2026-03-14T09:30:00-07:00 and 2026-03-14T16:30:00Z describe the same instant. Parse both through the same production path and assert that their normalized values are equal. Also check a timestamp with a positive offset, such as 2026-03-14T18:30:00+02:00, which represents that same instant.
Use offsets that expose mistakes
Include more than one offset sign and a non-whole-hour offset, such as +05:30, if the application accepts it. A test using only UTC can pass even when the parser ignores offsets entirely. Likewise, a test comparing formatted strings may fail for harmless display differences or pass while the underlying instant is wrong.
Keep the input format aligned with the application contract. If timestamps must contain an offset, test that a timestamp with no offset is rejected or handled by the explicitly documented default. Do not quietly assume the machine’s local time zone: a developer laptop and a CI runner may use different settings.
Check the round trip and boundary
If the application serializes timestamps, parse an offset timestamp, serialize it in the chosen canonical format, and parse it again. Assert that the instant is unchanged. The output may use Z instead of the original offset; that is fine when the contract promises instant preservation rather than preservation of the original spelling.
Add a boundary case near midnight. For instance, 2026-03-15T00:15:00+02:00 falls on the previous UTC date. This catches code that compares calendar dates before applying the offset. Keep expected values explicit so the test does not calculate its answer using the same conversion logic it is meant to verify.
Keep failures understandable
Name tests around the behavior, such as “equivalent offsets resolve to the same instant” and “positive offset can cross the UTC date boundary.” When a case fails, report the input and expected normalized instant. That makes it clear whether parsing, normalization, or serialization changed.
A small table of carefully chosen examples is often more useful than a large random set for this rule. The finished test should establish the invariant: different local representations of one moment compare as the same moment, while genuinely different instants remain distinct.