freezegun

Warnings

• gotcha Performance overhead in large projects: freezegun works by scanning and patching all imported modules that use date/time functions. In applications with many modules or complex dependency trees, this 'find-and-replace' mechanism can introduce significant overhead, making tests noticeably slower. For performance-critical scenarios, libraries like `time-machine` which mock at the C layer may be faster.
  Fix: For smaller projects, this overhead is usually negligible. For large projects with slow time-mocking tests, consider profiling to confirm `freezegun` as the bottleneck and evaluate alternatives like `time-machine`. Ensure `freezegun` is only active for the specific tests requiring time manipulation.
• breaking Asyncio compatibility issues: Prior to version 1.4.0, using `freezegun` with `asyncio` could cause `asyncio.sleep()` and other monotonic time-dependent functions to hang indefinitely, as `time.monotonic()` was also frozen. This was a common pitfall for asynchronous applications.
  Fix: Upgrade to freezegun 1.4.0 or newer. Use the `real_asyncio=True` parameter with `freeze_time` (e.g., `with freeze_time('2023-01-01', real_asyncio=True):`) to allow asyncio event loops to use real monotonic time while other time functions remain frozen.
• gotcha Incomplete mocking scope: freezegun primarily patches module-level imports of `datetime` and `time` functions. It may not intercept calls to time functions that are 'hidden' inside arbitrary objects, set as default function arguments during module import, or invoked directly from C extensions (e.g., Cython-compiled code or certain low-level system calls made by third-party libraries).
  Fix: Be aware of how time-related functions are imported and used in the code under test. If you encounter unmocked time, inspect the import path and call stack. For C extensions or deeply embedded time calls, `freezegun` might not be sufficient, and you might need to use other mocking strategies or a library that intercepts at a lower level (like `time-machine`).
• gotcha Timezone inconsistencies: Freezing time without explicitly managing timezones can lead to unexpected discrepancies, particularly when mixing `datetime.now()` (timezone-aware/local) and `datetime.utcnow()` (naive UTC) or `time.time()`. Issues can arise around Daylight Saving Time (DST) transitions if not handled carefully.
  Fix: Always specify the desired timezone when freezing time if your application is timezone-aware (e.g., `freeze_time('2023-10-26 14:30:00', tz_offset=-5)` or ensuring `datetime.now()` is explicitly timezone-aware where needed). Test edge cases like DST transitions to ensure consistent behavior.
• gotcha External network call issues (SSL/Certificates): Freezing time to a date far in the past can cause `SSLCertVerificationError` when making external HTTP requests. This happens because the SSL certificates used by servers have validity periods, and if the frozen time falls outside this period (e.g., before the certificate's 'notBefore' date), the certificate validation will fail.
  Fix: When testing code that makes external HTTP requests with SSL, ensure the frozen time is within the validity period of common SSL certificates. Alternatively, if appropriate for your test, consider mocking the external HTTP calls entirely or disabling SSL verification for that specific test (with caution).

Install

• pip install freezegun Install stable version

Imports

• freeze_time

  from freezegun import freeze_time

Quickstart

The most common way to use freezegun is via the `@freeze_time` decorator for test functions or the `with freeze_time(...)` context manager for specific blocks of code. You can pass a string representing the desired date and time. The `tick=True` parameter allows time to advance naturally (or manually with `frozen_datetime.tick()`) after the initial freeze, useful for testing time-sensitive sequences or durations. It effectively mocks `datetime.datetime.now()`, `datetime.date.today()`, `time.time()`, and related functions.

import datetime
from freezegun import freeze_time

@freeze_time("2023-10-26 14:30:00")
def test_fixed_time_decorator():
    assert datetime.datetime.now() == datetime.datetime(2023, 10, 26, 14, 30, 0)
    assert datetime.date.today() == datetime.date(2023, 10, 26)

def test_fixed_time_context_manager():
    with freeze_time("2024-01-01 00:00:00"):
        assert datetime.datetime.now() == datetime.datetime(2024, 1, 1, 0, 0, 0)
        assert datetime.datetime.utcnow() == datetime.datetime(2024, 1, 1, 0, 0, 0)

def test_advancing_time():
    with freeze_time("2023-01-01 10:00:00", tick=True) as frozen_datetime:
        start_time = datetime.datetime.now()
        print(f"Start: {start_time}")
        # Simulate some operations that take time, like an external API call
        # In real tests, you might have code here that calls `datetime.now()` multiple times
        frozen_datetime.tick(delta=datetime.timedelta(seconds=5))
        after_tick = datetime.datetime.now()
        print(f"After tick: {after_tick}")
        assert after_tick - start_time == datetime.timedelta(seconds=5)

test_fixed_time_decorator()
test_fixed_time_context_manager()
test_advancing_time()