From 20bc84c856a3b54e4c91dbab832966fe0da3fba8 Mon Sep 17 00:00:00 2001
From: kevin <kevin@larke.org>
Date: Fri, 29 Nov 2024 17:06:48 -0500
Subject: [PATCH] README.md : Updates to document utilities and tests provided
 by main.cpp/main.cfg.

---
 README.md | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 156 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d3c8e03..06bbbc7 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,159 @@
-libcw Testing and Development App
+# libcw Testing and Development App
+
+Command line:
+```
+cwtest <file.cfg> <label>
+```
+
+Where `<file.cfg>` refers to a libcw configuration file file with the form:
+```
+{
+  test: {
+  
+    `program_0`: {
+      a:1
+      b:"hello"
+    },
+    
+    `program_1`: {
+      arg0:["abc","def"]
+      b:{ a:73, z:[19] }
+    }
+}
+```
+
+`<label>` refers to a specific set of parameters which are associated with a library function.
+See `main.cpp` `mode_array[]` for the mapping of labels to functions.
+
+The goal of `cwtest` is to be able to easily exercize `libcw` functions with a flexible
+sets of parameters.  The configuration file provides the parameters.
+
+
+## MIDI
+
+# midiDeviceReport
+
+List The current set of MIID hardware devices and their ports.
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg midiDeviceReport
+```
+
+# midiDevice
+
+Interactive testing of the MIDI input file device start/pause/unpause/stop functions.
+Compares the time between MIDI events as generated by the device to the actual time between the
+events as listed in the file.
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg midiDevice
+```
+
+## Serial
+
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg midiDeviceReport
+```
+
+See `serialPortSrvTest()` in `cwSerialPortSrv.cpp`.
+
+This is an interactive test of the serial port send/receive functions.
+The test function continuously transmits ASCII values '0' through 'z' to external devices `/dev/ttyACM0` and '/dev/ttyACM1`.
+Those devices should increment the received value and send it back, where it is receieved and printed to the console.
+Firmware to run on ATMEGA328 based devices, like the Arduino Uno, is provided in `study/serial/arduino_xmt_recv/main.c`.
+
+## wesockSrv
+
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg websockSrv
+```
+
+See `websockSrvTest()` in `cwWebSockSvr.cpp`.
+
+Interactive websocket server testing application.
+Run the app and navigate in a web browser to `localhost:5687` to run the application.
+
+## nbmpscQueue
+
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg nbmpscQueue
+```
+
+See `test()` in cwNbMpScQueue.cpp.
+
+Run the non-blocking, multiple producer, single consumer queue for 'testDurMs' millisecdons
+and write the result into 'out_fname'.  This is the queue used by the websocket implementation
+(See cwWebSock) to support incoming calls form multiple threads without blocking the calling threads.
+
+## audioDevAlsa
+
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg audioDevAlsa
+```
+
+See `report()` in `cwAudioDeviceAlsa.cpp`.
+
+Generate a list of devices and device attributes directly from the ALSA sub-system.
+
+
+## audioDevRpt
+```
+cwtest ~/src/cwtest/src/cwtest/cfg/main.cfg audioDevRpt
+```
+
+See `report()` in `cwAudioDevice.cpp`.
+
+Generate a list of devices and device attributes from libcw.  This will include audio file based devices.
+
+
+
+
+
+
+
+## Run Unit Tests:
+
+These test are run by the libcw testing framework in cwTest.h/cpp.
+The configuraton for the unit tests is in `src/cwtest/src/cfg/test/main.cfg`.
+
+1. Add a new test:
+    - Create a function like this: rc_t my_test_func(const test_args_t& args);
+    - Add the module name, function pair to the `_test_map[]` in cwTest.cpp.
+    - Add an entry to the test parameters cfg. below.
+        + Name the test case (e.g. `test_0`) and give the test parameters. 
+        + On the call to my_test_func() the args.module_args is set to the 'module_args' dictionary defined in the cfg.
+        + Likewise args.test_args is set to the 'test_args' dictionary referenced by the test name label 'e.g. test_0:{ my_arg:1 }'.
+	  
+    - Run the test like this: `cwtest test/main.cfg test /my_module test_0 echo` to see the results of the test run.
+      The results of this run will be written into `/cur/my_test/test_0/log.txt`
+  
+    - Once the results have been validated copy the output from 'cur' to the `/ref/my_test/test_0/log.txt.`
+    
+    - Verify that the test passes: `cwtest test/main.cfg test /my_module test_0 compare`
+
+
+2. The test spec. is recursive. Modules can be listed inside of modules.  (e.g. 'lex' and 'flow').
+
+3. If a module spec. does not have an embedded
+      'module' or 'module_args' then the cases may
+      be listed without a 'cases' label.
+      (e.g. 'filesys','object', 'vop')
+    
+4. Command line args:
+
+      Parameter     |  Description
+    ----------------|------------------------------------------------------------------
+      <module_path> | 'all'  (required) The module path always begins with a '/'.
+      <test_label>  | 'all'  (required)
+      'gen_report'  | Print modulue/test label.
+      'compare'     | Run compare pass.
+      'echo'        | Print the generated test output to the console.
+      'args'        | All command line args after 'args' are passed to the tests.
+    
+5. Example command lines:
+```
+      cwtest ~/src/cwtest/src/cwtest/cfg/test/main.cfg test /lex test_0 gen
+      cwtest ~/src/cwtest/src/cwtest/cfg/test/main.cfg test /flow test_0 compare
+```
+
 
 
 # GDB Setup: