time-machine Documentation

When choosing a library for mocking time in Python, consider the following trade-offs between time-machine and its alternatives:

• unittest.mock: Fragile because it only affects specific import locations. It cannot mock references like function default arguments (e.g., def func(_now=time.time):).
• freezegun: Uses a find-and-replace mock strategy. It is slow in large projects because mocking time is proportional to the number of loaded modules. It also fails to find imports hidden inside objects (like class-level attributes) and cannot affect C extensions.
• python-libfaketime: A "perfect" mock that wraps C-level system calls, making it very fast and comprehensive. However, it relies on LD_PRELOAD, which is Unix-only and requires either re-executing the process (breaking debuggers/profilers) or manual environment variable management.
• time-machine: Combines the speed and comprehensiveness of libfaketime with the ease of use of freezegun. It works without LD_PRELOAD and mocks standard library functions everywhere they are referenced.

Key Limitations of time-machine:

• It does not mock libraries that use direct C-level system calls for time (though these are rare and can sometimes be added to the mocked set).
• It is currently limited to CPython and does not support other interpreters like PyPy.

The time_machine fixture is a function-scoped fixture that provides programmatic control over time within a test. It provides an object with two primary methods:

• move_to(destination): Sets the current time to the specified destination.
• shift(delta): Shifts the current time by the specified timedelta.

Note: Time is not mocked until you explicitly call move_to() or shift() using the fixture object.

import datetime as dt

def test_delorean(time_machine):
    # Time is not mocked yet
    
    # Set specific time
    time_machine.move_to(dt.datetime(1985, 10, 26))
    assert dt.date.today().isoformat() == "1985-10-26"

    # Change to another time
    time_machine.move_to(dt.datetime(2015, 10, 21))
    assert dt.date.today().isoformat() == "2015-10-21"

    # Shift time by one day
    time_machine.shift(dt.timedelta(days=1))
    assert dt.date.today().isoformat() == "2015-10-22"

You can use time_machine.travel() in several ways to ensure time is automatically restored after the block or function ends:

Function Decorator

Works for both synchronous and asynchronous functions.

Context Manager

Use with (sync) or async with (async) to mock time during a specific block of code.

Class Decorator

Only supports unittest.TestCase subclasses. Time is mocked from the start of setUpClass() to the end of tearDownClass().

import time
import time_machine

# Function decorator
@time_machine.travel("1970-01-01 00:00 +0000")
def test_in_the_deep_past():
    assert 0.0 < time.time() < 1.0

# Async function decorator
@time_machine.travel("1970-01-01 00:00 +0000")
async def test_async_past():
    assert 0.0 < time.time() < 1.0

# Synchronous context manager
def test_context_manager():
    with time_machine.travel(0.0):
        assert 0.0 < time.time() < 1.0

# Asynchronous context manager
async def test_async_context_manager():
    async with time_machine.travel(0.0):
        assert 0.0 < time.time() < 1.0

If you are performing simple function calls, you can migrate by replacing calls to freezegun.freeze_time() or libfaketime.fake_time() with time_machine.travel().

Key API Differences

• tick argument: In time-machine, the tick argument in travel() defaults to True (time progresses while running). In freezegun, the default behavior is effectively False. To match freezegun's behavior, you must explicitly pass tick=False.
• Timezone Handling: freezegun interprets naive datetimes in the local time zone. time-machine interprets naive datetimes in UTC. To mock a specific time zone, provide a datetime object with a ZoneInfo timezone.
• Shifting Time: freezegun's tick() method is implemented as shift() in time-machine. Unlike freezegun, shift() requires an explicit delta.
• Unsupported Arguments: freezegun's tz_offset and auto_tick_seconds are not supported by time-machine.

# Example migration pattern
# From freezegun:
# @freeze_time("2023-01-01")
# def test_func(): ...

# To time-machine:
# @time_machine.travel("2023-01-01", tick=False)
# def test_func(): ...