/*! @page exa_qutest Examples for QUTest Unit Testing Harness
@tableofcontents
<p>The examples in the <span class="img folder">qpc/examples/qutest</span> directory demonstrate how to test embedded code with the [<b>QUTest</b>](https://www.state-machine.com/qtools/qutest.html) unit testing harness. Currently, the following examples are provided:
The projects within the <span class="img folder">examples/qutest</span> directory have the customary structure used for testing. The production code to be tested is located in the <span class="img folder">src</span> sub-directory. The testing code is located in the <span class="img folder">test_...</span> sub-folder(s). The following directory tree illustrates the structure for the `dpp` example:
<ul class="tag">
<li><span class="img folder">examples/</span>
</li>
<ul class="tag">
<li><span class="img folder">qutest/</span> — Examples for QUTest unit testing harness
</li>
<ul class="tag">
<li><span class="img folder">dpp/</span> — The simple Blinky example
</li>
<ul class="tag">
<li><span class="img folder">src/</span> — source code under test <span class="tag">A</span>
<li><span class="img file_qm">dpp.qm</span> — DPP model
</li>
<li><span class="img file_c">philo.c</span> — `Philo` active object
</li>
<li><span class="img file_c">table.c</span> — `Table` active object
</li>
</ul>
</ul>
<ul class="tag">
<li><span class="img folder">test_philo/</span> — code for unit testing of `Philo` AO <span class="tag">B</span>
<li><span class="img folder">test_table/</span> — code for unit testing of `Table` AO <span class="tag">B</span>
<li><span class="img folder">test_dpp/</span> — code for unit testing of DPP application <span class="tag">C</span>
<li><span class="img folder">.../</span> — Other QUTest examples...
</li>
<li><span class="img folder">target_efm32/</span> — Code for the **embedded target** (EFM32) <span class="tag">D</span>
</li>
<li><span class="img folder">target_tm4c123/</span> — Code for the **embedded target** (TM4C123) <span class="tag">D</span>
</li>
</ul>
</ul>
</ul>
<ul class="tag">
<li><span class="tag">A</span> The <span class="img folder">src</span> sub-directory contains the production code to be tested. This directory contains the <span class="img file_qm">.qm</span> model file as well as the generated code from the model.
<li><span class="tag">B</span> The <span class="img folder">test_philo</span> sub-directory contains the unit test code for a component, such as `Philo` in this case. Here, you can find the <span class="img file_c">test_*.c</span> **test fixture**, the test scripts <span class="img file_py">test_*.py</span> (Python) and <span class="img file_tcl">test_*.tcl</span> (Tcl) as well as the cross-platform <span class="img file_mak">Makefile</span> to build the code and *run* the tests on the host.
<li><span class="tag">C</span> The <span class="img folder">test_dpp</span> 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 <span class="img file_c">main.c</span> `main()` function as well as the <span class="img file_c">test_dpp.c</span> *test fixture*. This directory also contains <span class="img file_mak">make_*</span> *makefiles* to build and run the code on the **embedded targets**.
</li>
<li><span class="tag">D</span> The <span class="img folder">target_efm32</span> 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 <span class="img file_mak">Makefiles</span> both *build* the code and *run* the tests.
<div class="separate"></div>
@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 <span class="img folder">test_...</span> folder of interest, and type `make`. This will build the application and run the tests (Python), as shown in the screen shot below:
The QUTest testing system allows you also to easily test the code directly on the embedded target board. The <span class="img folder">dpp/test_dpp/</span> directory illustrates this option by providing the `makefiles` for embedded boards, such as the TM4C123 (Tiva LaunchPad) <span class="img file_mak">make_tm4c123</span>.
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<n>` [command-line option](https://www.state-machine.com/qtools/qspy.html#qspy_command), where `<n>` is the specific COM port number on your host that the board is using.
Next, you open another terminal window, change directory to the <span class="img folder">test_...</span> 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:
