💤 SleepFake: Time Travel for Your Tests

Ever wish your tests could skip the waiting but keep correct time behavior? SleepFake patches time.sleep and asyncio.sleep so tests return instantly while frozen time moves forward exactly as requested. Async timeouts (asyncio.wait_for, asyncio.timeout, loop.call_later) fire on the fake clock too.

pip install sleepfake

Python 3.10 to 3.15, including free-threaded builds (3.13t+). The pytest plugin registers itself.

Make SleepFake apply to every test. Add to pyproject.toml:

[tool.pytest.ini_options]
sleepfake_autouse = true

Now regular tests skip sleeps:

import time


def test_retry():
    start = time.time()
    time.sleep(30)  # returns instantly
    assert time.time() - start >= 30

Async works the same way, timeouts included:

import asyncio

import pytest


async def test_polling():
    start = asyncio.get_running_loop().time()
    await asyncio.sleep(10)  # returns instantly
    assert asyncio.get_running_loop().time() - start >= 10


async def test_gives_up():
    with pytest.raises(TimeoutError):
        await asyncio.wait_for(asyncio.Event().wait(), timeout=60)  # ~20 ms, not 60 s

pytest-asyncio users: add asyncio_mode = "auto" (or mark tests with @pytest.mark.asyncio) so pytest collects async tests.

All pytest styles share one instance per test: combining them never patches twice.

import asyncio
import time

from sleepfake import SleepFake

# Sync
with SleepFake():
    start = time.time()
    time.sleep(10)  # returns instantly
    assert time.time() - start >= 10


# Async: `async with` or plain `with` both work
async def main():
    async with SleepFake():
        start = asyncio.get_running_loop().time()
        await asyncio.sleep(5)  # returns instantly
        assert asyncio.get_running_loop().time() - start >= 5

with SleepFake(ignore=["my_project.telemetry"]):
    ...

import asyncio
import time


def test_retry_logic(sleepfake):
    start = time.time()
    time.sleep(30)  # instantly skipped
    assert time.time() - start >= 30


async def test_polling(sleepfake):
    start = asyncio.get_running_loop().time()
    await asyncio.gather(asyncio.sleep(1), asyncio.sleep(5), asyncio.sleep(3))
    # All three complete instantly; the clock sits at +5 s
    assert asyncio.get_running_loop().time() - start >= 5

import time

import pytest


@pytest.mark.sleepfake
def test_marked():
    start = time.time()
    time.sleep(100)
    assert time.time() - start >= 100

# pyproject.toml
[tool.pytest.ini_options]
sleepfake_autouse = true
sleepfake_ignore = ["my_project.telemetry", "my_project.metrics"]

pytest --sleepfake --sleepfake-ignore my_project.telemetry

# conftest.py
pytest_sleepfake_ignore = ["my_project.telemetry"]

async def test_timeout(sleepfake):
    with pytest.raises(TimeoutError):
        async with asyncio.timeout(2):
            await asyncio.sleep(10)  # the clock stops at +2 s, like real asyncio

SleepFake(autojump_threshold=0)  # jump as soon as the loop is idle
SleepFake(autojump_threshold=math.inf)  # never jump: timers only fire when sleeps move the clock

[tool.pytest.ini_options]
sleepfake_autojump_threshold = "0.5"

Every ignore list is merged with DEFAULT_IGNORE = ["_pytest.timing", "pytest_timeout"], which keeps pytest's --durations and pytest-timeout on real clocks. Disable the plugin with -p no:sleepfake.

• Local bindings. A sleep captured in a local variable before the context starts (_sleep = time.sleep) keeps calling the real function.
• Real I/O under a timeout. If real I/O takes longer than autojump_threshold inside a wait_for/timeout, the timeout fires on the fake clock. Raise the threshold, or set it to math.inf.
• Other event loops. Timer autojump reads asyncio's pure-Python loop internals. On other loops (e.g. uvloop) asyncio.sleep is still faked, but loop timers need real time.
• Timer precision. A timer jump lands 1 µs after the deadline: asyncio only runs a timer once the clock is strictly past it.
• Shared clock. The frozen clock is global: every thread and every event loop sees the same time.

make dev-install   # uv sync + prek git hooks
make test-all      # ruff + ty, then tests
make cov           # tests under coverage (100% required)
make test-all-python  # 3.10 to 3.15 and 3.14t

PRs and issues welcome. See CHANGELOG.md for release notes.