Mocking

provide.testkit.time.mocking

Time mocking fixtures for testing.

Fixtures for mocking time-related functions like sleep, datetime.now(), etc.

Functions

mock_datetime

mock_datetime() -> Generator[Mock, None, None]

Mock datetime module for testing.

Returns:

Type	Description
None	Mock datetime module with common methods mocked.

Example

def test_with_mock_datetime(mock_datetime): ... now = datetime.datetime.now() ... assert now == datetime.datetime(2024, 1, 1, 12, 0, 0)

Source code in provide/testkit/time/mocking.py

@pytest.fixture
def mock_datetime() -> Generator[Mock, None, None]:
    """Mock datetime module for testing.

    Returns:
        Mock datetime module with common methods mocked.

    Example:
        >>> def test_with_mock_datetime(mock_datetime):
        ...     now = datetime.datetime.now()
        ...     assert now == datetime.datetime(2024, 1, 1, 12, 0, 0)
    """
    with patch("datetime.datetime") as mock_dt:
        # Set up a fake "now"
        fake_now = datetime.datetime(2024, 1, 1, 12, 0, 0)
        mock_dt.now.return_value = fake_now
        mock_dt.utcnow.return_value = fake_now
        mock_dt.today.return_value = fake_now.date()

        # Allow normal datetime construction
        mock_dt.side_effect = lambda *args, **kwargs: datetime.datetime(*args, **kwargs)

        yield mock_dt

mock_sleep

mock_sleep() -> Generator[Mock, None, None]

Mock time.sleep to speed up tests.

Returns:

Type	Description
None	Mock object that replaces time.sleep.

Example

def test_with_mock_sleep(mock_sleep): ... time.sleep(10) # Returns instantly ... assert mock_sleep.called

Source code in provide/testkit/time/mocking.py

@pytest.fixture
def mock_sleep() -> Generator[Mock, None, None]:
    """Mock time.sleep to speed up tests.

    Returns:
        Mock object that replaces time.sleep.

    Example:
        >>> def test_with_mock_sleep(mock_sleep):
        ...     time.sleep(10)  # Returns instantly
        ...     assert mock_sleep.called
    """
    with patch("time.sleep") as mock:
        # Make sleep instant by default
        mock.return_value = None
        yield mock

mock_sleep_with_callback

mock_sleep_with_callback() -> (
    Callable[[Callable[[float], None] | None], Mock]
)

Mock time.sleep with a callback for each sleep call.

Returns:

Type	Description
Callable[[Callable[[float], None] | None], Mock]	Function to set up sleep mock with callback.

Example

def test_with_callback(mock_sleep_with_callback): ... total_sleep = [] ... sleep_mock = mock_sleep_with_callback(lambda s: total_sleep.append(s)) ... with patch("time.sleep", sleep_mock): ... time.sleep(1.5) ... assert total_sleep == [1.5]

Source code in provide/testkit/time/mocking.py

@pytest.fixture
def mock_sleep_with_callback() -> Callable[[Callable[[float], None] | None], Mock]:
    """Mock time.sleep with a callback for each sleep call.

    Returns:
        Function to set up sleep mock with callback.

    Example:
        >>> def test_with_callback(mock_sleep_with_callback):
        ...     total_sleep = []
        ...     sleep_mock = mock_sleep_with_callback(lambda s: total_sleep.append(s))
        ...     with patch("time.sleep", sleep_mock):
        ...         time.sleep(1.5)
        ...     assert total_sleep == [1.5]
    """

    def _mock_sleep(callback: Callable[[float], None] | None = None) -> Mock:
        """Create a mock sleep with optional callback.

        Args:
            callback: Function called with sleep duration

        Returns:
            Mock sleep object
        """

        def sleep_side_effect(seconds: float) -> None:
            if callback:
                callback(seconds)
            return None

        mock = Mock(side_effect=sleep_side_effect)
        return mock

    return _mock_sleep

time_travel

time_travel() -> (
    Generator[
        Callable[[datetime.datetime], None], None, None
    ]
)

Fixture for traveling through time in tests.

Returns:

Type	Description
None	Function to travel to specific time points.

Example

def test_with_time_travel(time_travel): ... time_travel(datetime.datetime(2025, 1, 1)) ... # time.time() now returns the timestamp for 2025-01-01

Source code in provide/testkit/time/mocking.py

@pytest.fixture
def time_travel() -> Generator[Callable[[datetime.datetime], None], None, None]:
    """Fixture for traveling through time in tests.

    Returns:
        Function to travel to specific time points.

    Example:
        >>> def test_with_time_travel(time_travel):
        ...     time_travel(datetime.datetime(2025, 1, 1))
        ...     # time.time() now returns the timestamp for 2025-01-01
    """
    original_time = time.time
    current_offset = 0.0

    def mock_time() -> float:
        return original_time() + current_offset

    def _travel_to(target: datetime.datetime) -> None:
        """Travel to a specific point in time.

        Args:
            target: The datetime to travel to
        """
        nonlocal current_offset
        current_offset = target.timestamp() - original_time()

    with patch("time.time", mock_time):
        yield _travel_to