Freezegun: Time Travel for Your Python Tests

Introduction

Freezegun is an indispensable Python library that empowers developers to manipulate time within their test suites. By effectively mocking the datetime module, time.time(), and related functions, Freezegun allows you to freeze the current time to a specific date and time, or even simulate the passage of time. This capability is vital for testing applications with time-dependent features, ensuring that your tests are deterministic and free from real-world time variations.

Installation

Installing Freezegun is straightforward using pip:

$ pip install freezegun

For Debian systems, you can also use apt-get:

$ sudo apt-get install python-freezegun

Examples

Freezegun offers flexible ways to control time, whether through decorators, context managers, or direct API calls.

Decorator Usage

Apply freeze_time as a decorator to functions or classes to freeze time for their duration.

from freezegun import freeze_time
import datetime
import unittest

# Freeze time for a pytest style test:
@freeze_time("2012-01-14")
def test_frozen_time_decorator():
    assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)

# Or a unittest TestCase:
@freeze_time("1955-11-12")
class MyTests(unittest.TestCase):
    def test_the_class(self):
        assert datetime.datetime.now() == datetime.datetime(1955, 11, 12)

Context Manager Usage

Use freeze_time as a context manager for precise control over time within a specific block of code.

from freezegun import freeze_time
import datetime

def test_time_context_manager():
    assert datetime.datetime.now() != datetime.datetime(2012, 1, 14)
    with freeze_time("2012-01-14"):
        assert datetime.datetime.now() == datetime.datetime(2012, 1, 14)
    assert datetime.datetime.now() != datetime.datetime(2012, 1, 14)

Manual Ticks and Moving Time

Beyond freezing, Freezegun allows you to manually advance time or jump to a specific date.

from freezegun import freeze_time
import datetime

def test_manual_tick_and_move():
    initial_datetime = datetime.datetime(year=1, month=7, day=12,
                                        hour=15, minute=6, second=3)
    with freeze_time(initial_datetime) as frozen_datetime:
        assert frozen_datetime() == initial_datetime

        # Manually advance time by 1 second
        frozen_datetime.tick()
        initial_datetime += datetime.timedelta(seconds=1)
        assert frozen_datetime() == initial_datetime

        # Move to a completely different date
        other_datetime = datetime.datetime(year=2, month=8, day=13,
                                            hour=14, minute=5, second=0)
        frozen_datetime.move_to(other_datetime)
        assert frozen_datetime() == other_datetime

Ticking Time

The tick=True argument allows time to progress naturally from the frozen point.

from freezegun import freeze_time
import datetime
import time

@freeze_time("Jan 14th, 2020", tick=True)
def test_ticking_time():
    # Time will progress naturally after the initial freeze point
    initial_time = datetime.datetime.now()
    time.sleep(0.01) # Simulate some time passing
    assert datetime.datetime.now() > initial_time

Auto-Ticking Time

The auto_tick_seconds argument automatically increments time by a specified amount on each call.

from freezegun import freeze_time
import datetime

@freeze_time("Jan 14th, 2020", auto_tick_seconds=15)
def test_auto_ticking_time():
    first_time = datetime.datetime.now()
    # Subsequent call to datetime.datetime.now() will be 15 seconds later
    auto_incremented_time = datetime.datetime.now()
    assert first_time + datetime.timedelta(seconds=15) == auto_incremented_time

Real Asyncio

For asyncio applications, real_asyncio=True allows asyncio event loops to see real monotonic time while datetime remains frozen.

from freezegun import freeze_time
import datetime
import asyncio

@freeze_time("2012-01-14", real_asyncio=True)
async def test_asyncio_with_frozen_time():
    start_time = datetime.datetime.now()
    await asyncio.sleep(0.1) # This sleep will use real time
    end_time = datetime.datetime.now()
    assert start_time == end_time # datetime is still frozen

Why Use Freezegun?

Testing applications that interact with dates and times can be notoriously difficult. Real-world time is constantly changing, making it hard to reproduce specific scenarios or ensure consistent test results. Freezegun solves this by providing a simple, elegant way to control time within your tests. This leads to more reliable, deterministic, and faster test suites, allowing you to focus on your application's logic rather than battling time-related inconsistencies. It's an essential tool for any Python developer working with datetime objects in their code.

Links

Explore the Freezegun project further:

• GitHub Repository
• PyPI Page