Add shift() method to pytest time_machine fixture (#247)

HISTORY.rst

@@ -3,6 +3,7 @@ History
 =======
 
 * Build Windows ARM64 wheels.
+* Add ``shift()`` method to the pytest ``time_machine`` fixture.
 
 2.8.2 (2022-09-29)
 ------------------

README.rst

@@ -295,7 +295,7 @@ pytest plugin
 -------------
 
 time-machine also works as a pytest plugin.
-It provides a function-scoped fixture called ``time_machine`` that has one method, ``move_to()``, which has the same signature as ``Coordinates.move_to()``.
+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``.
 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:

src/time_machine/__init__.py

@@ -441,6 +441,14 @@ def move_to(
                 assert self.coordinates is not None
                 self.coordinates.move_to(destination, tick=tick)
 
+        def shift(self, delta: dt.timedelta | int | float) -> None:
+            if self.traveller is None:
+                raise RuntimeError(
+                    "Initialize with `move_to()` first before using `shift()`"
+                )
+            assert self.coordinates is not None
+            self.coordinates.shift(delta=delta)
+
         def stop(self) -> None:
             if self.traveller is not None:
                 self.traveller.stop()

tests/test_time_machine.py

@@ -701,14 +701,26 @@ def test_fixture_used_tick_true(time_machine):
     assert original < time.time() < EPOCH + 10.0
 
 
-def test_fixture_used_twice(time_machine):
+def test_fixture_move_to_twice(time_machine):
     time_machine.move_to(EPOCH)
     assert time.time() == EPOCH
 
     time_machine.move_to(EPOCH_PLUS_ONE_YEAR)
     assert time.time() == EPOCH_PLUS_ONE_YEAR
 
 
+def test_fixture_move_to_and_shift(time_machine):
+    time_machine.move_to(EPOCH, tick=False)
+    assert time.time() == EPOCH
+    time_machine.shift(100)
+    assert time.time() == EPOCH + 100
+
+
+def test_fixture_shift_without_move_to(time_machine):
+    with pytest.raises(RuntimeError):
+        time_machine.shift(100)
+
+
 # escape hatch tests