/*! @page exa_qutest Examples for QUTest Unit Testing Harness
@tableofcontents
The examples in the qpcpp/examples/qutest directory demonstrate how to test embedded code with the [QUTest](https://www.state-machine.com/qtools/qutest.html) unit testing harness. Currently, the following examples are provided:
- blinky — Simple "Blinky" single-active-object application
- dpp — DPP application from Chapter 9 of PSiCC2
- evt-par — testing events with parameters
- qhsmtst — Test State Machine based on QP::QHsm with QM model
- qmsmtst — Test State Machine based on QP::QMsm with QM model
- unity_basic — Comparison of a basic testing with Unity and QUTest
- unity_mock — Comparison of a advanced testing (mocking) with Unity and QUTest
@section exa_qutest-dir General Code Organization
The projects within the examples/qutest directory have the customary structure used for testing. The production code to be tested is located in the src sub-directory. The testing code is located in the test_... sub-folder(s). The following directory tree illustrates the structure for the `dpp` example:
- examples/
- qutest/ — Examples for QUTest unit testing harness
- dpp/ — The simple Blinky example
- src/ — source code under test A
- bsp.h — BSP header
- dpp.h — DPP header
- dpp.qm — DPP model
- philo.c — `Philo` active object
- table.c — `Table` active object
- test_philo/ — code for unit testing of `Philo` AO B
- Makefile — cross-platform makefile (host)
- test_philo.c — test fixture for `Philo` AO
- test_philo.py — test script for `Philo` (Python)
- test_philo.tcl — test script for `Philo` (Tcl)
- test_table/ — code for unit testing of `Table` AO B
- Makefile — cross-platform makefile (host)
- test_philo.c — test fixture for `Table` AO
- test_philo.py — test script for `Table` (Python)
- test_philo.tcl — test script for `Table` (Tcl)
- test_dpp/ — code for unit testing of DPP application C
- Makefile — cross-platform makefile (host)
- make_efm32 — makefile for the EFM32 **embedded board**
- make_tm4c123 — makefile for the TM4C123 **embedded board**
- main.c — `main()` function for DPP application
- test_dpp.c — test fixture for DPP application
- test_init.py — test script for DPP initialization (Python)
- test_init.tcl — test script for DPP initialization (Tcl)
- test_tick.py — test script for DPP tick processing (Python)
- test_tick.tcl — test script for DPP tick processing (Tcl)
- .../ — Other QUTest examples...
- target_efm32/ — Code for the **embedded target** (EFM32) D
- target_tm4c123/ — Code for the **embedded target** (TM4C123) D
- A The src sub-directory contains the production code to be tested. This directory contains the .qm model file as well as the generated code from the model.
- B The test_philo sub-directory contains the unit test code for a component, such as `Philo` in this case. Here, you can find the test_*.c **test fixture**, the test scripts test_*.py (Python) and test_*.tcl (Tcl) as well as the cross-platform Makefile to build the code and *run* the tests on the host.
- C The test_dpp sub-directory contains integration-test code for the application, such as `DPP` in this case. The objective is to test the initialization and interactions *among* components. Here, you can find the main.c `main()` function as well as the test_dpp.c *test fixture*. This directory also contains make_* *makefiles* to build and run the code on the **embedded targets**.
- D The target_efm32 sub-directory contains the Code needed to build and run the test code on the **embedded target**, like EFM32 in this case.
@section exa_qutest-test Building and Running the Tests
As usual in Test-Driven Development (TDD), the provided Makefiles both *build* the code and *run* the tests.
@subsection exa_qutest_host Host Computers
Typically, you start testing on your host computer. Before building/running the code, you need to open a terminal window and launch the [QSPY host application](https://www.state-machine.com/qtools/qspy.html) with the `-t` [command-line option](https://www.state-machine.com/qtools/qspy.html#qspy_command).
Next, you open another terminal window, change directory to the test_... folder of interest, and type `make`. This will build the application and run the tests (Python), as shown in the screen shot below:
To use the Tcl scripts, you invoke the `make` with the `SCRIPT=tcl` symbol:
@subsection exa_qutest_target Embedded Targets
The QUTest testing system allows you also to easily test the code directly on the embedded target board. The dpp/test_dpp/ directory illustrates this option by providing the `makefiles` for embedded boards, such as the TM4C123 (Tiva LaunchPad) make_tm4c123.
To test the code on an embedded board, you need to connect the board to the host computer and launch the and launch the [QSPY host application](https://www.state-machine.com/qtools/qspy.html) with the `-c COM` [command-line option](https://www.state-machine.com/qtools/qspy.html#qspy_command), where `` is the specific COM port number on your host that the board is using.
Next, you open another terminal window, change directory to the test_... folder of interest, and type `make -f make_tm4c123`. This will build the application and run the tests (Python), as shown in the screen shot below:
To use the Tcl scripts, you invoke the `make -f make_tm4c123` with the `SCRIPT=tcl` symbol:
@next{exa_os}
*/