freezegun

FreezeGun is a Python testing utility that patches the standard library’s time-related calls — datetime.datetime.now(), datetime.date.today(), time.time(), time.localtime(), time.gmtime(), time.strftime(), time.monotonic(), time.perf_counter(), and UUID1 generation — so tests can assert against a fixed, known point in time instead of racing the real clock.

The core freeze_time() entry point works as a decorator on functions, unittest.TestCase classes, or any callable class, as well as a context manager or a manually started/stopped object. It accepts natural-language and structured inputs (ISO strings, datetime objects, date objects, or a callable/generator that yields successive datetimes) via python-dateutil, plus a tz_offset for simulating non-UTC test environments.

Beyond simple freezing, it supports tick=True and auto_tick_seconds to let frozen time advance automatically, and a returned FrozenDateTimeFactory object with .tick() and .move_to() methods for manually stepping or jumping the frozen clock mid-test. A real_asyncio=True flag keeps asyncio event-loop scheduling on real monotonic time even while time.monotonic() is frozen elsewhere, avoiding broken asyncio.sleep() calls in async test suites.

A configurable ignore list (nose.plugins, selenium, threading, gi, etc.) excludes specific modules from time mocking, since blindly patching every consumer of time.time() can break test runners and other libraries that rely on real timestamps internally.

What You Get

• @freeze_time(...) decorator usable on plain functions, async coroutines, unittest.TestCase classes, and arbitrary classes
• A context-manager and manual start()/stop() API for freezing time around arbitrary code blocks
• Ticking modes (tick=True, auto_tick_seconds) so frozen time can advance realistically instead of staying perfectly static
• A FrozenDateTimeFactory handle exposing .tick(delta) and .move_to(target) for step-by-step or jump-based time control mid-test
• Natural-language date parsing via python-dateutil, plus support for callables and generators as the time source
• A configurable default ignore list (and freezegun.configure()) to exempt specific modules like threading or selenium from mocking

Common Use Cases

• Asserting business logic that depends on datetime.datetime.now() or date.today() without waiting for real time to pass
• Testing time-based expiration, scheduling, or TTL logic (tokens, caches, subscriptions) at exact simulated instants
• Verifying behavior across timezone or DST boundaries by freezing to a specific UTC instant with a tz_offset
• Simulating multi-step time progression in a single test using tick() or move_to() to check state transitions over time
• Freezing an entire unittest.TestCase class so every test method and setUp/tearDown runs against the same fixed date

Under The Hood

Architecture The library centers on a small factory hierarchy in freezegun/api.py — FrozenDateTimeFactory, TickingDateTimeFactory, and StepTickTimeFactory — each producing fake replacements for datetime.datetime, datetime.date, and the relevant time module functions, pushed onto module-level stacks (freeze_factories, tz_offsets, ignore_lists, tick_flags) so nested freeze_time() calls compose correctly; _freeze_time.start()/.stop() swap these fakes into datetime, time, calendar, and uuid at the module level and restore the originals captured at import time (real_time, real_datetime, etc.) on exit, with _async.py providing a small coroutine-wrapping shim so the decorator can also wrap async def test functions.

Tech Stack A pure-Python library (99.75% Python by bytes) with a single runtime dependency, python-dateutil>=2.7, used for flexible date-string parsing; it optionally integrates with maya (only on Python <3.12) if installed; packaging is plain setuptools via setup.cfg/setup.py with no build step beyond that, and pyproject.toml is used only to configure mypy --strict type checking.

Code Quality The tests/ directory contains roughly 20 focused test modules (test_datetimes.py, test_ticking.py, test_asyncio.py, test_pickle.py, test_uuid.py, test_sqlite3.py, etc.) run via pytest with pytest-cov and Coveralls reporting in CI, and the package ships a py.typed marker with full type annotations enforced by mypy --strict; error handling is explicit (a dedicated ConfigurationError for misuse of configure()), and the CI workflow runs the suite across the supported Python versions and PyPy.

What Makes It Unique Rather than requiring application code to accept an injectable clock, FreezeGun patches the standard library itself — including edge cases like time.monotonic(), time.perf_counter(), nanosecond-resolution time functions, and even C-extension-backed UUID1 generation — while still offering an escape hatch (the ignore list and real_asyncio flag) for the small set of subsystems where faking time would break correctness. This breadth of coverage across the datetime, time, and uuid surfaces, combined with composable nesting and manual tick/move_to control, is why it has become the standard tool for this problem rather than a bespoke per-project mock.