cwtest/README.md

# 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:

    set env LD_LIBRARY_PATH /home/kevin/src/libcm/build/linux/debug/lib
    r ~/src/cwtest/src/cwtest/cfg/main.cfg mtx

    // if problems occur with gdb hanging while download debuginfo 
    sudo dnf upgrade --enablerepo=*-debuginfo "*-debuginfo"   # update all debuginfo files

    r ~/src/cwtest/src/cwtest/cfg/video/video.cfg preset_sel  record_fn m302-325 beg_play_loc 9187 end_play_loc 10109
    r ~/src/cwtest/src/cwtest/cfg/video/video.cfg preset_sel  record_fn m350-458 beg_play_loc 12431 end_play_loc 14726
    r ~/src/cwtest/src/cwtest/cfg/video/video.cfg preset_sel  record_fn m1_283 beg_play_loc 0 end_play_loc 8452
    
    r ~/src/cwtest/src/cwtest/cfg/gutim_full/gutim.cfg preset_sel  record_fn m1_458 beg_play_loc 327 end_play_loc 396
	
	
     
# Valgrind setup

    export LD_LIBRARY_PATH=~/src/libcm/build/linux/debug/lib
    valgrind --leak-check=yes --log-file=vg0.txt ./cwtest  ~/src/cwtest/src/cwtest/cfg/main.cfg mtx
	
# Installation

Dependencies:

- libwebsockets-devel
- fftw-devel
- libcm: lapack-devel
-       atlas-devel

#Design Questions:

How should errors be presented to the user? developer?


#To Do:

### 

All callbacks should return meaningful result codes.


### UI Properties

    name            - becomes the HTML id for this element
    appId             application id for this element
    title             label or title for this element
    className         Base class name for this element. All elements have a built-in default class name.
    addClassName      Add this class name to the class name.
    clickable         This elemnt will send a 'click' msg when clicked.
    enable            This element is enabled
    visible           This element is visible.

# Preset Select
   
+ If the the parsing of the main cfg file fails the app crashes in main.cpp with a double free.
+ play on preset letter select
+ allow the network to be reloaded without restarting the program
+ create an interactive spec-dist panel to experiment with presets


REVIEW:
+ gain problem
- was it really the transition bug and not a gain bug?
- FFT normalization
- Float/Int conversion on ALSA output
- create a metering object to examine signal at various places in network
- add compressor/limiter like in cm based network



DONE:
+ save preset check box state.
+ verify that all fragments are saved and restored
+ UI:         remove 'Filename' entry box.
+ flow proc:  gain, audio channel split map, audio channel merge map, fixed delay 
+ Fix CPU usage: work around for serial port server.
+ App:        apply wet/dry and gain when new presets are loaded.
+ App:        add 'Note' to fragment 
+ App:        add per fragment play control with begin/end locations
+ UI:         reorganinze top panel layout
+ App:        Add a status box to report errors and warnings to the user.
+ App:        Send log output to "Log" UI.
+ App:        When a invalid value is entered (thereby disabling a control) a message should be written to the status box.
+ App:        Add ranges to numeric controls.
+ App:        What happens when an invalid value is entered in a GUI control?
+ App:        interactive wet in gain, wet out gain, dry gain, piano midi enable, sampler midi enable, sampler delay
+ App:        interactive print network
+ App:        automatically load on start
+ flow:       Allow setting a specific variable value from a network preset
+ preset_sel: The sampler requires a different velocity map than the piano. The piano was scaled down but now the sampler is too quiet.
+ preset_set: deleting a fragment does not automatically fill in the missing location space.
+ preset_sel: backup to numbered file on save
+ preset_sel: Velocity of the individual notes of chords should be scaled to such that their sum matches the dynamic value.
+ libcw:      Make IO sub-systems optionally synchronous
+ UI:         clear UI when the app disconnects.
+ UI: Add an error indicator and API for each control (e.g. border set to red)
+ UI: Add the ability to order child lists via the 'order' attribute.
+ UI: Add API to delete a UI element
+ UI: add HTML class and name assignments to row/col div's.  (See 'name' and 'addClassName' attribute.)
+ UI: add min/max/incr/decpl attributes to numeric variables (See uiSetNumbRange.)

+ PresetSel: Select and highlight a fragment.
+ PresetSel: + test adding,deleting, saving and restoring fragment records
+ Enable 'Delete' button when a fragment is selected.