• QtTestRunner

General Remarks

• As with the other GUI test runners for the CppUnit testing framework the QtTestRunner can be used to unit test any kind of C++ software, it's not limited to Qt applications.

• QtTestRunner shipped with CppUnit 1.10.2 is based on Qt version 2.x.

• This page describes how to build QtTestRunner with CppUnit 1.12.0 and Qt 3.x IMPORTANT: it does not work with Qt4, as it is not backwards compatible with Qt3.

• In the remaining documentation the identifier CPPUNIT stands for the top directory of the CppUnit installation and the identifier QTDIR stands for the top directory of the Qt installation.

• At least amongst MS Windows programmers it became common sense to distinguish different library types with an appropriate file name suffix. Libraries in debug mode often have a 'd' and dynamic libraries have a '_dll', which leads to combinations such as 'd_dll', for example cppunitd_dll.dll. This naming convention can be seen as a matter of taste but as learned from experience it's also helpful for Linux/Unix development. A reason for this is the fact that the GNU linker 'ld' by default links with shared images. If there are two library files with the same file name but different file types (.a and .so) in a directory then 'ld' will link with the .so type even when it gets the .a file as an input parameter (this behaviour can be overriden of course, but it's not obvious at first sight how to do that). Therefore the scripts presented here create the different flavors of the QtTestRunner library with different file names which makes the creation and verification process more transparently.

Notes about Qt 4.x:

• In QtTestRunnerWithEclipse you'll find step by step instructions on how to build QtTestRunner with Qt4 under Eclipse. There you'll find a zip file containing QtTestRunner's source code ported to Qt4 that may also be used to build it in other platforms. However the .pro and .ui files haven't been ported, so you will not be able to rely on the Qt specific tools qmake and QtAssistant.

• QxTestRunner is a derivative of QtTestRunner based on the model/view framework of Qt4.

• As part of the Qt4 distribution comes QtTestLib which is a library designed to ease unit testing for Qt based C++ code. It has no GUI for running the tests therefore QtTestRunner's live span will also extend into the Qt4 era.

• Qt/Win free project provides a patch to compile Qt 4 Open Source Edition with Visual Studio and Borland C++.

General Requirements

• The Qt framework is installed, if not yet, then get it from http://www.trolltech.com/products/qt/downloads.

• An environment variable named QTDIR must point to the top directory of the Qt installation on the system where the QtTestRunner library will be created and used.

• http://doc.trolltech.com/latest/qmake-manual.html is Trolltech's tool for generating Makefiles out of Qt project files (.pro). qmake presets its CONFIG variable with the options used to build the Qt libraries. Should any options be missing to build the QtTestRunner library using one of the .pro files presented here than provide them by yourself in accordance with your Qt installation. Such options can be: exceptions rtti stl. How the Qt libraries were originally built is stored in different files, for example in file QTDIR\.qtwinconfig on MS Windows platforms and in QTDIR/.qmake.cache on all platforms. Other files are also involved in the Makefile creation process such as qmake.conf. Please read the qmake documentation for more information.

• The files discussed here should be downloaded from the CppUnit download page.

QtTestRunner for Microsoft Windows

This section describes how to create the QtTestRunner library for Windows (2000, XP) with Microsoft VC++ 7.0 and Qt 3.x. The library can either be built with the Microsoft IDE or from the command line using qmake with Qt project files (.pro). Working with the IDE is the preferred approach because it ensures that all environment settings are correct and one isn't bothered with the proper settings of the PATH, INCLUDE or LIB environment variables.

• It's important that all libraries used in a program use the same runtime library, i.e. if the QtTestRunner library used in a test program was created with the multi-threaded DLL runtime then the CppUnit library must have been built analogous.

• For building the QtTestRunner library as a DLL the QTTESTRUNNER_DLL_BUILD preprocessor definition is required when compiling the QtTestRunner source files.

• Programs using the QtTestRunner DLL must be compiled with the QTTESTRUNNER_DLL preprocessor definition. This isn't required when linking with the static QtTestRunner library.

• When the QtTestRunner library is built as a DLL with the scripts described below it always gets linked with the corresponding CppUnit DLL, but there is nothing against linking it with the static CppUnit library.

Prerequisites

• The CppUnit libraries are in the CPPUNIT\lib directory. Most likely there will be static and dynamic versions of the CppUnit library in debug and release mode namely cppunitd.lib, cppunit.lib, cppunitd_dll.lib, cppunitd_dll.dll, cppunit_dll.lib and cppunit_dll.dll.

