Add marker support to pytest plugin

Author: kingbuzzman

docs/changelog.rst

@@ -10,6 +10,10 @@ Changelog
 2.18.0 (2025-08-18)
 -------------------
 
+* Add a pytest marker fixture supporting initial time setting and in-test time shifting.
+
+  Thanks to Javier Buzzi in `PR #499 <https://github.com/adamchainz/time-machine/pull/499>`__.
+
 * Update the :ref:`migration CLI <migration-cli>` to detect unittest classes based on whether they use ``self.assert*`` methods like ``self.assertEqual()``.
 
 * Fix free-threaded Python warning: ``RuntimeWarning: The global interpreter lock (GIL) has been enabled...`` as seen on Python 3.13+.

docs/pytest_plugin.rst

@@ -3,7 +3,7 @@ pytest plugin
 =============
 
 time-machine also works as a pytest plugin.
-It provides a function-scoped fixture called ``time_machine`` with methods ``move_to()`` and ``shift()``, which have the same signature as their equivalents in ``Coordinates``.
+It provides a marker and function-scoped fixture called ``time_machine`` with methods ``move_to()`` and ``shift()``, which have the same signature as their equivalents in ``Coordinates``.
 This can be used to mock your test at different points in time and will automatically be un-mock when the test is torn down.
 
 For example:
@@ -13,6 +13,13 @@ For example:
     import datetime as dt
 
 
+    @pytest.mark.time_machine(dt.datetime(1985, 10, 26))
+    def test_delorean_marker(time_machine):
+        assert dt.date.today().isoformat() == "1985-10-26"
+        time_machine.move_to(dt.datetime(2015, 10, 21))
+        assert dt.date.today().isoformat() == "2015-10-21"
+
+
     def test_delorean(time_machine):
         time_machine.move_to(dt.datetime(1985, 10, 26))
 

pyproject.toml

@@ -130,6 +130,7 @@ max_supported_python = "3.14"
 addopts = """\
     --strict-config
     --strict-markers
+    -p pytester
     """
 xfail_strict = true
 

src/time_machine/__init__.py

@@ -378,6 +378,24 @@ def time_ns() -> int:
 # pytest plugin
 
 if HAVE_PYTEST:  # pragma: no branch
+    MARKER_NAME = "time_machine"
+    FIXTURE_NAME = "time_machine"
+
+    def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
+        """
+        Inject our fixture into any tests with our marker
+        """
+        for item in items:
+            if item.get_closest_marker(MARKER_NAME):
+                item.fixturenames.insert(0, FIXTURE_NAME)  # type: ignore[attr-defined]
+
+    def pytest_configure(config: pytest.Config) -> None:
+        """
+        Register our marker
+        """
+        config.addinivalue_line(
+            "markers", f"{MARKER_NAME}(...): use time machine to set time"
+        )
 
     class TimeMachineFixture:
         traveller: travel | None
@@ -413,9 +431,15 @@ def stop(self) -> None:
             if self.traveller is not None:
                 self.traveller.stop()
 
-    @pytest.fixture(name="time_machine")
-    def time_machine_fixture() -> TypingGenerator[TimeMachineFixture, None, None]:
+    @pytest.fixture(name=FIXTURE_NAME)
+    def time_machine_fixture(
+        request: pytest.FixtureRequest,
+    ) -> TypingGenerator[TimeMachineFixture, None, None]:
         fixture = TimeMachineFixture()
+        marker = request.node.get_closest_marker(MARKER_NAME)
+        if marker:
+            fixture.move_to(*marker.args, **marker.kwargs)
+
         yield fixture
         fixture.stop()
 

tests/test_time_machine.py

@@ -948,6 +948,36 @@ def test_fixture_shift_without_move_to(time_machine):
     )
 
 
+def test_standalone_marker(testdir):
+    testdir.makepyfile(
+        """
+        import pytest
+        import time
+
+        @pytest.fixture
+        def current_time():
+             return time.time()
+
+        @pytest.fixture
+        def set_time(time_machine):
+             time_machine.move_to("2000-01-01")
+
+        def test_normal(current_time):
+            assert current_time > 1742943111.0
+
+        @pytest.mark.time_machine("2000-01-01")
+        def test_mod(current_time, time_machine):
+            assert current_time == 946684800.0
+            time_machine.shift(1)
+            assert current_time == 946684800.0
+            assert int(time.time()) == 946684801
+    """
+    )
+
+    result = testdir.runpytest("-v", "-s")
+    assert result.ret == 0
+
+
 # escape hatch tests