qpc/examples/qutest/unity_mock

About This Example
==================
This example is loosely based on Matt Chernosky's blog "Test-Driving
with Mocks Instead of Hardware", which you can find at:

- https://www.electronvector.com/blog/test-driving-with-mocks-instead-of-hardware
- https://vimeo.com/256590562

The purpose of this example is to compare the traditional approach based on the
Unity unit testing framework and extensive "mocking". The alternative approach
is based on the QUTest unit testing harness and Python:

- https://www.state-machine.com/qtools/qutest.html
- https://github.com/QuantumLeaps/qtools/tree/main/qutest


*** NOTE ***
The provided Makefiles for building and running the tests are cross-platform
and will work on Windows as well as POSIX workstations (Linux/macOS). Also,
it is assumed that you have installed the QTools collection on your computer
and that you have added the QTools/bin directory to your PATH, see:

- https://www.state-machine.com/qtools


Directories and Files
---------------------

<qpc>/examples/qutest/unity_mock/ - this example
|
+-src/         - code under test (CUT)
| +-Led.h
| +-LedBar.h
| +-LedBar.c
|
+-test_unity/  - traditional testing with Unity
| +-cmock/           - CMock source code needed in this example
| | +-cmock.h
| | +-cmock.c
| | +-cmock_internals.h
| |
| +-Makefile         - makefile for building and running the tests
| +-MockLed.h        - interface of the LED-Mock (generated by CMock)
| +-MockLed.c        - implementation of the LED-Mock (generated by CMock)
| +-TestLedBar.c     - test fixture for the LedBar CUT
| +-TestLedBar_Runner.c - test runner for the LedBar (generated by CMock)
|
+-test/        - testing with QUTest
| +-conftest.py      - configuration file for Python
| +-Makefile         - makefile for building and running the tests (host)
| +-Makefile         - makefile for building and running the tests
| +-spy_Led.c        - QUTest "spy" test double for LED (replaces the mock)
| +-test_LedBar.c    - QUTest test fixture for LedBar
| +-test_LedBar.py   - QUTest test script in Python


Building the Code and Testing with Unity
----------------------------------------
Open a terminal/command-prompt. Change directory to test_unity
(qpc/examples/qutest/unity_mock/test_unity).

Type "make". The provided Makefile will build the code and run
the tests using the Unity framework.

*** NOTE ***
For Windows, the make utility, the C compiler (MinGW) are included
in the QTools collection. For all platforms, you will also need
the Unity source code, which is also included in the QTools collection
and the provided Makefile takes it from there.

*** NOTE ***
Some of the Unity tests fail, which is intentional to demonstrate
various failure modes.


Building the Code and Testing with QUTest
-----------------------------------------
Open terminal / command-prompt and launch the QSPY host utility
by typing:

qspy

Open *another* terminal / command-prompt and change directory to
test (qpc/examples/qutest/unity_mock/test).
Type:

make

to build the code with the provided Makefile and run the tests
using the Python test script (test_LedBar.py)

*** NOTE ***
For Windows, the Python interpreter (Python 3.7 or higher) is provided
in the QTools collection. On Linux/macOS, Python is typically already
available, or can be easily installed.

*** NOTE ***
Some of the QUTest tests fail, which is intentional to demonstrate
various failure modes, exactly as it is in the case of Unity tests.


Contact Information
-------------------
https://www.state-machine.com
mailto:info@state-machine.com