• The source code of QtTestRunner is located in CPPUNIT\src\qttestrunner.

Building the QtTestRunner Library with the Microsoft IDE

The solution and project files mentioned in this section were created with the Microsoft Development Environment 2003 for VC++ 7.0 and the .NET framework 1.1.

1. The CppUnit distribution contains all the QtTestRunner source files as well as the solution file QtTestRunner.sln and the project files qttestrunner.vcproj and qttestrunner_dll.vcproj suitable for the IDE.

2. Unpack the CppUnit distribution into a folder of your choice.

3. Open QtTestRunner.sln with the IDE which will show the two projects qttestrunner and qttestrunner_dll in the solution explorer.

4. To successfully build the QtTestRunner library as a DLL the Qt library name must be adjusted in the linker's additional dependencies settings of the qttestrunner_dll project to correspond with your Qt version. For creating a static QtTestRunner library the Qt library isn't needed.

5. Choose the configurations of interest in the IDE and let the build process start. After successful completion there will be, depending on the chosen configurations, static and dynamic versions of the QtTestRunner library in debug and release mode in the CPPUNIT\lib directory, namely qttestrunnerd.lib, qttestrunner.lib, qttestrunnerd_dll.lib, qttestrunnerd_dll.dll, qttestrunner_dll.lib and qttestrunner_dll.dll.

Building the QtTestRunner Library from the Command Line

The qmake and nmake utilities are used when creating the QtTestRunner library from the command line. However, if possible build the library with the IDE, otherwise you could end up spending some time for adjusting environment variables. This is especially true if different VC++ versions are installed on a system.

1. Open a command window and set the working directory to CPPUNIT\src\qttestrunner.

2. Enter
   qmake qttestrunnerlib.pro
   to create the file Makefile in the current directory. To run qmake like this QTDIR\bin must be in the PATH environment variable.

3. Enter
   nmake
   which uses Makefile to build the QtTestRunner library. By default the library is built as static in debug mode. See the comments in qttestrunnerlib.pro for how to build it in another fashion. After successful completion there will be, depending on the chosen configurations, static and dynamic versions of the QtTestRunner library in debug and release mode in the CPPUNIT\lib directory, namely qttestrunnerd.lib, qttestrunner.lib, qttestrunnerd_dll.lib, qttestrunnerd_dll.dll, qttestrunner_dll.lib and qttestrunner_dll.dll.

4. In the CppUnit distribution the script make_lib.bat is included, which does the last two steps at once by successively running qmake and nmake.

Related Pictures

This picture shows where to set preprocessor definitions in the project properties dialog of the Microsoft IDE:

This picture shows where to set the runtime library in the project properties dialog of the Microsoft IDE:

This picture shows where to define additional input files for the linker in the project properties dialog of the Microsoft IDE:

QtTestRunner for Linux/Unix

This section describes how to create the QtTestRunner library for Linux (2.6.5-7.95-smp) with g++ (2.95.3) and Qt 3.x. The library is built from the command line using qmake with Qt project files (.pro). Building the library on other Unix OS should work as well.

• When the QtTestRunner library is built as a shared image (dynamic library) with the scripts described below it always gets linked with the cppunit library. Whether this is the shared or static CppUnit library depends on the CppUnit installation. See the general remarks at the beginning of this page about this issue. For the QtTestRunner library to work it's irrelevant which CppUnit library type it gets linked with.

Prerequisites

• The CppUnit libraries are in the CPPUNIT/lib directory. Most likely there will be static and dynamic versions of the CppUnit library either in debug or release mode, depending on your installation, named libcppunit.a and libcppunit.so as well as a helper file libcppunit.la.

• The source code of QtTestRunner is located in CPPUNIT/src/qttestrunner.

Building the QtTestRunner Library

The qmake and make utilities are used for creating the QtTestRunner library from the command line.

1. Open an XTERM or similar console window and set the working directory to CPPUNIT/src/qttestrunner.

2. Enter
   qmake qttestrunnerlib.pro
   to create the file Makefile in the current directory. To run qmake like this QTDIR/bin must be in the PATH environment variable.

3. Enter
   make
   which uses Makefile to build the QtTestRunner library. By default the library is built as static in debug mode. See the comments in qttestrunnerlib.pro for how to build it in another fashion. After successful completion there will be, depending on the chosen configurations, static and dynamic versions of the QtTestRunner library in debug and release mode in the CPPUNIT/lib directory, namely libqttestrunnerd.a, libqttestrunner.a, libqttestrunnerd_shared.so and libqttestrunner_shared.so.

