Add documentation to tests and utilities.

test/test_chat_text.py

@@ -1,9 +1,17 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Test small (single-frame) and large (multi-frame) messages over a high quality
+simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving data through the TNC and modem
+and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC. Tests both low- and
+high-bandwidth data frames (datac3 and datac1 respectively) from Codec2.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_chat_test_[12].py in separate processes to perform the data transfer.
 """
 
 import contextlib
@@ -33,7 +41,27 @@ bytes_out = b'{"dt":"f","fn":"zeit.txt","ft":"text\\/plain","d":"data:text\\/pla
 
 messages = [
     "This is a test chat...",
-    "This is a much longer message, hopefully longer than each of the datac1 and datac3 frames available to use in this modem. This should be long enought, but to err on the side of completeness this will string on for many more words before coming to the long awaited conclusion. We are not at the concluding point just yet because there is still more space to be taken up in the datac3 frame. Perhaps now would be a good place to terminate this test message, but perhaps not because we need a few more bytes. Here then we stop. This compresses so well that I need more data, even more stuff than is already here and included in the unreadable diatribe below, or is it a soliloquy? MyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5CgMyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5Cg=MyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5CgMyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5CgMyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5Cg=",
+    "This is a much longer message, hopefully longer than each of the datac1 and "
+    "datac3 frames available to use in this modem. This should be long enough, "
+    "but to err on the side of completeness this will string on for many more "
+    "words before coming to the long awaited conclusion. We are not at the "
+    "concluding point just yet because there is still more space to be taken up "
+    "in the datac3 frame. Perhaps now would be a good place to terminate this test "
+    "message, but perhaps not because we need a few more bytes. Here then we stop. "
+    "This compresses so well that I need more data, even more stuff than is already "
+    "here and included in the unreadable diatribe below, or is it a soliloquy? "
+    "MyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obm"
+    "UgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5"
+    "NjY5NzY1NTU4Nzc4MjA5CgMyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0"
+    "MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG"
+    "9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5Cg=MyBtb2Rlcywgb2huZSBjbGFzcwowL"
+    "jAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODk"
+    "xMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5CgMyBtb2R"
+    "lcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjIgbW9kZXMsIG9obmUgY2xhc"
+    "3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY2xhc3MKMC4wMDA5NjY5NzY"
+    "1NTU4Nzc4MjA5CgMyBtb2Rlcywgb2huZSBjbGFzcwowLjAwMDk2OTQ4MTE4MDk5MTg0MTcKCjI"
+    "gbW9kZXMsIG9obmUgY2xhc3MKMC4wMDA5NjY1NDUxODkxMjI1Mzk0CgoxIG1vZGUsIG9obmUgY"
+    "2xhc3MKMC4wMDA5NjY5NzY1NTU4Nzc4MjA5Cg=",
 ]
 PIPE_THREAD_RUNNING = True
 

test/test_datac0.py

@@ -1,9 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Test control frame commands over a high quality simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving select control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_datac0.py in separate process to perform the data transfer.
 """
 
 import contextlib
@@ -173,7 +179,6 @@ def analyze_results(station1: list, station2: list, call_list: list):
         # pytest.param("cq", marks=pytest.mark.xfail(reason="Too unstable for CI")),
     ],
 )
-# @pytest.mark.flaky(reruns=2)
 def test_datac0(frame_type: str, tmp_path):
     log_handler.setup_logging(filename=tmp_path / "test_datac0", level="DEBUG")
     log = structlog.get_logger("test_datac0")

test/test_helpers.py

@@ -1,5 +1,11 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
-Tests for the FreeDATA TNC state machine.
+Unit test common helper routines used throughout the TNC.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses no other files.
 """
 
 import sys

test/test_highsnr_stdio_C_P_datacx.py

@@ -1,5 +1,16 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
-Tests a high signal-to-noise ratio path with codec2 data formats using codec2 to transmit.
+Test small multiple-burst messages over a high quality simulated audio channel.
+
+Legacy test for sending / receiving frames through the codec2 modem
+and back through on the other station. Data injection initiates directly into
+codec2 API. Tests all three codec2 data frames.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_rx.py, sox and freedv_data_raw_tx in separate processeses to perform
+the audio tests.
 """
 
 # pylint: disable=global-statement, invalid-name, unused-import

test/test_highsnr_stdio_P_C_datacx.py

@@ -1,5 +1,16 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
-Tests a high signal-to-noise ratio path with codec2 data formats using codec2 to receive.
+Test small multiple-burst messages over a high quality simulated audio channel.
+
+Legacy test for sending / receiving frames through the codec2 modem
+and back through on the other station. Data injection initiates directly into
+codec2 API. Tests all three codec2 data frames.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_tx.py, sox, freedv_data_raw_rx and hexdump in separate processeses to
+perform the audio tests.
 """
 
 # pylint: disable=global-statement, invalid-name, unused-import

test/test_highsnr_stdio_P_P_datacx.py

@@ -1,5 +1,16 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
-Tests a high signal-to-noise ratio path with codec2 data formats.
+Test small multiple-burst messages over a high quality simulated audio channel.
+
+Legacy test for sending / receiving frames through the codec2 modem
+and back through on the other station. Data injection initiates directly into
+codec2 API. Tests all three codec2 data frames.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_rx.py and util_tx.py in separate processeses to perform
+the audio tests.
 """
 
 # pylint: disable=global-statement, invalid-name, unused-import

