Time

provide.testkit.mocking.time

Time Mocking Utilities.

Provides utilities for mocking time-related functions in tests, particularly sleep functions from both time and asyncio modules.

Classes

SleepTracker

SleepTracker()

Tracks sleep calls and their durations.

Initialize sleep tracker.

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

def __init__(self) -> None:
    """Initialize sleep tracker."""
    self.calls: list[float] = []
    self.total_sleep_time: float = 0.0

Attributes

call_count property

call_count: int

Get number of sleep calls.

Functions

add_call

add_call(duration: float) -> None

Add a sleep call.

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

def add_call(self, duration: float) -> None:
    """Add a sleep call."""
    self.calls.append(duration)
    self.total_sleep_time += duration

reset

reset() -> None

Reset tracking data.

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

def reset(self) -> None:
    """Reset tracking data."""
    self.calls.clear()
    self.total_sleep_time = 0.0

Functions

create_sleep_mock

create_sleep_mock(
    instant: bool = True, track_calls: bool = True
) -> Mock

Create a mock for sleep functions with tracking.

Parameters:

Name	Type	Description	Default
instant	bool	If True, sleep calls return immediately.	True
track_calls	bool	If True, track all sleep calls and durations.	True

Returns:

Type	Description
Mock	Mock object with sleep tracking capabilities.

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

def create_sleep_mock(instant: bool = True, track_calls: bool = True) -> Mock:
    """Create a mock for sleep functions with tracking.

    Args:
        instant: If True, sleep calls return immediately.
        track_calls: If True, track all sleep calls and durations.

    Returns:
        Mock object with sleep tracking capabilities.
    """
    mock = Mock()
    tracker = SleepTracker()

    def sleep_side_effect(duration: float) -> None:
        if track_calls:
            tracker.add_call(duration)

    mock.side_effect = sleep_side_effect
    mock.tracker = tracker
    return mock

mock_asyncio_sleep

mock_asyncio_sleep(
    instant: bool = True,
    track_calls: bool = True,
    side_effect: Any = None,
) -> Generator[SleepTracker, None, None]

Context manager to mock only asyncio.sleep.

Parameters:

Name	Type	Description	Default
instant	bool	If True, sleep calls return immediately. If False, use side_effect.	True
track_calls	bool	If True, track all sleep calls and durations.	True
side_effect	Any	Custom side effect for sleep calls. Ignored if instant=True.	None

Yields:

Type	Description
SleepTracker	SleepTracker instance for inspecting sleep calls.

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

@contextmanager
def mock_asyncio_sleep(
    instant: bool = True,
    track_calls: bool = True,
    side_effect: Any = None,
) -> Generator[SleepTracker, None, None]:
    """Context manager to mock only asyncio.sleep.

    Args:
        instant: If True, sleep calls return immediately. If False, use side_effect.
        track_calls: If True, track all sleep calls and durations.
        side_effect: Custom side effect for sleep calls. Ignored if instant=True.

    Yields:
        SleepTracker instance for inspecting sleep calls.
    """
    tracker = SleepTracker()

    async def asyncio_sleep_mock(duration: float) -> None:
        """Mock implementation of asyncio.sleep."""
        if track_calls:
            tracker.add_call(duration)
        if not instant and side_effect:
            result = side_effect(duration)
            if asyncio.iscoroutine(result):
                return await result
            return result

    with patch("asyncio.sleep", side_effect=asyncio_sleep_mock):
        yield tracker

mock_sleep

mock_sleep(
    instant: bool = True,
    track_calls: bool = True,
    side_effect: Any = None,
) -> Generator[SleepTracker, None, None]

Context manager to mock both time.sleep and asyncio.sleep.

Parameters:

Name	Type	Description	Default
instant	bool	If True, sleep calls return immediately. If False, use side_effect.	True
track_calls	bool	If True, track all sleep calls and durations.	True
side_effect	Any	Custom side effect for sleep calls. Ignored if instant=True.	None

Yields:

Type	Description
SleepTracker	SleepTracker instance for inspecting sleep calls.

Example

with mock_sleep() as sleep_tracker: time.sleep(1.0) asyncio.sleep(2.0) assert sleep_tracker.call_count == 2 assert sleep_tracker.total_sleep_time == 3.0

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

@contextmanager
def mock_sleep(
    instant: bool = True,
    track_calls: bool = True,
    side_effect: Any = None,
) -> Generator[SleepTracker, None, None]:
    """Context manager to mock both time.sleep and asyncio.sleep.

    Args:
        instant: If True, sleep calls return immediately. If False, use side_effect.
        track_calls: If True, track all sleep calls and durations.
        side_effect: Custom side effect for sleep calls. Ignored if instant=True.

    Yields:
        SleepTracker instance for inspecting sleep calls.

    Example:
        with mock_sleep() as sleep_tracker:
            time.sleep(1.0)
            asyncio.sleep(2.0)
            assert sleep_tracker.call_count == 2
            assert sleep_tracker.total_sleep_time == 3.0
    """
    tracker = SleepTracker()

    def time_sleep_mock(duration: float) -> None:
        """Mock implementation of time.sleep."""
        if track_calls:
            tracker.add_call(duration)
        if not instant and side_effect:
            return side_effect(duration)

    async def asyncio_sleep_mock(duration: float) -> None:
        """Mock implementation of asyncio.sleep."""
        if track_calls:
            tracker.add_call(duration)
        if not instant and side_effect:
            result = side_effect(duration)
            if asyncio.iscoroutine(result):
                return await result
            return result

    with (
        patch("time.sleep", side_effect=time_sleep_mock),
        patch("asyncio.sleep", side_effect=asyncio_sleep_mock),
    ):
        try:
            yield tracker
        finally:
            pass

mock_time_sleep

mock_time_sleep(
    instant: bool = True,
    track_calls: bool = True,
    side_effect: Any = None,
) -> Generator[SleepTracker, None, None]

Context manager to mock only time.sleep.

Parameters:

Name	Type	Description	Default
instant	bool	If True, sleep calls return immediately. If False, use side_effect.	True
track_calls	bool	If True, track all sleep calls and durations.	True
side_effect	Any	Custom side effect for sleep calls. Ignored if instant=True.	None

Yields:

Type	Description
SleepTracker	SleepTracker instance for inspecting sleep calls.

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

@contextmanager
def mock_time_sleep(
    instant: bool = True,
    track_calls: bool = True,
    side_effect: Any = None,
) -> Generator[SleepTracker, None, None]:
    """Context manager to mock only time.sleep.

    Args:
        instant: If True, sleep calls return immediately. If False, use side_effect.
        track_calls: If True, track all sleep calls and durations.
        side_effect: Custom side effect for sleep calls. Ignored if instant=True.

    Yields:
        SleepTracker instance for inspecting sleep calls.
    """
    tracker = SleepTracker()

    def time_sleep_mock(duration: float) -> None:
        """Mock implementation of time.sleep."""
        if track_calls:
            tracker.add_call(duration)
        if not instant and side_effect:
            return side_effect(duration)

    with patch("time.sleep", side_effect=time_sleep_mock):
        yield tracker