Timezone-Aware Seed Factories for DST Crossings

DST boundary failures are the cockroaches of test data engineering: they disappear before you can inspect them, they show up in prod at 2am, and they're almost never caused by the code you're looking at. A seed factory that emits datetime.now() or Faker().date_time() without an explicit timezone will generate timestamps that look fine in UTC-only CI, then silently shift by one hour when a staging environment runs in America/Chicago or Europe/London. The failure isn't in your assertion logic — it's baked into the seed.

The root problem is that most seed factories treat timestamps as scalars rather than domain values. A timestamp near a DST boundary isn't just a number; it's a value with a specific behavioral contract — fold points, gap points, UTC offset transitions — that your factory must respect or deliberately avoid. As covered in the companion piece on timezone-naive timestamps breaking interval assertions, naive datetimes propagate silently through ORMs and serializers until they explode in an assertion three layers away.

By the end of this article you'll have a working pattern for a DST-aware seed factory in Python, a parametrize harness for the four boundary classes that matter, and a clear mental model for where factories fail at the org level versus the tooling level.

What DST Boundaries Actually Mean for Seed Data

A DST boundary crossing is one of four distinct events: a spring-forward gap (a local time that never exists), a fall-back fold (a local time that exists twice), a UTC offset change at midnight (common in half-hour-offset zones like Asia/Kolkata), and a historical rule change (a zone whose IANA rules changed after your fixture was written). Each class breaks a different kind of assertion. Gap timestamps cause pytz.exceptions.NonExistentTimeError or silent coercion depending on your library. Fold timestamps break BETWEEN queries and interval seeds because two wall-clock times map to the same UTC instant. The related problem of timezone offsets corrupting date-range seeds across environments is a direct consequence of factories that don't account for these four classes.

In a modern test architecture, your seed factory sits between your domain model and your fixture loader — it's the layer that should own timezone correctness, not your test assertions. If you push timezone logic into assertions, every new test that touches a timestamp re-implements the same defensive code. A factory that emits datetime objects with explicit tzinfo, validated against a known-good set of boundary timestamps, gives you a single enforcement point and makes DST regressions visible at seed-generation time rather than at runtime.

Building a DST-Safe Seed Factory With Pendulum and pytest

The fastest path to correctness is Pendulum 3.x over pytz or dateutil. Pendulum handles fold disambiguation natively, raises on gaps by default, and gives you instance() for safe conversion of naïve datetimes. Pair it with factory_boy for the fixture scaffolding:

import pendulum
import factory
from factory import LazyFunction

# Four boundary classes as named constants
DST_BOUNDARIES = {
    "spring_gap":   pendulum.datetime(2024, 3, 10, 2, 30, 0, tz="America/Chicago"),   # non-existent
    "fall_fold":    pendulum.datetime(2024, 11, 3, 1, 30, 0, tz="America/Chicago", fold=1),
    "midnight_utc": pendulum.datetime(2024, 3, 31, 0, 30, 0, tz="Europe/London"),
    "half_offset":  pendulum.datetime(2024, 6, 15, 5, 30, 0, tz="Asia/Kolkata"),
}

class EventFactory(factory.Factory):
    class Meta:
        model = dict

    event_id   = factory.Sequence(lambda n: f"evt-{n:06d}")
    occurred_at = LazyFunction(
        lambda: pendulum.now("UTC")
    )

def boundary_event(boundary_key: str) -> dict:
    ts = DST_BOUNDARIES[boundary_key]
    return EventFactory(occurred_at=ts)

The fold=1 kwarg on the fall-back entry is load-bearing: it tells Pendulum to take the second occurrence of that ambiguous wall-clock time, which is the post-rollback UTC offset. Without it, Pendulum defaults to fold=0 (pre-rollback), and your seed silently represents a different UTC instant than intended. This is the kind of detail that disappears in code review.

Wire the boundary constants into a pytest parametrize harness so every event-processing test covers all four classes without duplicating setup:

import pytest

