AI debugging: test a local day across daylight saving

Name the timezone and the meaning of a report date

Imagine a support dashboard whose daily report is defined by the customer’s calendar in America/New_York. Each stored event already identifies an instant with an offset. The request contains a calendar date and an IANA timezone name. Include events from local midnight at the start of that date up to, but not including, the next local midnight. The example does not parse user-entered local appointment times.

That contract differs from a rolling 24-hour report. Before changing any code, ask whether the product wants a named date in a customer’s timezone or a fixed elapsed duration ending now. Both are reasonable features. Swapping one for the other can produce a plausible total while answering the wrong question, especially when the clocks change.

Python distinguishes aware timestamps from naive ones. A naive value does not carry enough information to identify an instant without an additional interpretation. This example rejects it instead of assuming the server’s local timezone. Python datetime: aware values and timezone conversion Record the report zone explicitly so the same request does not change meaning when deployed to another machine.

Choose an event in the hour the shortcut loses

An assistant proposes converting the report’s starting midnight to UTC, then adding 24 hours for the end. On November 1, 2026 in New York, the first boundary is 04:00 UTC. The next local midnight is November 2 at 05:00 UTC. An event at 04:30 UTC on November 2 is still part of the November 1 local report, but the 24-hour shortcut excludes it.

Put those literal UTC values in the reproduction before writing a fix. Avoid computing the expected end with the same helper you are testing. The key comparison is not whether the program emits an ISO string; it is whether it assigns that late event to the correct report date. Keep an event exactly at the following midnight as a separate exclusion case.

ZoneInfo supplies the zone rules used in this example, including daylight-saving transitions. It reads system timezone data or the first-party tzdata package; some systems, especially Windows, need that package installed. A missing database is an environment failure, not evidence that the arithmetic is correct or incorrect. Python zoneinfo: IANA rules and timezone data

Construct each local midnight before converting to UTC

Run the following self-contained script in Python 3.11 or newer with IANA timezone data available. On a machine without that data, install tzdata in your project environment first. The implementation constructs the next calendar date rather than assuming how many elapsed hours separate the two midnights. It compares instants only after conversion to UTC.

The code also checks an ordinary day and the spring transition. The expected UTC boundaries are written explicitly. The elapsed-hour checks subtract UTC values: Python’s datetime rules for arithmetic with the same tzinfo differ from elapsed-time subtraction across changing offsets, so converting first keeps this measurement aligned with the claim. Python datetime: aware values and timezone conversion

from datetime import date, datetime, time, timedelta, timezone
from zoneinfo import ZoneInfo

UTC = timezone.utc

def utc_bounds(day, zone_name):
    zone = ZoneInfo(zone_name)
    start = datetime.combine(day, time.min, zone)
    end = datetime.combine(day + timedelta(days=1), time.min, zone)
    return start.astimezone(UTC), end.astimezone(UTC)

def belongs_to_day(event, day, zone_name):
    if event.tzinfo is None or event.utcoffset() is None:
        raise ValueError('event must identify an instant')
    start, end = utc_bounds(day, zone_name)
    return start <= event.astimezone(UTC) < end

def instant(text):
    return datetime.fromisoformat(text)

zone = 'America/New_York'
cases = [
    (date(2026, 2, 1), '2026-02-01T05:00:00+00:00', '2026-02-02T05:00:00+00:00', 24),
    (date(2026, 3, 8), '2026-03-08T05:00:00+00:00', '2026-03-09T04:00:00+00:00', 23),
    (date(2026, 11, 1), '2026-11-01T04:00:00+00:00', '2026-11-02T05:00:00+00:00', 25),
]
for day, start_text, end_text, hours in cases:
    start, end = utc_bounds(day, zone)
    assert (start, end) == (instant(start_text), instant(end_text))
    assert (end - start).total_seconds() == hours * 3600
    assert belongs_to_day(start, day, zone)
    assert belongs_to_day(end - timedelta(microseconds=1), day, zone)
    assert not belongs_to_day(end, day, zone)
    assert not belongs_to_day(start - timedelta(microseconds=1), day, zone)

