[http://www.systest.ch/testing/qtrunner/qttestrunner_sample.png]

== 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 (should be the same for Qt 4.x). 

 *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. 

'''Note about Qt 4.x:'''
  
 *Trolltech intends to release its internally used test framework QtTest to the public in one of its next Qt 4.x releases, thereby QtTestRunner could get obsolete (?). 

== QtTestRunner for Microsoft Windows ==

This section describes how to create and test 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 run-time 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. 

 *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 they always link 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 Qt framework is installed, if not yet, then get it from [http://www.trolltech.com/download]. 

 *An environment variable named '''QTDIR''' must point to the top directory of the Qt installation. 

 *An environment variable named '''CPPUNIT''' must point to the top directory of the CppUnit installation. 

 *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 [http://www.systest.ch/testing/qtrunner/qttestrunner.zip 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 [http://www.systest.ch/testing/qtrunner/qttestrunner.zip 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 [http://www.systest.ch/testing/qtrunner/qttestrunner.zip 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 successfull 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 [http://www.trolltech.com/products/qt/qmake.html 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. [http://www.systest.ch/testing/qtrunner/qttestrunnerlib.pro qttestrunnerlib.pro] is a slightly improved qmake project file compared to qttestrunner.pro as provided with the CppUnit distribution. Download [http://www.systest.ch/testing/qtrunner/qttestrunnerlib.pro qttestrunnerlib.pro] and save it in ''CPPUNIT\src\qttestrunner'' or download [http://www.systest.ch/testing/qtrunner/qttestrunner.zip 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. Enter[[BR]]
 ''qmake qttestrunnerlib.pro''[[BR]][[BR]]
 to create the file ''makefile'' in the current directory. To run qmake like this ''QTDIR\bin'' must be in the ''PATH'' environment variable.

 1. Enter[[BR]]
 ''nmake''[[BR]][[BR]]
 which uses ''makefile'' to build the QtTestRunner library. By default the library is built as static in debug mode. See the comments in [http://www.systest.ch/testing/qtrunner/qttestrunnerlib.pro qttestrunnerlib.pro] for how to build it in another fashion. After successfull 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''. 

== Verifying the QtTestRunner Library ==

A sample application helps in verifying that the QtTestRunner library works as expected. 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. Get an overview by reading the [http://www.systest.ch/testing/qtrunner/sample/doc/index.html Sample Testing Application] online documentation.

 1. Download the packed archive file [http://www.systest.ch/testing/qtrunner/sample/SampleTestApp.zip SampleTestApp.zip]. This file contains the source codes of the sample application and sample unit tests, the doxygen configuration file for creating its online documentation and the solution files ''SampleTestApp.sln'' and ''SampleTestApp_with_DLL.sln'' respectively.

  * '''SampleTestApp.sln''' includes the ''SampleApp.vcproj'' project file for building the sample application and the '' SampleUnitTest.vcproj'' project file for building the sample unit test program with the CppUnit and QtTestRunner static libraries linked in.

  * '''SampleTestApp_with_DLL.sln''' includes the same ''SampleApp.vcproj'' project file for building the sample application but differs in that it includes the ''SampleUnitTest_with_DLL.vcproj'' project file which is configured for building the sample unit test program and linking it with the CppUnit and QtTestRunner dynamic libraries. 

 1. Unpack [http://www.systest.ch/testing/qtrunner/sample/SampleTestApp.zip SampleTestApp.zip] into a location of your choice.

 1. To test the static QtTestRunner library open ''SampleTestApp.sln'' with the IDE which will show the two projects ''SampleApp'' and ''SampleUnitTest'' in the solution explorer.

 1. To successfully build the unit test program the Qt library name must be adjusted in the linker's additional dependencies settings of the SampleUnitTest project to correspond with your Qt version.

 1. Choose the configurations of interest in the IDE and let the build process start for both projects. After successfull completion there will be a ''SampleApp.exe'' representing the sample application program and a ''SampleUnitTest.exe'' representing the unit test main program. These executables now can be run independently. 

 1. To test the QtTestRunner DLL open ''SampleTestApp_with_DLL.sln'' with the IDE which will show the two projects ''SampleApp'' and ''SampleUnitTest_with_DLL'' in the solution explorer. 

 1. Here too, adjust the Qt library name in the linker's additional dependencies settings&nbsp; to correspond with your Qt version. Do it for the ''SampleUnitTest_with_DLL'' project.

 1. Again choose the configurations of interest in the IDE and let the build process start for both projects. After successfull completion there will be a ''SampleApp.exe'' representing the sample application program and a ''SampleUnitTest.exe'' representing the unit test main program. These executables now can be run independently. 

 1. ''CPPUNIT\lib'' must be in the ''PATH'' environment variable to successfully run the unit test program ''SampleUnitTest.exe'' so it can load the DLL's at run-time. 

== 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:

[http://www.systest.ch/testing/qtrunner/qttestrunner_orig.png]

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

[http://www.systest.ch/testing/qtrunner/qttestrunner.png]

The failure reports are displayed in QListViewItems 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 gets set by adding the statement shown in the class constructor:

{{{
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 and best of all, by downloading [http://www.systest.ch/testing/qtrunner/qttestrunner.zip qttestrunner.zip] you get the corrected source files in an instant.

== QtTestRunner for Linux/Unix == 

Coming soon.
