Booking time zones: test missing and repeated local times before launch
Test booking time zones with missing and repeated local-time fixtures before launch. Includes an executed Python example and clear limits.
A customer choosing 01:30 is not always choosing one moment. During a clock change, that local time can occur twice. Another local time can fail to occur at all. If a booking form accepts the label without checking the business time zone, a confirmation can represent a different appointment from the one the customer intended.
This guide uses a small Python fixture to distinguish an ordinary local time, a missing time and a repeated time. It is a synthetic engineering example, not a test of Omnistu's booking products or a claim about any deployed customer system.
Write down the product rule before writing the conversion
For a single appointment, ask for the business's IANA time zone and resolve the selected local time to an explicit instant. A fixed offset such as -05:00 describes an offset, not the full rules of America/New_York. Python's zoneinfo documentation explains how its IANA-backed implementation handles changing offsets.
Choose a rule for each unusual result:
- Zero matching instants: do not silently confirm the requested label. Reject it with an explanation or offer a clearly labeled alternative under the product's stated policy.
- One matching instant: use that instant and retain the zone needed to explain it.
- Two matching instants: ask which occurrence the customer means, or expose only the occurrence the product explicitly supports. Show the offset as well as the local label.
These are product choices. A time library cannot decide whether an appointment may move or which repeated slot a business offers.
Why attaching a zone is not enough
Python's fold attribute distinguishes the earlier and later readings of a repeated local time. PEP 495 also explains that constructors can produce invalid instances; construction is not a promise that a requested wall time existed.
The fixture therefore tries both fold values, converts each candidate to UTC, then converts it back to the named zone. A candidate is kept only when the local date and clock time survive the round trip. A set removes duplicate UTC instants for ordinary times.
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
def candidates(local_text, zone_name):
local = datetime.fromisoformat(local_text)
if local.tzinfo is not None:
raise ValueError("expected a local datetime without an offset")
zone = ZoneInfo(zone_name)
choices = set()
for fold in (0, 1):
instant = local.replace(tzinfo=zone, fold=fold).astimezone(timezone.utc)
roundtrip = instant.astimezone(zone).replace(tzinfo=None)
if roundtrip == local:
choices.add(instant)
return sorted(choices)
This helper accepts a local datetime without an offset by design. Offset-bearing API input should use a separately defined contract rather than being silently reinterpreted as a local appointment label. Invalid date strings and unknown zones also need clear application-level validation errors.
Four fixtures with explicit expected results
The accompanying script was executed with Python 3.10.12 using the environment's installed time-zone data on November 18, 2026. It produced these results:
| Local input | Zone | Matching UTC instants |
|---|---|---|
| 2026-02-04 09:00 | America/New_York | 2026-02-04 14:00 UTC |
| 2026-03-08 02:30 | America/New_York | None |
| 2026-11-01 01:30 | America/New_York | 2026-11-01 05:30 UTC and 06:30 UTC |
| 2026-11-01 09:00 | Asia/Kolkata | 2026-11-01 03:30 UTC |
The test also rejected offset-bearing input. It asserted fixed expected values instead of merely asserting that converting forward and backward returned something.
This is evidence for these fixtures in this environment. It is not an exhaustive proof for every historical transition or every time-zone database version. Python obtains zone data from the system or the tzdata package. Keep that dependency available, record its version in a reproducible deployment and rerun the relevant fixtures when it changes.
Carry the resolved choice through the whole booking
Validation is wasted if another layer reinterprets the label. Preserve the resolved instant, original named zone and the selected occurrence in the booking contract. Confirmations, staff agendas, reschedule screens and reminders should refer to that same choice. A customer's viewing zone can change the displayed clock time without changing the appointment instant.
Recurring business hours need a separate rule. "Every Monday at 09:00 in the business zone" is a local-time recurrence, not necessarily a fixed number of elapsed hours between every occurrence. Materialize and validate each occurrence under the chosen scheduling policy. Do not apply this one-off helper as an entire recurrence engine.
Acceptance checks beyond the helper
In a staging booking flow, run the missing and repeated inputs from two viewer zones. Verify that the form's explanation survives submission, refresh and reopening. Check the stored instant against the confirmation and staff agenda. Rescheduling must preserve the old appointment if the new input is refused.
Also test duration separately. A service lasting 60 elapsed minutes can cross an offset change and display a surprising local end time. Decide whether duration means elapsed time or wall-clock labels, then assert that policy. Resource conflicts, opening hours, payment holds and reminder delivery remain independent checks.
The useful launch question is not "does the calendar support time zones?" It is "can we show exactly what the customer chose when the clock label is missing or repeated?"
Sources and method
- Python 3.10 zoneinfo documentation: IANA zones, fold behavior and zone-data dependencies.
- PEP 495: Local Time Disambiguation: ambiguous and missing local times, invalid instances and fold semantics.
- Python 3.10 datetime documentation: aware datetimes, fixed offsets and conversion behavior.
Written with AI assistance. The synthetic fixture was executed locally; no customer appointments, external booking APIs or live analytics were used.