Merge pull request #5486 from jenshnielsen/move_test_utils

Move DriverTestCase and mock Instruments out of tests module

docs/changes/newsfragments/5486.new

@@ -0,0 +1,3 @@
+Mock instruments have been moved from `qcodes.tests.instrument_mocks` to `qcodes.instrument_drivers.mock_instruments` and `DriverTestCase` from
+`qcodes.tests.driver_test_case` to `qcodes.extensions`. This is in preparation for no longer shipping `qcodes.tests` as part of the
+public api. The previous locations remain functional but will be deprecated after one release.

src/qcodes/dist/tests/station/example.station.yaml

@@ -48,12 +48,12 @@ instruments:
     add_parameters:
       Bx: {source: ch01.fine_volt, label: Bx, unit: T, scale: 28, limits: [-1, 1], monitor: true}
   mock_dac:
-    type: qcodes.tests.instrument_mocks.DummyInstrument
+    type: qcodes.instrument_drivers.mock_instruments.DummyInstrument
     enable_forced_reconnect: true
     init:
       gates: {"ch1", "ch2"}
     add_parameters:
       Bx: {source: ch1, label: Bx, unit: T, scale: 28, limits: [-1, 1], monitor: true}
   mock_dac2:
-    type: qcodes.tests.instrument_mocks.DummyInstrument
+    type: qcodes.instrument_drivers.mock_instruments.DummyInstrument
     enable_forced_reconnect: true

src/qcodes/extensions/__init__.py

@@ -2,7 +2,12 @@
 The extensions module contains smaller modules that extend the functionality of QCoDeS.
 These modules may import from all of QCoDeS but do not themselves get imported into QCoDeS.
 """
+from ._driver_test_case import DriverTestCase
 from ._log_export_info import log_dataset_export_info
 from .installation import register_station_schema_with_vscode
 
-__all__ = ["register_station_schema_with_vscode", "log_dataset_export_info"]
+__all__ = [
+    "register_station_schema_with_vscode",
+    "log_dataset_export_info",
+    "DriverTestCase",
+]

src/qcodes/extensions/_driver_test_case.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import unittest
+
+from qcodes.instrument import Instrument
+
+"""
+This module defines:
+
+- `DriverTestCase`: a `TestCase` subclass meant for testing instrument drivers
+
+Using `DriverTestCase` is pretty easy:
+
+- Inherit from this class instead of from the base `unittest.TestCase`
+
+- Provide a driver class variable that points to the Instrument class
+
+- In your tests, `self.instrument` is the latest instance of this class.
+
+- If your test case includes a `setUpClass` method, make sure to call
+  `super().setUpClass()`, because that's where we find the latest instance of
+  this `Instrument`, or skip the test case if no instances are found.
+"""
+
+
+class DriverTestCase(unittest.TestCase):
+    # override this in a subclass
+    driver: type[Instrument] | None = None
+    instrument: Instrument
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        if cls is DriverTestCase:
+            return
+
+        if cls.driver is None:
+            raise TypeError("you must set a driver for " + cls.__name__)
+
+        instances = cls.driver.instances()
+        name = cls.driver.__name__
+
+        if not instances:
+            msg = f"no instances of {name} found"
+            if getattr(cls, "noskip", False):
+                # just to test this class, we need to disallow skipping
+                raise ValueError(msg)
+            else:
+                raise unittest.SkipTest(msg)
+
+        if len(instances) == 1:
+            print(f"***** found one {name}, testing *****")
+        else:
+            print(
+                f"***** found {len(instances)} instances of {name}; "
+                "testing the last one *****"
+            )
+
+        cls.instrument = instances[-1]