CocoQML Setup

About CocoQML

QML is a user interface markup language that is used in the Qt Framework. Coco has an add-on that supports code coverage for QML.

The add-on is delivered as a separate package. It consists of two parts, a program to instrument the QML code and a QML plugin that is needed at runtime.

The instrumentation program is called cocoqmlscanner and it inserts code into the QML sources of a program. The plugin implements a QML object that at runtime collects the coverage data and writes them to a file. The plugin is delivered in source form and must be compiled by the customer.

Setup

The CocoQML package is a ZIP archive. When unpacked, it generates a directory with two subdirectories:

• bin: The directory with the cocoqmlscanner executable and some libraries that are needed by it.
• trackerplugin: The source code of the tracker plugin.

Both directories are independent of each other and it is possible to copy them to different places in a test installation.

Compilation of the plugin

The plugin is a qmake project. It must be compiled for the same Qt version as the application for which the coverage should be measured. We recommend that you make it part of your project and include it in the repository, so that it is automatically compiled correctly.

Under UNIX^®, the compilation looks like this:

$ /Qt/5.11.3/gcc_64/bin/qmake ../trackerplugin
Info: creating stash file /home/user/trackerplugin-build/.qmake.stash
$ make
g++ -c -pipe -O2 -std=gnu++11 -D_REENTRANT -Wall -W -fPIC -DQT_NO_DEBUG -DQT_PLUGIN -DQT_GUI_LIB -DQT_QML_LIB -DQT_NETWORK_LIB -DQT_CORE_LIB -I../trackerplugin -I. -I/Qt/5.11.3/gcc_64/include -I/Qt/5.11.3/gcc_64/include/QtGui -I/Qt/5.11.3/gcc_64/include/QtQml -I/Qt/5.11.3/gcc_64/include/QtNetwork -I/Qt/5.11.3/gcc_64/include/QtCore -I. -isystem /usr/include/libdrm -I/Qt/5.11.3/gcc_64/mkspecs/linux-g++ -o csexeapi.o ../trackerplugin/csexeapi.cpp
[...]
mv -f libcocoqmltracker.so QmlJsCoverage/libcocoqmltracker.so
cp -f /home/user/trackerplugin/qmldir QmlJsCoverage

When compiled this way, the build directory contains a subdirectory QmlJsCoverage which contains the plugin:

$ ls QmlJsCoverage/
libcocoqmltracker.so  qmldir

The Microsoft^® Windows build is similar. The plugin directory then contains a DLL file instead of a .so file.

Use of CocoQML

Instrumentation

To measure QML coverage in a software project, its QML files must be instrumented. This is done by the cocoqmlscanner command, in the form

$ cocoqmlscanner <project directory>

All QML files in subdirectories of <project directory> are then (reversibly) instrumented and a program database (or .csmes file) is written. By default, the program database file is cocoqmlscanner_result.csmes.

After the QML files are instrumented, it is recommended to recompile the project. This is especially important in two cases:

• The QML files are resources of the program (i.e. specified in a .qrc file).
• The QML compiler is used. (This is the default for release builds that are compiled with Qt Creator).

In both cases, the compilation makes the instrumented files part of the executable.

Measuring the coverage

After instrumentation, an application needs the tracker plugin to run. To find the plugin, it uses the environment variable QML2_IMPORT_PATH for Qt 5 or QML_IMPORT_PATH for Qt 6. The corresponding variable must be set and its value must contain the parent directory of QmlJsCoverage/. (This means that the string QmlJsCoverage does not occur at the end of the path in QML_IMPORT_PATH.)

If this variable is set correctly, the instrumented AUT can run.

Debugging

If something goes wrong, it is useful to set the variable COCOQML_VERBOSE to 1 which allows the plugin to log its activity.