QTools 6.9.3
QUTest™ Script Reference

A QUTest test script contains a group of related tests (a test group). The basic job of these tests is to send commands to the test fixture running in the Target and to compare the QSPY textual output produced by the Target with the expectations of the tests.

The QUTest test scripts are executed in the host by the "QUTest front-end" that communicates with the QSPY host application via the UDP interface. The "QUTest front-end" is itself implemented in Python (Python 3.3+).

Running the Test Scripts

To run any test script(s), you first need to make sure that the QSPY console application (version 6.x or higher) is running. Once QSPY is running, you can "attach" to the UDP socket and start communicating with the QSPY back-end or to the Target (through QSPY).

The Python test scripts are executed by the Python module qtools/qspy/py/qutest.py, with the following usage:

python3 <qutest-dir>qutest.py [-x] [test-scripts] [host_exe] [qspy_host[:udp_port]] [qspy_tcp_port]

<qutest-dir> is the directory with the qutest.py script

[test_scripts]optional specification of the Python test scripts to run. If not specified, qutest will try to run all *.py files in the current directory as test scripts
[host_exe]optional specification of the host executable to launch for testing embedded code on the host computer. If host_exe is not specified, or is specified as a placeholder "", an embedded target is assumed. The special value DEBUG means that qutest.py will start in the debug mode, in which it will NOT launch the host executables and it will wait for the Target reset and other responses from the Target.
[qspy_host[:udp_port]]optional host-name/IP-address:port for the host running the QSpy utility. If not specified, the default is localhost:7701.
[tcp_port]optional the QSpy TCP port number for connecting host executables.

Usage examples (for Windows):

python3 %QTOOLS%\qspy\py\qutest.py
python3 %QTOOLS%\qspy\py\qutest.py *.py
python3 %QTOOLS%\qspy\py\qutest.py *.py build\dpp.exe
python3 %QTOOLS%\qspy\py\qutest.py *.py build\dpp.exe
python3 %QTOOLS%\qspy\py\qutest.py *.py "" localhost:7701 6605
python3 %QTOOLS%\qspy\py\qutest.py *.py DEBUG
python3 %QTOOLS%\qspy\py\qutest.py *.py DEBUG localhost:7701 6605

Usage examples (for Linux/MacOS):

python3 $(QTOOLS)/qspy/py/qutest.py
python3 $(QTOOLS)/qspy/py/qutest.py *.py
python3 $(QTOOLS)/qspy/py/qutest.py *.py build/dpp
python3 $(QTOOLS)/qspy/py/qutest.py *.py build/dpp
python3 $(QTOOLS)/qspy/py/qutest.py *.py "" localhost:7701 6605
python3 $(QTOOLS)/qspy/py/qutest.py *.py DEBUG
python3 $(QTOOLS)/qspy/py/qutest.py *.py DEBUG localhost:7701 6605

QUTestâ„¢ Testing DSL

The Python module qtools/qspy/py/qutest.py defines a small Domain Specific Language (DSL) for writing test scripts in Python. The structure of this DSL is very simple. Each test script consists of two sections:


The "preamble" section of a test script file specifies include scripts and defines callback functions common to all tests in this file. It can contain the following functions:

The on_...() callback functions can call any of the test commands.


The "tests" section of a test script file contains the actual tests. Each test starts with the test() command and can contain any number of the test commands. The test continues until another test() command, or the skip() command.


The commands that you can place in the tests (as well as inside the callback functions) are:

Categories of QSPY Output

To write effective test scripts you need to understand the main categories of QSPY output, which are illustrated in the picture below:

Information output generated internally by QSPY. This output is not sent to test scripts.
Dictionary trace records generated by the Target. This output is not forwarded to test scripts.
Acknowledgement trace records generated by the Target. This output is forwarded to test scripts, but is checked automatically and implicitly by the test commands.
Trace records generated by the Target. This output is forwarded to test scripts and must be checked explicitly by test expectations.

Next: QView™ Visualization & Monitoring