tests: rework cli tests and add test for readme API example

tests/_testutils.py

@@ -213,7 +213,9 @@ class VirtualBusDevice(BaseDriver):
 
     def initialize(self, *args, **kwargs):
         self.call_args['initialize'] = CallArgs(args, kwargs)
-        return self.get_status(**kwargs)
+        return [
+            ('Firmware version', '3.14.16', ''),
+        ]
 
     def get_status(self, *args, **kwargs):
         self.call_args['status'] = CallArgs(args, kwargs)
@@ -225,6 +227,15 @@ class VirtualBusDevice(BaseDriver):
             ('Hardware mode', True, ''),
         ]
 
+    def set_fixed_speed(self, *args, **kwargs):
+        self.call_args['set_fixed_speed'] = CallArgs(args, kwargs)
+
+    def set_speed_profile(self, *args, **kwargs):
+        self.call_args['set_speed_profile'] = CallArgs(args, kwargs)
+
+    def set_color(self, *args, **kwargs):
+        self.call_args['set_color'] = CallArgs(args, kwargs)
+
     @property
     def description(self):
         return 'Virtual Bus Device (experimental)'

tests/test_api.py

@@ -20,3 +20,57 @@ def test_entering_the_runtime_context_does_not_call_connect():
         # since __enter__ takes no arguments, if __enter__ calls connect it
         # will override dev.kwargs['connect'] with {}
         assert 'marker' in dev.call_args['connect'].kwargs
+
+
+def test_modified_readme_example(capsys):
+    from liquidctl import find_liquidctl_devices
+
+    first = True
+
+    # find all connected and supported devices on pseudo bus 'virtual'
+    devices = find_liquidctl_devices(bus='virtual')
+
+    for dev in devices:
+
+        # connect to the device (here a context manager is used, but the
+        # connection can also be manually managed)
+        with dev.connect():
+            print(f'{dev.description} at {dev.bus}:{dev.address}:')
+
+            # devices should be initialized after every boot (here we assume
+            # this has not been done before)
+            init_status = dev.initialize()
+
+            # print all data returned by initialize()
+            if init_status:
+                for key, value, unit in init_status:
+                    print(f'{key}: {value} {unit}')
+
+            # get regular status information from the device
+            status = dev.get_status()
+
+            # print all data returned by get_status()
+            for key, value, unit in status:
+                print(f'{key}: {value} {unit}')
+
+            # for a particular device, set the pump LEDs to red
+            if 'Virtual Bus Device' in dev.description:
+                print('setting pump to radical red')
+                radical_red = [0xff, 0x35, 0x5e]
+                dev.set_color(channel='pump', mode='fixed', colors=[radical_red])
+
+        # the context manager took care of automatically calling disconnect();
+        # when manually managing the connection, disconnect() must be called at
+        # some point even if an exception is raised
+
+        if first:
+            first = False
+            print()  # add a blank line between each device
+
+    # end of modified example; check that it more or less did what it should
+
+    out, _ = capsys.readouterr()
+    assert 'Virtual Bus Device (experimental) at virtual:virtual_address:' in out
+    assert 'Firmware version: 3.14.16' in out
+    assert 'Temperature: 30.4 °C' in out
+    assert 'setting pump to radical red' in out

tests/test_cli.py

@@ -45,7 +45,28 @@ def test_json_list(main):
     assert got == exp
 
 
-def assert_json_status_like(out):
+def test_json_initialize(main):
+    code, out, _ = main('test', '--bus', 'virtual', 'initialize', '--json')
+    assert code == 0
+
+    got = json.loads(out)
+    exp = [
+        {
+            'bus': 'virtual',
+            'address': 'virtual_address',
+            'description': 'Virtual Bus Device',
+            'status': [
+                { 'key': 'Firmware version', 'value': '3.14.16', 'unit': '' },
+            ]
+        }
+    ]
+    assert got == exp
+
+
+def test_json_status(main):
+    code, out, _ = main('test', '--bus', 'virtual', 'status', '--json')
+    assert code == 0
+
     got = json.loads(out)
     exp = [
         {
@@ -62,15 +83,3 @@ def assert_json_status_like(out):
         }
     ]
     assert got == exp
-
-
-def test_json_initialize(main):
-    code, out, _ = main('test', '--bus', 'virtual', 'initialize', '--json')
-    assert code == 0
-    assert_json_status_like(out)
-
-
-def test_json_status(main):
-    code, out, _ = main('test', '--bus', 'virtual', 'status', '--json')
-    assert code == 0
-    assert_json_status_like(out)