test/test_highsnr_stdio_P_P_multi.py

@@ -1,5 +1,16 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
-Tests a high signal-to-noise ratio path with multiple codec2 data formats.
+Test small multiple-burst messages over a high quality simulated audio channel.
+
+Legacy test for sending / receiving frames through the codec2 modem
+and back through on the other station. Data injection initiates directly into
+codec2 API. Tests all three codec2 data frames simultaneously.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_multimode_tx.py and util_multimode_tx in separate processeses to perform
+the audio tests.
 """
 
 # pylint: disable=global-statement, invalid-name, unused-import

test/test_tnc.py

@@ -1,5 +1,16 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+Test connect frame commands over a high quality simulated audio channel.
+
+Near end-to-end test for sending / receiving connection control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_tnc_I[RS]S.py in separate process to perform the data transfer.
+"""
 
 import multiprocessing
 import os

test/test_tnc_states.py

@@ -1,5 +1,15 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
-Tests for the FreeDATA TNC state machine.
+Test control frame messages over a high quality simulated audio channel.
+
+Near end-to-end test for sending / receiving select control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Can be invoked from CMake, pytest, coverage or directly.
+
+Uses util_datac0.py in separate process to perform the data transfer.
 """
 
 import multiprocessing

test/util_chat_text_1.py

@@ -1,9 +1,12 @@
-#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Send-side station emulator for connect frame tests over a high quality simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving connection control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Invoked from test_chat_text.py.
 """
 
 import base64

test/util_chat_text_2.py

@@ -1,9 +1,12 @@
-#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Receive-side station emulator for connect frame tests over a high quality simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving connection control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Invoked from test_chat_text.py.
 """
 
 import time

test/util_datac0.py

@@ -1,9 +1,13 @@
-#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Send- and receive-side station emulator for control frame tests over a high quality
+simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving control frames through the TNC and modem
+and back through on the other station. Data injection initiates from the queue used
+by the daemon process into and out of the TNC.
+
+Invoked from test_datac0.py.
 """
 
 import json

test/util_multimode_rx.py

@@ -1,5 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+Receive-side station emulator for test frame tests over a high quality audio channel
+using a physical sound card or STDIO.
+
+Legacy test for sending / receiving connection test frames through the codec2 and
+back through on the other station. Data injection initiates directly through
+the codec2 API. Tests all three codec2 data frames simultaneously.
+
+Invoked from CMake, test_highsnr_stdio_P_P_multi.py, and many test_virtual[1-3]*.sh.
+"""
 
 import argparse
 import ctypes

test/util_multimode_tx.py

@@ -1,6 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+Send-side station emulator for test frame tests over a high quality audio channel
+using a physical sound card or STDIO.
 
+Legacy test for sending / receiving connection test frames through the codec2 and
+back through on the other station. Data injection initiates directly through
+the codec2 API. Tests all three codec2 data frames simultaneously.
+
+Invoked from CMake, test_highsnr_stdio_P_P_multi.py, and many test_virtual[1-3]*.sh.
+"""
 
 import argparse
 import ctypes

test/util_rx.py

@@ -1,9 +1,14 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Receive-side station emulator for test frame tests over a high quality audio channel
+using a physical sound card or STDIO.
 
-@author: DJ2LS
+Legacy test for sending / receiving connection test frames through the codec2 and
+back through on the other station. Data injection initiates directly through
+the codec2 API.
+
+Invoked from CMake, test_highsnr_stdio_{P_C, P_P}_datacx.py, and many test_virtual[1-3]*.sh.
 """
 
 import argparse

test/util_tnc_IRS.py

@@ -1,9 +1,12 @@
-#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Receive-side station emulator for connect frame tests over a high quality simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving connection control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Invoked from test_tnc.py.
 """
 
 import signal

test/util_tnc_ISS.py

@@ -1,9 +1,12 @@
-#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Created on Wed Dec 23 07:04:24 2020
+Send-side station emulator for connect frame tests over a high quality simulated audio channel.
 
-@author: DJ2LS
+Near end-to-end test for sending / receiving connection control frames through the
+TNC and modem and back through on the other station. Data injection initiates from the
+queue used by the daemon process into and out of the TNC.
+
+Invoked from test_tnc.py.
 """
 
 import json

test/util_tx.py

@@ -1,6 +1,15 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+"""
+Send-side station emulator for test frame tests over a high quality audio channel
+using a physical sound card or STDIO.
 
+Legacy test for sending / receiving connection test frames through the codec2 and
+back through on the other station. Data injection initiates directly through
+the codec2 API.
+
+Invoked from CMake, test_highsnr_stdio_{P_C, P_P}_datacx.py, and many test_virtual[1-3]*.sh.
+"""
 
 import argparse
 import ctypes