QTools  6.3.7
QUTest™ Fixture Reference

A QUTest test fixture is a regular C or C++ program that contains the main() function as well as a few QS callback functions (to implement test commands as well as test startup and teardown). The main job of a test fixture is to exercise the CUT (Code Under Test).

The CUT called from a test fixture can be any code you wish to unit-test and does not need to be based on the QP framework. That way of applying QUTest is illustrated in the first lessons of the QUTest Tutorial.

However, QUTest is particularly useful for testing QP applications, which is illustrated in the later lessons of the QUTest Tutorial. In this case, the test fixture needs to initialize all used QP services, such as event pools to dispatch/post events to your state machines and active objects.

QUTestâ„¢ QP Stub

The QP API implementation linked with the test fixture is not the actual QP framework, but instead just a QUTest QP Stub, which differs from the real QP implementation in the following aspects:

  • the QActive_start() implementation initializes the event queue for the AO and registers it with the QP framework, but it does not start a new thread for the AO.
  • the QF_run() implementation calls the QS_onTestLoop() to wait for the commands from the "test script"
  • the stub provides QActiveDummy class for instantiating "dummy" active objects for testing
The QUTest QP Stub is implemented in the file qutest.c as well as Target-specific QUTest port qutest_port.c.

QUTestâ„¢ Fixture Callbacks

Pausing Test Fixtures

Test Probes

QUTest "Test Probes" are a very flexible mechanism to alter the behavior of code from the test scripts. This alteration of behavior can be used for a variety of reasons:

  • to alter the flow of control to execute paths through the code otherwise hard to reach (to improve the test coverage of the code)
  • to cause various error conditions
  • to alter return values from functions
  • many others

The "Test Probes" are just 32-bit values (uint32_t) sent from the test script to the Target (see the probe() command), where they are stored in the FIFO (First-In-First-Out) data structure. The "Test Probes" can be then retrieved from C or C++ code on the Target, by means of the following macros:

The QUTest Test Probes macros can be used both in production code and in test code (intended for testing only). These macros are active only when Q_UTEST is defined, and otherwise resolve to nothing, which means that you can leave the Test Probe macros in your production code.

The typical use of the "Test Probe" macros is as follows:

A C or C++ function calls the macro QS_TEST_PROBE_DEF(), which defines the test-probe variable qs_tp_ of type uint32_t. If any test probes for this function have been sent from the test script, the test-probe is retrieved and assigned to the test-probe variable. Otherwise the test-probe variable is initialized to zero.

Once the the test-probe variable is defined and initialized, it can be tested with the QS_TEST_PROBE() and QS_TEST_PROBE_ID() macros. The QS_TEST_PROBE() macro executes the code snippet specified as the parameter to the macro when the test probe is not zero. The QS_TEST_PROBE_ID() executes the specified code snippet only when the test-probe has a given ID value.

Next: QUTest™ Script Reference