
== Verifying the QtTestRunner Library ==

 *The sample application helps in verifying that the QtTestRunner library works as expected.

 *Get an overview by reading the [http://www.systest.ch/testing/qtrunner/sample/doc/index.html Sample Testing Application] online documentation.

=== Prerequisites ===

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

 *The CppUnit and QtTestRunner libraries reside in the {{{lib}}} subfolder of where the {{{CPPUNIT}}} environment variable points to.

=== Verification on Microsoft Windows ===

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

  * '''Sample``Test``App.sln''' includes the '''Sample``App.vcproj''' project file for building the sample application and the '''Sample``Unit``Test.vcproj''' project file for building the sample unit test program with the CppUnit and QtTestRunner static libraries linked in.

  * '''Sample``Test``App_with_DLL.sln''' includes the same  '''Sample``App.vcproj''' project file for building the sample application but differs in that it includes the '''Sample``Unit``Test_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] to 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.

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

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

  a. Here too, adjust the Qt library name in the linker's additional dependencies settings to correspond with your Qt version. Do it for the {{{SampleUnitTest_with_DLL}}} project.

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

  a. Make sure that {{{CPPUNIT\lib}}} is in the {{{PATH}}} environment variable so that the unit test program {{{SampleUnitTest.exe}}} can load the DLL's at run-time. 

=== Verification on Linux/Unix ===

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

 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 qmake configuration files {{{SampleTestApp.pro}}},  {{{SampleApp.pro}}} in the {{{SampleApp}}} subdirectory and {{{SampleUnitTest.pro}}} in the {{{SampleUnitTest}}} subdirectory.

  *'''Sample``Test``App.pro''' includes the '''Sample``App.pro''' project file for generating the Makefile for the sample application and the '''Sample``Unit``Test.pro''' project file for generating the Makefile for the sample unit test program.

  *By default the unit test program gets linked with the Qt``Test``Runner static library and the static or dynamic CppUnit library depending on which type is found on your system. Adjust the {{{CONFIG}}} system variable in {{{SampleUnitTest.pro}}} to link with other types of the Qt``Test``Runner library. See the comments in this .pro file.

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

 1. Open an XTERM or similar console window and set the working directory to where the .zip file was unpacked.

 1. Enter[[BR]] {{{qmake SampleTestApp.pro}}}[[BR]] to create a {{{Makefile}}} in the current directory. To run qmake like this {{{QTDIR/bin}}} must be in the {{{PATH}}} environment variable.

 1. Enter[[BR]] {{{make}}}[[BR]] which uses {{{Makefile}}} for building the Makefiles and then 'making' the targets in the subdirectories.

 1. After successfull completion there will be a {{{SampleApp}}} executable representing the sample application program and a {{{SampleUnitTest}}} executable representing the unit test main program. These executables now can be run independently.

  a. Make sure that {{{CPPUNIT/lib}}} is in the {{{LD_LIBRARY_PATH}}} environment variable so that the unit test program {{{SampleUnitTest}}} can load the shared images at run-time in case of being linked with them.

 *The {{{SampleApp}}} and {{{SampleUnitTest}}} executables can be built separately. Just use qmake with their .pro files for generating Makefiles and then 'make' them.

== 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 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 gets 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 [http://www.systest.ch/testing/qtrunner/qttestrunner.zip qttestrunner.zip] you get the already corrected source files.
