docs: Doc tweak

Author: Alan Christie

tests/api_adapter.py

@@ -1,3 +1,20 @@
+"""The UnitTest API Adapter.
+
+This 'simulates' the sort of responses you can expect from the DM API/Model.
+It stimulates a Database by using dictionaries that are pickled to (and unpickled from)
+the file system after acquiring a lock object. Pickling is required to
+(because it's a simple built-in mechanism in Python) to persist data
+between processes in the multi-processing framework we run in because we ultimately need
+to simulate the multi-pod messaging-based framework of the DM.
+
+A separate pickle file is used for each 'simulated' model table and the object
+initialiser resets all the pickle files (located in 'tests/pickle-files').
+
+Job definitions are loaded (statically) from the content of the
+'tests/job-definitions/job-definitions.yaml' file and yielded through the 'get_job()'
+method.
+"""
+
 import os
 from multiprocessing import Lock
 from pickle import Pickler, Unpickler

tests/config.py

@@ -1,5 +1,5 @@
 """An emulation of the Data Manager config module.
-A location of common constants."""
+A module of common constants."""
 
 # The project ID used in the tests (there is only one atm)
 TEST_PROJECT_ID: str = "project-00000000-0000-0000-0000-000000000001"

tests/instance_launcher.py

@@ -1,3 +1,20 @@
+"""The UnitTest Instance Launcher.
+
+It runs Python module modules defined in the unit-test job-definitions file.
+
+It also uses the UnitTestMessageDispatcher to send a simulated
+'end of instance' PodMessage  that are normally sent to the WorkflowEngine's
+'handle_message()' method by the underlying queue. The 'exit code' of the module is
+passed to the WorkflowEngine through the PodMessage - so if the module fails
+(i.e. returns a non-zero exit code) then the WorkflowEngine will see that the PodMessage.
+This allows you to write jobs that fail and see how the WorkflowEngine responds.
+
+Instances (jobs) are executed in a simulated project directory - actually
+tests/project-root/project-00000000-0000-0000-0000-000000000001. The project directory
+is created by the UnitTestInstanceLauncher and is also wiped as the launcher initialises
+(so the start of each test begins with an empty project directory).
+"""
+
 import json
 import os
 import shutil
@@ -28,22 +45,7 @@ def project_file_exists(file_name: str) -> bool:
 
 
 class UnitTestInstanceLauncher(InstanceLauncher):
-    """A unit test instance launcher, which runs the
-    Python module that matches the job name in the provided specification.
-
-    The Python module used to satisfy the step matches the job name in the
-    step specification. If the step_specification's 'job' is 'my_job', then the launcher
-    will run the Python module 'my_job.py' in the 'jobs' directory. The
-    module is run synchronously - i.e. the launch() method waits for the
-    module to complete.
-
-    It then uses the UnitTestMessageDispatcher to send a simulated
-    'end of instance' PodMessage  that will be received by the WorkflowEngine's
-    'handle_message()' method. The 'exit code' of the module is passed to the
-    WorkflowEngine through the PodMessage - so if the module fails (i.e. returns
-    a non-zero exit code) then the WorkflowEngine will see that the PodMessage.
-    This allows you to write jobs that fail and see how the WorkflowEngine responds.
-    """
+    """A unit test instance launcher."""
 
     def __init__(
         self, api_adapter: UnitTestAPIAdapter, msg_dispatcher: UnitTestMessageDispatcher

tests/message_dispatcher.py

@@ -1,3 +1,10 @@
+"""The UnitTest Message Dispatcher.
+
+A very simple object that relies on an underlying message queue.
+Here we offer a minimal implementation that simply sends a (protocol buffer) message
+to the queue.
+"""
+
 from google.protobuf.message import Message
 
 from tests.message_queue import UnitTestMessageQueue

tests/message_queue.py

@@ -1,3 +1,18 @@
+"""The UnitTest Message Queue.
+
+A simulation of the RabbitMQ queue in the DM. It has a 'put()' method that
+serializes ProtocolBuffer messages and places them on a queue. The 'run()' method
+picks messages off the queue and deserializes them back into ProtocolBuffer objects
+before sending them to a receiver function.
+
+In the UnitTest framework the receiver is the WorkflowEngine's 'handle_message()'
+function.
+
+The queue needs to be started (before any testing) and stopped (after testing).
+This is typically done by the pytest 'basic engine' fixture in
+'test_workflow_engine_examples.py'.
+"""
+
 from contextlib import suppress
 from multiprocessing import Event, Process, Queue
 from queue import Empty

tests/test_decoder_minimal.py

@@ -1,4 +1,3 @@
-# Tests for the decoder package.
 import os
 from typing import Any, Dict
 

tests/test_test_api_adapter.py

@@ -1,5 +1,3 @@
-# Tests for the decoder package.
-
 import pytest
 
 pytestmark = pytest.mark.unit

tests/test_test_instance_launcher.py

@@ -1,4 +1,3 @@
-# Tests for the decoder package.
 import json
 
 import pytest

tests/test_test_message_dispatcher.py

@@ -1,5 +1,3 @@
-# Tests for the decoder package.
-
 from datetime import datetime, timezone
 
 import pytest
@@ -15,10 +13,16 @@
 @pytest.fixture
 def basic_dispatcher():
     utmq = UnitTestMessageQueue()
-    return UnitTestMessageDispatcher(msg_queue=utmq)
+    utmd = UnitTestMessageDispatcher(msg_queue=utmq)
+    utmq.start()
+
+    yield utmd
+
+    utmq.stop()
+    utmq.join()
 
 
-def test_get_nop_job(basic_dispatcher):
+def test_send_start(basic_dispatcher):
     # Arrange
     msg = WorkflowMessage()
     msg.timestamp = f"{datetime.now(timezone.utc).isoformat()}Z"

tests/test_test_message_queue.py

@@ -24,20 +24,13 @@ def basic_queue():
     receiver = Receiver()
     utmq = UnitTestMessageQueue(receiver=receiver.handle_msg)
     utmq.start()
+
     yield utmq
+
     utmq.stop()
     utmq.join()
 
 
-def test_start_and_stop(basic_queue):
-    # Arrange
-
-    # Act
-    pass
-
-    # Assert
-
-
 def test_send_messages(basic_queue):
     # Arrange