4. In the CppUnit distribution the tcsh shell script make_lib is included, which does the last two steps at once by successively running qmake and make.

Verifying the QtTestRunner Library

• A small example program is provided with the CppUnit distribution to verify the proper functioning of the QtTestRunner library. It has a number of unit test cases which are designed to produce example errors and failures. This section describes how to build the example program.

Requirements

• The prerequisites and requirements described above for building the QtTestRunner library are also valid for building the example program.

Verification on Microsoft Windows

This section describes how to create the QtTestRunner example program for Windows (2000, XP) with Microsoft VC++ 7.0 and Qt 3.x. The library can either be built with the Microsoft IDE or from the command line using qmake with Qt project files (.pro).

Prerequisites

• The CppUnit and QtTestRunner libraries are in the CPPUNIT\lib directory. Most likely there will be static and dynamic versions of these libraries.

• The source code of the example program is located in CPPUNIT\examples\qt.

Building the QtTestRunner Example with the Microsoft IDE

The solution and project files mentioned in this section were created with the Microsoft Development Environment 2003 for VC++ 7.0 and the .NET framework 1.1.

1. Open qt_example.sln in folder CPPUNIT\examples\qt with the IDE which will show the two projects qt_example and qt_example_dll in the solution explorer. As the names suggest the qt_example project links with the static CppUnit and QtTestRunner libraries while the qt_example_dll project links with the dynamic CppUnit and QtTestRunner libraries.

   • To successfully link the example program the Qt library name must be adjusted in the linker's additional dependencies settings of the projects to correspond with your Qt version.

2. Choose the projects and configurations of interest in the IDE and let the build process start. After successful completion there will be the executable qt_example.exe in the corresponding projects target destination subdirectory which can be Debug, DebugDLL, Release or ReleaseDLL.

3. Run the program!

   • Make sure that CPPUNIT\lib is in the PATH environment variable when running the example program which uses the DLL's so it can load them at run-time.

Building the QtTestRunner Example from the Command Line

The qmake and nmake utilities are used when creating the QtTestRunner example from the command line. However, if possible build the program with the IDE, otherwise again you could end up spending some time for adjusting environment variables.

1. Open a command window and set the working directory to CPPUNIT\examples\qt.

2. Enter
   qmake qt_example.pro
   to create the file Makefile in the current directory. To run qmake like this QTDIR\bin must be in the PATH environment variable.

3. Enter
   nmake
   which uses Makefile to build the QtTestRunner example program. By default the program is built using the static CppUnit and QtTestRunner libraries. See the comments in qt_example.pro for how to build it in another fashion.

4. After successful completion there will be the executable qt_example.exe in the corresponding projects target destination subdirectory which can be Debug, DebugDLL, Release or ReleaseDLL.

5. Run the program!

   • Make sure that CPPUNIT\lib is in the PATH environment variable when running the example program which uses the DLL's so it can load them at run-time.

6. In the example directory there is the script make_example.bat which successively runs qmake and nmake as described above.

Verification on Linux/Unix

The configuration files needed to build the QtTestRunner example program are written for Linux (2.6.5-7.95-smp) with g++ (2.95.3) but should work fine in similar environments.

• When the QtTestRunner example program is built with the scripts described below it always gets linked with the cppunit library. Whether this is the shared or static CppUnit library depends on the CppUnit installation. See the general remarks at the beginning of this page about this issue. For the QtTestRunner example program to work it's irrelevant which CppUnit library type it gets linked with.

Prerequisites

• The CppUnit and QtTestRunner libraries are in the CPPUNIT/lib directory. Most likely there will be static and dynamic versions of these libraries.

• The source code of the example program is located in CPPUNIT/examples/qt.

Building the QtTestRunner Example

The qmake and make utilities are used for creating the QtTestRunner example from the command line.

1. Open an XTERM or similar console window and set the working directory to CPPUNIT/examples/qt.

2. Enter
   qmake qt_example.pro
   to create the file Makefile in the current directory. To run qmake like this QTDIR/bin must be in the PATH environment variable.

3. Enter
   make
   which uses Makefile to build the QtTestRunner example program. By default the program is built using the static QtTestRunner library. See the comments in qt_example.pro for how to build it in another fashion.

4. After successful completion there will be the executable qt_example in the current working directory.

5. Run the program!

   • Make sure that CPPUNIT/lib is in the LD_LIBRARY_PATH environment variable when running the example program which uses the dynamic libraries so it can load them at run-time.

6. In the example directory there is the tcsh shell script make_example which successively runs qmake and make as described above.