Add better comments to test_gallery

tests/unit_tests/test_gallery.py

@@ -99,19 +99,27 @@ def test_gallery_compatible_protocol():
 
 def test_gallery_thing_finds_all_providers(simulation_test_env):
     """Check the gallery identifies the correct Things that will provide data."""
+    # Started the full simulation in a test environment.
+    # Get the gallery and 3 other Things from the environment.
     gallery = simulation_test_env.get_thing_by_name("gallery")
     snake_workflow = simulation_test_env.get_thing_by_name("snake_workflow")
     smart_scan = simulation_test_env.get_thing_by_name("smart_scan")
     camera = simulation_test_env.get_thing_by_name("camera")
 
+    # Check that all_ofm_things are correct. Camera and smart scan are ofm things
+    # snake workflow is not.
     assert snake_workflow not in gallery.all_ofm_things.values()
     assert camera in gallery.all_ofm_things.values()
     assert smart_scan in gallery.all_ofm_things.values()
 
+    # Also check that both the camera and smart scan are recognised as gallery
+    # providers based on the protocol.
     assert snake_workflow not in gallery.gallery_providing_things.values()
     assert camera in gallery.gallery_providing_things.values()
     assert smart_scan in gallery.gallery_providing_things.values()
 
+    # Also check the runtime checkable protocol GalleryCompatibleThing works directly
+    # when called with isinstance.
     assert not isinstance(snake_workflow, GalleryCompatibleThing)
     assert isinstance(smart_scan, GalleryCompatibleThing)
 
@@ -158,11 +166,12 @@ def minimal_gallery_env():
 
 def test_gallery_lists_data(minimal_gallery_env, mocker, caplog):
     """Test that the gallery calls all gallery things to list data."""
-    # Create a config with the minimal Thing and the bad Thing
+    # Create a config with the two minimal things and get the things by name.
     gallery = minimal_gallery_env.get_thing_by_name("gallery")
     thing_1 = minimal_gallery_env.get_thing_by_name("minimal_thing1")
     thing_2 = minimal_gallery_env.get_thing_by_name("minimal_thing2")
 
+    # Add some mock data to them the gallery data things
     thing_1_data = [
         MockGalleryData(mock="thing_1", foobar=1),
         MockGalleryData(mock="thing_1", foobar=2),
@@ -173,9 +182,11 @@ def test_gallery_lists_data(minimal_gallery_env, mocker, caplog):
         MockGalleryData(mock="thing_2", foobar=2),
     ]
 
+    # Also mock the get_data_for_gallery methods.
     mocker.patch.object(thing_1, "get_data_for_gallery", return_value=thing_1_data)
     mocker.patch.object(thing_2, "get_data_for_gallery", return_value=thing_2_data)
 
+    # Set the expected returns.
     thing_1_return = [
         {"mock": "thing_1", "foobar": 1},
         {"mock": "thing_1", "foobar": 2},
@@ -185,11 +196,15 @@ def test_gallery_lists_data(minimal_gallery_env, mocker, caplog):
         {"mock": "thing_2", "foobar": 2},
     ]
 
+    # Check that the gallery returns the expected concatenated data
     assert gallery.list_data == thing_1_return + thing_2_return
 
+    # Check that if the first thing called throws an error the data from the second
+    # thing is still returned.
     thing_1.get_data_for_gallery.side_effect = RuntimeError
     with caplog.at_level(logging.INFO):
         assert gallery.list_data == thing_2_return
+    # Check an error was logged about the first thing failing to collect data.
     assert len(caplog.records) == 1
     assert caplog.records[0].levelname == "ERROR"
 
@@ -233,16 +248,19 @@ def test_gallery_calls_delete(test_case, minimal_gallery_env, mocker):
     thing_1 = minimal_gallery_env.get_thing_by_name("minimal_thing1")
     thing_2 = minimal_gallery_env.get_thing_by_name("minimal_thing2")
 
+    # Set up the desired side effect for the test case.
     mocker.patch.object(
         thing_1, "delete_all_gallery_items", side_effect=test_case.thing_1_side_effect
     )
     mocker.patch.object(thing_2, "delete_all_gallery_items")
 
+    # Call delete_all_data, checking for errors if the test case expects an error.
     if test_case.action_errors:
         with pytest.raises(test_case.thing_1_side_effect):
             gallery.delete_all_data()
     else:
         gallery.delete_all_data()
 
+    # Check the call counts are as expected from the test case.
     assert thing_1.delete_all_gallery_items.call_count == 1
     assert thing_2.delete_all_gallery_items.call_count == test_case.thing_2_call_count