qpc-rtthread/doxygen/exa_qutest.dox

/*! @page exa_qutest Examples for QUTest Unit Testing Harness

<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:
</p>

- <span class="img folder">blinky</span> &mdash; Simple "Blinky" single-active-object application
- <span class="img folder">dpp</span> &mdash; DPP application from Chapter 9 of PSiCC2
- <span class="img folder">evt-par</span> &mdash; testing events with parameters
- <span class="img folder">qhsmtst</span> &mdash; Test State Machine based on ::QHsm with QM model
- <span class="img folder">qmsmtst</span> &mdash; Test State Machine based on ::QMsm with QM model
- <span class="img folder">unity_basic</span> &mdash; Comparison of a basic testing with Unity and QUTest
- <span class="img folder">unity_mock</span> &mdash; Comparison of a advanced testing (mocking) with Unity and QUTest


@section exa_qutest-dir General Code Organization
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> &mdash; Examples for QUTest unit testing harness
    </li>
    <ul class="tag">
      <li><span class="img folder">dpp/</span> &mdash; The simple Blinky example
      </li>
      <ul class="tag">
        <li><span class="img folder">src/</span> &mdash; source code under test &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">A</span>
        </li>
        <ul class="tag">
          <li><span class="img file_h">bsp.h</span> &mdash; BSP header
          </li>
          <li><span class="img file_h">dpp.h</span> &mdash; DPP header
          </li>
          <li><span class="img file_qm">dpp.qm</span> &mdash; DPP model
          </li>
          <li><span class="img file_c">philo.c</span> &mdash; `Philo` active object
          </li>
          <li><span class="img file_c">table.c</span> &mdash; `Table` active object
          </li>
        </ul>
      </ul>
      <ul class="tag">
        <li><span class="img folder">test_philo/</span> &mdash; code for unit testing of `Philo` AO &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">B</span>
        </li>
        <ul class="tag">
          <li><span class="img file_mak">Makefile</span> &mdash; cross-platform makefile (host)
          </li>
          <li><span class="img file_c">test_philo.c</span> &mdash; test fixture for `Philo` AO
          </li>
          <li><span class="img file_py">test_philo.py</span> &mdash; test script for `Philo` (Python)
          </li>
        </ul>
      </ul>
      <ul class="tag">
        <li><span class="img folder">test_table/</span> &mdash; code for unit testing of `Table` AO &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">B</span>
        </li>
        <ul class="tag">
          <li><span class="img file_mak">Makefile</span> &mdash; cross-platform makefile (host)
          </li>
          <li><span class="img file_c">test_philo.c</span> &mdash; test fixture for `Table` AO
          </li>
          <li><span class="img file_py">test_philo.py</span> &mdash; test script for `Table` (Python)
          </li>
        </ul>
      </ul>
      <ul class="tag">
        <li><span class="img folder">test_dpp/</span> &mdash; code for unit testing of DPP application &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">C</span>
        </li>
        <ul class="tag">
          <li><span class="img file_mak">Makefile</span> &mdash; cross-platform makefile (host)
          </li>
          <li><span class="img file_mak">make_efm32</span> &mdash; makefile for the EFM32 **embedded board**
          </li>
          <li><span class="img file_mak">make_tm4c123</span> &mdash; makefile for the TM4C123 **embedded board**
          </li>
          <li><span class="img file_c">main.c</span> &mdash; `main()` function for DPP application
          </li>
          <li><span class="img file_c">test_dpp.c</span> &mdash; test fixture for DPP application
          </li>
          <li><span class="img file_py">test_init.py</span> &mdash; test script for DPP initialization (Python)
          </li>
          <li><span class="img file_py">test_tick.py</span> &mdash; test script for DPP tick processing (Python)
          </li>
        </ul>
      </ul>
      <li><span class="img folder">~~~/</span> &mdash; Other QUTest examples~~~
      </li>
      <li><span class="img folder">target_efm32/</span> &mdash; Code for the **embedded target** (EFM32) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <span class="tag">D</span>
      </li>
      <li><span class="img folder">target_tm4c123/</span> &mdash; Code for the **embedded target** (TM4C123) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <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>

  <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) 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>

  <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.
  </li>
</ul>


@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.


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

@image html  qutest_py.png
@image latex qutest_py.png width=6.5in
@caption{Testing on the host (Python)}


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

@image html  qutest_tm4c123_py.png
@image latex qutest_tm4c123_py.png width=6.5in
@caption{Testing on the TM4C123 embedded target (Python)}

@ifnot LATEX
@nav_next{exa_os}
@endif
*/