day = date(2026, 11, 1)
late = instant('2026-11-02T04:30:00+00:00')
start, _ = utc_bounds(day, zone)
assert not (start <= late < start + timedelta(hours=24))
assert belongs_to_day(late, day, zone)
first = instant('2026-11-01T01:30:00-04:00')
second = instant('2026-11-01T01:30:00-05:00')
assert first.astimezone(UTC) != second.astimezone(UTC)
assert belongs_to_day(first, day, zone)
assert belongs_to_day(second, day, zone)
try:
    belongs_to_day(datetime(2026, 11, 1, 12), day, zone)
except ValueError:
    pass
else:
    raise AssertionError('accepted a naive event')
print('Local-day boundaries and all inclusion checks passed.')

Keep both occurrences of a repeated clock time

The two 01:30 timestamps in the script look similar, but their offsets identify different instants. Both belong in the same local-date report. Deduplicating events by a formatted local clock string would merge distinct observations. If the domain needs deduplication, use its actual event identity rather than a display value.

Our input contract avoids asking the filter to resolve ambiguous local text. If a separate form accepts a date and a clock time without an offset, it must decide which occurrence the user means when the hour repeats. ZoneInfo supports the fold distinction for such repeated times. Python zoneinfo: IANA rules and timezone data That is a separate input-design problem, not a reason to silently guess inside the report filter.

Likewise, do not fabricate an instant for a local time skipped when clocks move forward. This article starts from already identified instants and illustrates New York dates whose day boundaries are unambiguous. Other zones and historical changes can require an explicit policy for unusual or missing local midnights; these fixtures are not a universal calendar specification.

Check storage, filtering, and display as separate steps

After the small reproduction passes, trace one real request through the application. Confirm the account’s timezone reaches the boundary builder unchanged, the database query uses the same inclusive-start and exclusive-end rules, and the UI labels the report with the requested local date. A correct helper cannot repair a caller that still sends a UTC calendar date by mistake.

Inspect serialization too. An offset lost while formatting or parsing can turn a well-defined instant into an ambiguous local value. Log a safe synthetic fixture at each boundary during development rather than relying on the wall clock at the moment of the test. The test should reproduce the same inclusion decision in winter, summer, and on a build server in another zone.

Keep elapsed timers separate. Timeouts, retry budgets, and performance measurements have different requirements from calendar grouping. Reusing the report helper for a timer would introduce a new conceptual bug. Name helpers around the product meaning they implement, such as local-day boundaries, so an assistant has less room to infer the wrong kind of time.

Ask the assistant to defend the endpoints and exclusions

Give the assistant the failing event, the literal expected boundaries, and the timezone contract. Ask it to explain why the end changes by an hour while the selected local date does not. Request a narrow patch to boundary construction and tests, leaving storage migration and display redesign outside that change.

Review its suggested assertions before accepting them. A test that checks only an event near noon can pass under both the broken and corrected algorithms. A test that computes its expected end by adding 24 hours repeats the defect. Keep exact boundaries, an event in the affected late hour, and the naive-input rejection because they answer different questions.

Common questions about timezone boundary bugs

Why not group by the UTC date? That is correct only when the requested report is defined in UTC. A customer-local report deliberately uses a different boundary. Store instants consistently, then apply the selected calendar interpretation when grouping.

Should the end be 23:59:59? No. An exclusive next-midnight boundary includes every supported precision without inventing a last representable fraction of a second. It also lets adjacent reports share a boundary without counting an event twice.

Does this prove every timezone works? No. The executed fixtures establish the stated New York cases and offset-aware input behavior. Support additional zones with their own boundary policies and fixtures, and keep timezone data available in every deployment environment.