Metadata-Version: 2.1
Name: pytest_time
Version: 0.3.2
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Pytest
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Unit
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: COPYING
Requires-Dist: pytest

pytest-time
===========

The pytest-time plugin extends pytest to control ``time`` — the built-in Python
module, not the concept within the universe.

.. image:: https://github.com/lengau/pytest-time/actions/workflows/tests.yaml/badge.svg
    :target: https://github.com/lengau/pytest-time/actions/workflows/tests.yaml

Fixtures
--------

Pytest-time offers several fixtures for use in your projects, depending on your particular needs.

Instant Sleep
~~~~~~~~~~~~~

The ``instant_sleep`` fixture is the most basic wrapper and is designed to be used at any scope. It monkeypatches the built-in ``time`` module to be chronologically consistent while not actually sleeping when running ``time.sleep``. This includes modifying the behaviour of ``time.time()``, ``time.monotonic()`` and their nanosecond counterparts to include the additional delay expected after sleeping.

A basic use of ``instant_sleep`` is shown below:

.. code:: python

    import time
    import pytest

    @pytest.mark.parametrize("sleep_time", [1, 10, 100])
    @pytest.mark.usefixtures("instant_sleep")
    def test_instant_sleep(sleep_time):
        start_time = time.time()
        start_monotonic = time.monotonic()

        time.sleep(sleep_time)

        assert time.time() >= start_time + sleep_time
        assert time.monotonic() >= start_monotonic + sleep_time

This code will behave almost identically with and without the ``instant_sleep`` fixture in use. To demonstrate, let's time this file with the fixture enabled...

.. code:: text

    $ time pytest test_instant_sleep.py
    =========== test session starts ===========
    platform linux -- Python 3.11.4, pytest-7.3.1, pluggy-1.0.0
    rootdir: /home/lengau/Projects/pytest-time
    configfile: pyproject.toml
    plugins: check-2.1.5, mock-3.10.0, hypothesis-6.78.2, time-0.2.1.dev3+ga0d3b98.d20230624, cov-4.1.0
    collected 3 items

    test_instant_sleep.py ...                              [100%]

    =========== 3 passed in 0.01s ===========

    real    0m0.276s
    user    0m0.240s
    sys     0m0.025s

and disabled:

.. code:: text

    $ time pytest test_instant_sleep_no_fixture.py
    =========== test session starts ===========
    platform linux -- Python 3.11.4, pytest-7.3.1, pluggy-1.0.0
    rootdir: /home/lengau/Projects/pytest-time
    configfile: pyproject.toml
    plugins: check-2.1.5, mock-3.10.0, hypothesis-6.78.2, time-0.2.1.dev3+ga0d3b98.d20230624, cov-4.1.0
    collected 3 items

    test_instant_sleep_no_fixture.py ...                   [100%]

    =========== 3 passed in 111.01s (0:01:51) ===========

    real    1m51.354s
    user    0m0.250s
    sys     0m0.020s

The sleep is, for practical purposes, essentially instant. And yet, the ``time`` module still acts as though the appropriate time has passed.

Recording Time Calls
~~~~~~~~~~~~~~~~~~~~~

Pytest-time also provides ``mock_time``, a fixture that wraps several ``time`` functions in Mock objects but still runs the real calls. This is useful if you need to ensure that certain calls occurred, etc. The fixture will provide Mock objects for inspection in tests:

.. code:: python

    import time

    def test_mock_time(mock_time):
        start_time = time.time()
        start_monotonic = time.monotonic()

        time.sleep(1)  # Actually sleeps for a second

        assert time.time() >= start_time + 1
        assert time.monotonic() >= start_monotonic + 1

        mock_time.sleep.assert_called_once_with(1)
        assert len(mock_time.time.mock_calls) == 2
        assert len(mock_time.monotonic.mock_calls) == 2

Mocking a Powernap
~~~~~~~~~~~~~~~~~~

The two above are combined for you in the ``mock_instant_sleep`` fixture. This fixture replaces the relevant ``time`` functions as in the ``instant_sleep`` fixture, but also provides mock wrappers around those functions, allowing for recording time.

.. code:: python

    import time

    def test_mock_instant_sleep(mock_instant_sleep):
        start_time = time.time()
        start_monotonic = time.monotonic()

        time.sleep(86400)  # Doesn't sleep

        assert time.time() >= start_time + 86400
        assert time.monotonic() >= start_monotonic + 86400

        mock_instant_sleep.sleep.assert_called_once_with(86400)
        assert len(mock_instant_sleep.time.mock_calls) == 2
        assert len(mock_instant_sleep.monotonic.mock_calls) == 2