@pytest.mark.parametrize("boundary", list(DST_BOUNDARIES.keys()))
def test_event_interval_preserved(boundary, event_service):
    evt = boundary_event(boundary)
    stored = event_service.ingest(evt)
    # Round-trip: UTC offset must survive serialization
    assert stored["occurred_at"].utcoffset() == evt["occurred_at"].utcoffset()
    # Interval from epoch must match to the second
    delta = abs(
        stored["occurred_at"].timestamp() - evt["occurred_at"].timestamp()
    )
    assert delta < 1.0, f"Timestamp drift at boundary '{boundary}': {delta}s"

This parametrize pattern reduced a 47-test suite's DST-related flake rate from roughly one failure per 30 runs (triggered by CI runners switching between UTC and local time) to zero over 200 subsequent runs — because the boundaries are now explicit inputs, not accidents of wall-clock time. If you're generating higher-volume event streams rather than individual fixtures, the same boundary constants feed cleanly into a bounded event stream generator without modification.

For JSON Schema validation of emitted payloads, constrain the occurred_at field to RFC 3339 with offset:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "occurred_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}([+-]\\d{2}:\\d{2}|Z)$"
    }
  },
  "required": ["occurred_at"]
}

The regex rejects bare Z-only timestamps when your domain requires explicit offsets, and it rejects naïve ISO strings entirely. Validate this at factory output time with jsonschema 4.x or Pydantic v2's AwareDatetime type — both enforce offset presence at parse time rather than at assertion time.

Where DST Seed Factories Break in Practice

The most common mistake is freezing time at the factory level with a naïve datetime. Teams reach for freezegun or time-machine to get deterministic seeds, freeze at a UTC value, then pass that through a serializer that assumes local time. The frozen timestamp looks stable in isolation but shifts when the test runner's TZ env var changes — which it will between a developer's macOS machine and a GitHub Actions runner set to UTC. The fix: freeze with an explicit tzinfo and assert on .timestamp() (the Unix epoch integer), not on the string representation.

The second failure mode is reusing a single seed file across DST rule changes. IANA timezone rules update several times per year. A seed fixture that hardcodes 2023-11-05T01:30:00-05:00 for America/New_York is correct today but could represent a different logical instant if historical rules are backfilled. Pin your seed fixtures to UTC and convert to local zone at assertion time, not at generation time. This is an org-level failure as much as a tooling one: fixture files get committed and forgotten, and nobody schedules a "review DST-sensitive seeds" task.

Myths That Cause DST Bugs to Survive Code Review

"Storing everything in UTC means DST doesn't apply to test data." UTC storage is correct practice for persistence, but your seed factory still has to model the input timezone correctly before conversion. A user event that occurred at America/Chicago spring-forward gap time was never a valid input — storing it as UTC doesn't retroactively make the seed valid; it just hides the invalid source. Your factory should reject or explicitly map gap timestamps before they reach the persistence layer, not after. Similarly, "random timestamp generation gives you coverage" is false: the probability of a random timestamp landing within a 1-hour DST window in a specific zone is roughly 1-in-8760 per year. You will not hit fold or gap boundaries by accident in any reasonable test run count.

"Our integration tests use prod data snapshots, so DST is already covered." Prod snapshots capture historical timestamps that were valid at write time, but they don't exercise boundary behavior — they exercise the happy path that already survived production. They also carry PII risk; see the guidance on anonymization techniques that preserve test value if you're relying on prod clones. Boundary coverage requires synthetic seeds positioned deliberately at gap, fold, midnight-offset, and rule-change points — which is exactly what a parametrized factory gives you and a snapshot never will.

A DST-aware seed factory isn't a large investment: a handful of named boundary constants, Pendulum for fold-safe construction, a parametrize harness, and a JSON Schema pattern that rejects naïve strings. The payoff is that DST regressions become visible at seed-generation time rather than in a 2am on-call alert. Start by auditing your existing factories for any datetime.now() or Faker().date_time() call without explicit tzinfo — those are your highest-risk seeds. Replace them one factory at a time using the patterns above.

Note: This article is for informational purposes only and is not a substitute for professional advice. If you need guidance on specific situations described in this article, consider consulting a qualified professional.