Time Travel in Your Tests with freezegun

Testing time-dependent code presents significant challenges. Applications that check subscription status, validate trial eligibility, or perform date calculations often produce unreliable test results. The freezegun library solves this by allowing developers to freeze time during testing.

The Problem

Imagine needing to test a subscription expiring after 30 days. Verifying active status on day 15 versus expired status on day 45 presents a reliability challenge. Creating subscriptions with distant expiration dates creates fragile tests. The real need is controlling what datetime.now() returns.

The Solution

Freezegun patches datetime.now(), date.today(), and related time functions to return fixed values during tests. Key usage patterns include:

• The @freeze_time decorator for single point-in-time tests
• Context managers when testing identical logic across multiple time points
• move_to() for simulating time passage within tests
• tick=True parameter when time needs to progress naturally
• Results in deterministic, reproducible tests eliminating flaky time-based failures

Installation: pip install freezegun

Key Takeaways

The library enables testing without time-based brittleness, providing consistent test execution regardless of when tests run.