1. Summary
  2. Files
  3. Support
  4. Report Spam
  5. Create account
  6. Log in

QtTestRunner

From cppunit

Jump to: navigation, search

Image:qttestrunner_exa.png

Contents

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 as currently shipped with CppUnit 1.10.2 is based on Qt version 2.x, this page describes how to build QtTestRunner with Qt 3.x . IMPORTANT: it does not work with Qt4, as it is not backwards compatible with Qt3.
  • The QtTestRunner GUI as provided has the disadvantage of clenching test failure reports consisting of several lines into a single line in its failure list, which makes them rather unreadable. This document describes how to solve this drawback easily with little changes in QtTestRunner source code.
  • 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 Qt``Assistant.
  • 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 [1].
  • 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.
  • qmake 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 either be downloaded with the links provided in this page or from the CppUnit patch section. Packed archive files are available in .zip (for Windows) and .tar.gz (for Linux/Unix) format.

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. Since there is no solution file included in the CppUnit distribution, you should download the packed archive file qttestrunner.zip. This file 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. 
1. Either
 *unpack the qttestrunner.zip file into a temporary location and then copy QtTestRunner.sln, qttestrunner.vcproj and  qttestrunner_dll.vcproj to CPPUNIT\src\qttestrunner or
 *delete the contents of CPPUNIT\src\qttestrunner and then unpack the qttestrunner.zip file into this directory, i.e. replace all the QtTestRunner files with the unpacked ones. 
1. Open QtTestRunner.sln with the IDE which will show the two projects qttestrunner and qttestrunner_dll in the solution explorer.
1. 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. 
1. 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. qttestrunnerlib.pro is a slightly improved qmake project file compared to qttestrunner.pro as provided with the CppUnit distribution. Download qttestrunnerlib.pro and save it in CPPUNIT\src\qttestrunner or download qttestrunner.zip and extract qttestrunnerlib.pro from it into CPPUNIT\src\qttestrunner.
1. Open a command window and set the working directory to CPPUNIT\src\qttestrunner.
1. EnterBR qmake qttestrunnerlib.proBR to create the file Makefile in the current directory. To run qmake like this QTDIR\bin must be in the PATH environment variable.
1. EnterBR nmakeBR 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.
  • In qttestrunner.zip 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:

Image:qtr_preprocessor_defs.png

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

Image:qtr_runtime_lib.png

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

Image:qtr_linker_input.png

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. qttestrunnerlib.pro is a slightly improved qmake project file compared to qttestrunner.pro as provided with the CppUnit distribution. Download qttestrunnerlib.pro and save it in CPPUNIT/src/qttestrunner or download qttestrunner.tar.gz and extract qttestrunnerlib.pro from it into CPPUNIT/src/qttestrunner.
1. Open an XTERM or similar console window and set the working directory to CPPUNIT/src/qttestrunner.
1. EnterBR qmake qttestrunnerlib.proBR to create the file Makefile in the current directory. To run qmake like this QTDIR/bin must be in the PATH environment variable.
1. EnterBR makeBR 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.
  • In qttestrunner.tar.gz 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.
  • For your convenience there is also a sample application with simple logic and a related unit test program to demonstrate the use of unit test cases in more detail. This sample application is described in the QtTestRunnerSampleApp page.

Requirements

  • The prerequisites and requirements described above for building the QtTestRunner library are also valid for building the example program.
  • The step-by-step instructions below demand you to replace the example program files provided with the CppUnit distribution with new ones contained in downloadable archive files. One reason to do so is the renaming of the files ExampleTestCase.cpp and ExampleTestCase.h of the CppUnit distribution to ExampleTestCases.cpp and ExampleTestCases.h. The new names better reflect what their contents is. See the CppUnit cookbook about testing terminology.

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. Since there is no solution file included in the CppUnit distribution, you should download the packed archive file qt_example.zip. This file contains all the example program source files as well as the solution file qt_example.sln and the project files qt_example.vcproj and qt_example_dll.vcproj suitable for the IDE. 
1. Delete the contents of CPPUNIT\examples\qt and then unpack the qt_example.zip file into this directory, i.e. replace all the example program files with the unpacked ones.
1. Open qt_example.sln 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.
1. 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.
1. 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. Download the packed archive file qt_example.zip. This file contains all the example program source files as well as qt_example.pro which is a slightly improved qmake project file compared to example.pro as provided with the CppUnit distribution.
1. Delete the contents of CPPUNIT\examples\qt and then unpack the qt_example.zip file into this directory, i.e. replace all the example program files with the unpacked ones.
1. Open a command window and set the working directory to CPPUNIT\examples\qt.
1. EnterBR qmake qt_example.proBR to create the file Makefile in the current directory. To run qmake like this QTDIR\bin must be in the PATH environment variable.
1. EnterBR nmakeBR 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. 
1. 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.
1. 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. 
  • In qt_example.zip the script make_example.bat is included, 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. Download the packed archive file qt_example.tar.gz. This file contains all the example program source files as well as qt_example.pro which is a slightly improved qmake project file compared to example.pro as provided with the CppUnit distribution.
1. Delete the contents of CPPUNIT/examples/qt and then unpack the qt_example.tar.gz file into this directory, i.e. replace all the example program files with the unpacked ones.
1. Open an XTERM or similar console window and set the working directory to CPPUNIT/examples/qt.
1. EnterBR qmake qt_example.proBR to create the file Makefile in the current directory. To run qmake like this QTDIR/bin must be in the PATH environment variable.
1. EnterBR makeBR 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. 
1. After successful completion there will be the executable qt_example in the current working directory.
1. 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. 
  • In qt_example.tar.gz the tcsh shell script make_example is included, which successively runs qmake and make as described above.

Multi Line Failure Reports

What's left is the little code correction before building the library to improve the readability of multi line failure reports in the GUI. What is meant here can best be explained with pictures.

This is how it looks with the QtTestRunner included in the CppUnit distribution:

Image:qttestrunner_orig.png

And this is how you probably prefer to have it displayed:

Image:qttestrunner.png

The failure reports are displayed in Q``List``View``Items which can be set to be "multi line". By default this property is disabled. Therefore two source files of QtTestRunner, found in CPPUNIT\src\qttestrunner need to be changed in order to have this property used right.

In file TestFailureListViewItem.cpp the property is set by adding the setMultiLinesEnabled (true) statement in the class constructor as shown below:

TestFailureListViewItem::TestFailureListViewItem(

                          TestFailureInfo *failure,
                          QListView *parent ) : 
   QListViewItem( parent ),
   _failure( failure )

{ setMultiLinesEnabled (true); }

In file TestRunnerDlgImpl.cpp unnecessary white space needs to be stripped away in method TestRunnerDlg::reportFailure( TestFailureInfo *failure ) by replacing the statement

item->setText( indexMessage, thrownException->what() ); with item->setText( indexMessage, QString(thrownException->what()).stripWhiteSpace() );

That's all there is to do. By downloading qttestrunner.zip or qttestrunner.tar.gz you get the already corrected source files.

Personal tools