move patch_motors to dodal.testing (#1513)

* move patch_motors to dodal.testing

* Added arguments for default values with doc string

* Updated docs

---------

Co-authored-by: Dominic Oram <[email protected]>

Author: oliwenmandiamond

docs/how-to/write-tests.md

@@ -7,6 +7,9 @@ Testing is essential to maintain the integrity and reliability of the codebase.
 - **Unit Tests**: Place unit tests for individual components in the `tests` directory, but take care to mirror the file structure of the `src` folder with the corresponding code files. Use the `test_*.py` naming convention for test files.
 - **System Tests**: Tests that interact with DLS infrastructure, network, and filesystem should be placed in the top-level `systems_test` folder. This separation ensures that these tests are easily identifiable and can be run independently from unit tests.
 
+Useful functions for testing that can be reused across multiple tests for common devices and for external plan repositories belong in the `dodal/testing` directory. For example, when mocking a `Motor` device, all of the signals will default to zero, which will cause errors when trying to move. The `patch_motor` and `patch_all_motors` functions, found in `dodal.testing`, will populate the mocked motor with useful default values for the signals so that it can still be used in tests.
+
+
 ## Writing a test for a device
 We aim for high test coverage in dodal with small, modular test functions. To achieve this, we need to test the relevant methods by writing tests for the class/method we are creating or changing, checking for the expected behaviour. We shouldn't need to write tests for parent classes unless we alter their behaviour.
 

src/dodal/devices/util/test_utils.py

@@ -0,0 +1,3 @@
+from .setup import patch_all_motors, patch_motor
+
+__all__ = ["patch_motor", "patch_all_motors"]

src/dodal/testing/__init__.py

@@ -0,0 +1,67 @@
+from contextlib import ExitStack
+
+from ophyd_async.core import Device
+from ophyd_async.epics.motor import Motor
+from ophyd_async.testing import (
+    callback_on_mock_put,
+    set_mock_value,
+)
+
+
+def patch_motor(
+    motor: Motor,
+    initial_position: float = 0,
+    deadband: float = 0.001,
+    velocity: float = 3,
+    max_velocity: float = 5,
+    low_limit_travel: float = float("-inf"),
+    high_limit_travel: float = float("inf"),
+):
+    """
+    Patch a mock motor with sensible default values so that it can still be used in
+    tests and plans without running into errors as default values are zero.
+
+    Parameters:
+        motor: The mock motor to set mock values with.
+        initial_position: The default initial position of the motor to be set.
+        deadband: The tolerance between readback value and demand setpoint which the
+                  motor is considered at position.
+        velocity: Requested move speed when the mock motor moves.
+        max_velocity: The maximum allowable velocity that can be set for the motor.
+        low_limit_travel: The lower limit that the motor can move to.
+        high_limit_travel: The higher limit that the motor can move to.
+    """
+    set_mock_value(motor.user_setpoint, initial_position)
+    set_mock_value(motor.user_readback, initial_position)
+    set_mock_value(motor.deadband, deadband)
+    set_mock_value(motor.motor_done_move, 1)
+    set_mock_value(motor.velocity, velocity)
+    set_mock_value(motor.max_velocity, max_velocity)
+    set_mock_value(motor.low_limit_travel, low_limit_travel)
+    set_mock_value(motor.high_limit_travel, high_limit_travel)
+    return callback_on_mock_put(
+        motor.user_setpoint,
+        lambda pos, *args, **kwargs: set_mock_value(motor.user_readback, pos),
+    )
+
+
+def patch_all_motors(parent_device: Device):
+    """
+    Check all children of a device and patch any motors with mock values.
+
+    Parameters:
+        parent_device: The device that hold motor(s) as children.
+    """
+    motors = []
+
+    def recursively_find_motors(device: Device):
+        for _, child_device in device.children():
+            if isinstance(child_device, Motor):
+                motors.append(child_device)
+            recursively_find_motors(child_device)
+
+    recursively_find_motors(parent_device)
+    motor_patch_stack = ExitStack()
+    for motor in motors:
+        motor_patch_stack.enter_context(patch_motor(motor))
+    return motor_patch_stack

src/dodal/testing/setup.py

@@ -5,7 +5,7 @@
 
 from dodal.beamlines import aithre
 from dodal.devices.aithre_lasershaping.goniometer import Goniometer
-from dodal.devices.util.test_utils import patch_all_motors
+from dodal.testing import patch_all_motors
 
 
 @pytest.fixture

tests/devices/aithre_lasershaping/test_goniometer.py

@@ -10,8 +10,8 @@
 from dodal.devices.i03.dcm import DCM
 from dodal.devices.i03.undulator_dcm import UndulatorDCM
 from dodal.devices.undulator import AccessError, Undulator
-from dodal.devices.util.test_utils import patch_motor
 from dodal.log import LOGGER
+from dodal.testing import patch_motor
 from tests.devices.test_daq_configuration import MOCK_DAQ_CONFIG_PATH
 from tests.devices.test_daq_configuration.lookup import (
     BEAMLINE_ENERGY_DCM_PITCH_CONVERTER_TXT,

tests/devices/i03/test_undulator_dcm.py

@@ -13,7 +13,7 @@
     EncReset,
     LaserSettings,
 )
-from dodal.devices.util.test_utils import patch_all_motors
+from dodal.testing import patch_all_motors
 
 
 @pytest.fixture

tests/devices/i24/test_pmac.py

@@ -3,7 +3,7 @@
 from bluesky import RunEngine
 
 from dodal.devices.i24.vgonio import VerticalGoniometer
-from dodal.devices.util.test_utils import patch_all_motors
+from dodal.testing import patch_all_motors
 
 
 @pytest.fixture

tests/devices/i24/test_vgonio.py

@@ -10,7 +10,7 @@
 
 from dodal.common.beamlines.beamline_parameters import GDABeamlineParameters
 from dodal.devices.i03 import Beamstop, BeamstopPositions
-from dodal.devices.util.test_utils import patch_motor
+from dodal.testing import patch_motor
 from tests.common.beamlines.test_beamline_parameters import TEST_BEAMLINE_PARAMETERS_TXT
 
 

tests/devices/mx_phase1/test_beamstop.py

@@ -18,7 +18,7 @@
     wait_for_tip_to_be_found,
 )
 from dodal.devices.smargon import Smargon
-from dodal.devices.util.test_utils import patch_all_motors
+from dodal.testing import patch_all_motors
 
 
 def test_bottom_right_from_top_left():