<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
<head>
<title>kunittest: KUnitTest - a UnitTest library for KDE (kunittest)</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" comment "ICRAonline DE v2.0" l gen true for "http://www.kde.org" r (nz 1 vz 1 lz 1 oz 1 cb 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://www.kde.org" r (n 0 s 0 v 0 l 0))' />
<meta name="trademark" content="KDE e.V." />
<meta name="description" content="K Desktop Environment Homepage, KDE.org" />
<meta name="MSSmartTagsPreventParsing" content="true" />
<meta name="robots" content="all" />
<link rel="shortcut icon" href="../../favicon.ico" />
<link rel="stylesheet" media="screen" type="text/css" title="APIDOX" href="doxygen.css" />
</head>
<body>
<div id="nav_header_top" align="right">
<a href="#content" class="doNotDisplay" accesskey="2">Skip to main content ::</a>
<a href="../.."><img id="nav_header_logo" alt="Home" align="left" src="../../kde_gear_64.png" border="0" /></a>
<span class="doNotDisplay">::</span>
<div id="nav_header_title" align="left">KDE API Reference</div>
</div>
<div id="nav_header_bottom" align="right">
<span class="doNotDisplay">:: <a href="#navigation" accesskey="5">Skip to Link Menu</a><br/></span>
<div id="nav_header_bottom_right" style="text-align: left;">
/ <a href="../..">API Reference</a>
/ <a href=".">kunittest</a>
</div>
</div>
<table id="main" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" class="menuheader" height="0"></td>
<td id="contentcolumn" valign="top" rowspan="2" >
<div id="content" style="padding-top: 0px;"><div style="width:100%; margin: 0px; padding: 0px;">
<a name="content"></a>
<!-- Generated by Doxygen 1.7.4 -->
</div>
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> - a UnitTest library for KDE </div> </div>
</div>
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="contents"></a>
Contents</h2>
<ul>
<li><a class="el" href="index.html#background">Background</a> </li>
<li><a class="el" href="index.html#usage">Example usage</a> </li>
<li><a class="el" href="index.html#integration">Integration</a> </li>
<li><a class="el" href="index.html#module">Creating test modules</a> </li>
<li><a class="el" href="index.html#advanced">Advanced usage</a> </li>
<li><a class="el" href="index.html#scripts">Scripts</a></li>
</ul>
<h2><a class="anchor" id="background"></a>
Background</h2>
<p><a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> is based on the "in reality no one wants to write tests and if it takes a lot of code no one will. So the less code to write the better" design principle.</p>
<p>Copyright and credits: </p>
<ul>
<li>(C) 2004 Zack Rusin (original author) </li>
<li>Brad Hards (import into CVS) </li>
<li>(C) 2005 Jeroen Wijnhout (GUI, library, module)</li>
</ul>
<p>You are responsible for what you do with it though. It is licensed under a BSD license - read the top of each file.</p>
<p>All the GUI related stuff is in kdesdk/kunittest, the core libraries are in kdelibs/kunittest. A simple example modules is in kdelisbs/kunittest/samplemodule.{h,cpp}, however more examples can be found in kdesdk/kunittest/example.</p>
<p>There are roughly two ways to use the <a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> library. Either you create dynamically loadable modules and use the kunittestmodrunner or kunittestguimodrunner programs to run the tests, or you use the kunittest/kunittestgui library to create your own test runner application.</p>
<p>The main parts of the <a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> library are: </p>
<ul>
<li>runner.{h,cpp} - it is the tester runner, holds all tests and runs them. </li>
<li>runnergui.{h,cpp} - the GUI wrapper around the runner. The GUI neatly organizes the test results. With the kunittest helper script it can even add the debug output to the test results. For this you need to have the kdesdk module installed. </li>
<li><a class="el" href="tester_8h.html">tester.h</a> - which holds the base of a pure test object (Tester). </li>
<li><a class="el" href="module_8h.html">module.h</a> - defines macros to create a dynamically loadable module.</li>
</ul>
<h2><a class="anchor" id="usage"></a>
Example usage</h2>
<p>This section describes how to use the library to create your own tests and runner application.</p>
<p>Now lets see how you would add a new test to <a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a>. You do that by writting a Tester derived class which has an "allTests()" method:</p>
<div class="fragment"><pre class="fragment"> <span class="keyword">class </span>SampleTest : <span class="keyword">public</span> Tester
{
<span class="keyword">public</span>:
SampleTest();
<span class="keywordtype">void</span> allTests();
};
</pre></div><p>Now in the allTests() method we implement our tests, which might look like:</p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">void</span> SampleTest::allTests()
{
<a class="code" href="tester_8h.html#a4fd95491287cc131e6ae4f5dafc26ac1">CHECK</a>( 3+3, 6 );
<a class="code" href="tester_8h.html#a4fd95491287cc131e6ae4f5dafc26ac1">CHECK</a>( <a class="codeRef" href="qstring.html">QString</a>( <span class="stringliteral">"hello%1"</span> ).arg( <span class="stringliteral">" world not"</span> ), <a class="codeRef" href="qstring.html">QString</a>( <span class="stringliteral">"hello world"</span> ) );
}
</pre></div><p><a class="el" href="tester_8h.html#a4fd95491287cc131e6ae4f5dafc26ac1">CHECK()</a> is implemented using a template, so you get type safe comparison. All that is needed is that the argument types have an <code>operator==()</code> defined.</p>
<p>Now that you did that the only other thing to do is to tell the framework to add this test case, by using the <a class="el" href="runner_8h.html#ac1af23b0a525c05b4c17c5f16f7be550" title="Automatic registration of Tester classes.">KUNITTEST_REGISTER_TESTER(x)</a> macro. Just put the following line in the implementation <a href="file:">file:</a></p>
<div class="fragment"><pre class="fragment"> <a class="code" href="runner_8h.html#ac1af23b0a525c05b4c17c5f16f7be550" title="Automatic registration of Tester classes.">KUNITTEST_REGISTER_TESTER</a>( SampleTest );
</pre></div><p>Note the ;, it is necessary.</p>
<p><a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> will do the rest. It will tell you which tests failed, how, what was the expected result, what was the result it got, what was the code that failed and so on. For example for the code above it would output:</p>
<div class="fragment"><pre class="fragment">
SampleTest - 1 test passed, 1 test failed
Unexpected failure:
sampletest.cpp[38]: failed on "QString( "hello%1" ).arg( " world not" )"
result = 'hello world not', expected = 'hello world'
</pre></div><p>If you use the RunnerGUI class then you will be presented with a scrollable list of the test results.</p>
<h2><a class="anchor" id="integration"></a>
Integration</h2>
<p>The <a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> library is easy to use. Let's say that you have the tests written in the sampletest.h and sampletest.cpp files. Then all you need is a main.cpp file and a Makefile.am. You can copy both from the example file provided with the library. A typical main.cpp file looks like this:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <kaboutdata.h></span>
<span class="preprocessor"> #include <kapplication.h></span>
<span class="preprocessor"> #include <kcmdlineargs.h></span>
<span class="preprocessor"> #include <kcmdlineargs.h></span>
<span class="preprocessor"> #include <klocale.h></span>
<span class="preprocessor"> #include <kunittest/runnergui.h></span>
<span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">char</span> description[] = I18N_NOOP(<span class="stringliteral">"SampleTests"</span>);
<span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">char</span> version[] = <span class="stringliteral">"0.1"</span>;
<span class="keyword">static</span> KCmdLineOptions options[] = { KCmdLineLastOption };
<span class="keywordtype">int</span> main( <span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv )
{
KAboutData about(<span class="stringliteral">"SampleTests"</span>, I18N_NOOP(<span class="stringliteral">"SampleTests"</span>), version, description,
KAboutData::License_BSD, <span class="stringliteral">"(C) 2005 You!"</span>, 0, 0, <span class="stringliteral">"mail@provider"</span>);
KCmdLineArgs::init(argc, argv, &about);
KCmdLineArgs::addCmdLineOptions( options );
KApplication app;
KUnitTest::RunnerGUI runner(0);
runner.show();
app.setMainWidget(&runner);
<span class="keywordflow">return</span> app.exec();
}
</pre></div><p>The Makefile.am file will look like:</p>
<div class="fragment"><pre class="fragment"> INCLUDES = -I$(top_srcdir)/src $(all_includes)
METASOURCES = AUTO
check_PROGRAMS = sampletests
sampletests_SOURCES = main.cpp sampletest.cpp
sampletests_LDFLAGS = $(KDE_RPATH) $(all_libraries)
sampletests_LDADD = -lkunittest
noinst_HEADERS = sampletest.h
check:
kunittest $(top_builddir)/src/sampletests SampleTests
</pre></div><p>Most of this Makefile.am will be self-explanatory. After running "make check" the binary "sampletests" will be built. The reason for adding the extra make target "check" is that you probably do not want to rebuild the test suite everytime you run make.</p>
<p>You can run the binary on its own, but you get more functionality if you use the kunittest helper script. The Makefile.am is set up in such a way that this helper script is automatically run after you do a "make check". This scripts take two arguments, the first is the path to the binary to run. The second the application name, in this case SampleTests. This name is important since it is used to let the script communicate with the application via DCOP. The helper scripts relies on the Perl DCOP bindings, so these need to be installed.</p>
<h2><a class="anchor" id="module"></a>
Creating test modules</h2>
<p>If you think that writing your own test runner if too much work then you can also use the kunittestermodrunner application or the kunitguimodrunner script to run the tests for you. You do have to put your tests in a dynamically loadable module though. Fortunately <a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> comes with a few macros to help you do this.</p>
<p>First the good news, you don't have to change the header file sampletest.h. However, we will rename it to <a class="el" href="samplemodule_8h_source.html">samplemodule.h</a>, so we remember we are making a module. The implementation file should be rename to <a class="el" href="samplemodule_8cpp_source.html">samplemodule.cpp</a>. This file requires some modifications. First we need to include the <a class="el" href="module_8h.html">module.h</a> header:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <<a class="code" href="module_8h.html">kunittest/module.h</a>></span>
</pre></div><p>This header file is needed because it defines some macro you'll need. In fact this is how you use them:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="module_8h.html#a575d7139957626186dfcf0876344606f">KUNITTEST_MODULE</a>( kunittest_samplemodule, <span class="stringliteral">"Tests for sample module"</span> );
<a class="code" href="module_8h.html#acdb9aa969d8df77112699dd5e1c64ad1">KUNITTEST_MODULE_REGISTER_TESTER</a>( SimpleSampleTester );
<a class="code" href="module_8h.html#acdb9aa969d8df77112699dd5e1c64ad1">KUNITTEST_MODULE_REGISTER_TESTER</a>( SomeSampleTester );
</pre></div><p>The first macro, <a class="el" href="module_8h.html#a575d7139957626186dfcf0876344606f">KUNITTEST_MODULE()</a>, makes sure that the module can be loaded and that the test classes are created. The first argument "kunittest_samplemodule" is the library name, in this case the library we're creating a kunittest_samplemodule.la module. The second argument is name which will appear in the test runner for this test suite.</p>
<p>The tester class are now added by the <a class="el" href="module_8h.html#acdb9aa969d8df77112699dd5e1c64ad1">KUNITTEST_MODULE_REGISTER_TESTER()</a> macro, not the <a class="el" href="runner_8h.html#ac1af23b0a525c05b4c17c5f16f7be550" title="Automatic registration of Tester classes.">KUNITTEST_REGISTER_TESTER()</a>. The only difference between the two is that you have to pass the module class name to this macro.</p>
<p>The Makefile.am is also a bit different, but not much:</p>
<div class="fragment"><pre class="fragment"> INCLUDES = -I$(top_srcdir)/include $(all_includes)
METASOURCES = AUTO
check_LTLIBRARIES = kunittest_samplemodule.la
kunittest_samplemodule_la_SOURCES = samplemodule.cpp
kunittest_samplemodule_la_LIBADD = $(LIB_KUNITTEST)
kunittest_samplemodule_la_LDFLAGS = -module $(KDE_CHECK_PLUGIN) $(all_libraries)
</pre></div><p>The macro is there to make sure a dynamically loadable module is created.</p>
<p>After you have built the module you open a Konsole and cd into the build folder. Running the tests in the module is now as easy as:</p>
<div class="fragment"><pre class="fragment"> $ make check && kunittestmodrunner
</pre></div><p>The kunittestmodrunner application loads all kunittest_*.la modules in the current directory. The exit code of this console application is the number of unexpected failures.</p>
<p>If you want the GUI, you should use the kunittestmod script:</p>
<div class="fragment"><pre class="fragment"> $ make check && kunittestmod
</pre></div><p>This script starts kunittestguimodrunner application and a helper script to take care of dealing with debug output.</p>
<h2><a class="anchor" id="advanced"></a>
Advanced usage</h2>
<p>Normally you just want to use <a class="el" href="tester_8h.html#a4fd95491287cc131e6ae4f5dafc26ac1">CHECK()</a>. If you are developing some more tests, and they are run (or not) based on some external dependency, you may need to skip some tests. In this case, rather than doing nothing (or worse, writing a test step that aborts the test run), you might want to use <a class="el" href="tester_8h.html#a634ab9b9480188b1ed710cbedd91f156">SKIP()</a> to record that. Note that this is just a logging / reporting tool, so you just pass in a string:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="tester_8h.html#a634ab9b9480188b1ed710cbedd91f156">SKIP</a>( <span class="stringliteral">"Test skipped because of lack of foo support."</span> );
</pre></div><p>Similarly, you may have a test step that you know will fail, but you don't want to delete the test step (because it is showing a bug), but equally you can't fix it right now (eg it would break binary compatibility, or would violate a string freeze). In that case, it might help to use <a class="el" href="tester_8h.html#a083ae9c5c4eda5232b45ec2e1f8f1801">XFAIL()</a>, for "expected failure". The test will still be run, and recorded as a failure (assuming it does fail), but will also be recorded separately. Usage might be as follows:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="tester_8h.html#a083ae9c5c4eda5232b45ec2e1f8f1801">XFAIL</a>( 2+1, 4 );
</pre></div><p>You can mix <a class="el" href="tester_8h.html#a4fd95491287cc131e6ae4f5dafc26ac1">CHECK()</a>, <a class="el" href="tester_8h.html#a634ab9b9480188b1ed710cbedd91f156">SKIP()</a> and <a class="el" href="tester_8h.html#a083ae9c5c4eda5232b45ec2e1f8f1801">XFAIL()</a> within a single Tester derived class.</p>
<h2><a class="anchor" id="exceptions"></a>
Exceptions</h2>
<p><a class="el" href="namespaceKUnitTest.html" title="Namespace for Unit testing classes.">KUnitTest</a> comes with simple support for testing whether an exception, such as a function call, throws an exception or not. Simply, for the usual macros there corresponding ones for exception testing: <a class="el" href="tester_8h.html#a0b66e2c1e37fa4ef3d20468f6c478234">CHECK_EXCEPTION()</a>, <a class="el" href="tester_8h.html#aa9792f7d211cb95f23e38ab30f7aad9d">XFAIL_EXCEPTION()</a>, and <a class="el" href="tester_8h.html#a6f8532018c41967598a798ae9e3ed943">SKIP_EXCEPTION()</a>. They all take two arguments: the expression that will catch the exception, and the expression that is supposed to throw the exception.</p>
<p>For example:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="tester_8h.html#a0b66e2c1e37fa4ef3d20468f6c478234">CHECK_EXCEPTION</a>(EvilToothFairyException *, myFunction(<span class="stringliteral">"I forgot to brush my teeth!"</span>));
</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>The exception is not de-allocated in anyway.</dd></dl>
<p>The macros does not allow introspection of the exceptions, such as testing a supplied identifier code on the exception object or similar; this requires manual coding, such as custom macros.</p>
<h2><a class="anchor" id="scripts"></a>
Scripts</h2>
<p>The library comes with several helper scripts:</p>
<ul>
<li>kunittest [app] [dcopobject] : Runs the application app and redirects all debug output to the dcopobject. </li>
<li>kunittestmod --folder [folder] --query [query] : Loads and runs all modules in the folder matching the query. Use a GUI. </li>
<li>kunittest_debughelper [dcopobject] : A PERL script that is able to redirect debug output to a RunnerGUI instance.</li>
</ul>
<p>These scripts are part of the kdesdk/kunittest module. </p>
</div></div>
</div></div>
</td>
</tr>
<tr>
<td valign="top" id="leftmenu" width="25%">
<a name="navigation"></a>
<div class="menu_box"><h2>kunittest</h2>
<div class="nav_list">
<ul><li><a href="index.html">Main Page</a></li><li><a href="namespaces.html">Namespace List</a></li><li><a href="hierarchy.html">Class Hierarchy</a></li><li><a href="classes.html">Alphabetical List</a></li><li><a href="annotated.html">Class List</a></li><li><a href="files.html">File List</a></li><li><a href="namespacemembers.html">Namespace Members</a></li><li><a href="functions.html">Class Members</a></li></ul>
<!--
<h2>Class Picker</h2>
<div style="text-align: center;">
<form name="guideform">
<select name="guidelinks" style="width:100%;" onChange="window.location=document.guideform.guidelinks.options[document.guideform.guidelinks.selectedIndex].value">
<option value="annotated.html">-- Choose --</option>
<option value="classKUnitTest_1_1Runner.html">kunittest::runner</option>, <option value="classKUnitTest_1_1SlotTester.html">kunittest::slottester</option>, <option value="classKUnitTest_1_1Tester.html">kunittest::tester</option>, <option value="classKUnitTest_1_1TesterAutoregister.html">kunittest::testerautoregister</option>, <option value="classKUnitTest_1_1TestResults.html">kunittest::testresults</option>,
</select>
</form>
</div>
-->
</div></div>
<div class="menu_box"><h2>API Dox</h2>
<div class="nav_list">
<ul>
<li><a href="../../arts/html/index.html">arts</a></li><li><a href="../../dcop/html/index.html">dcop</a></li><li><a href="../../dnssd/html/index.html">dnssd</a></li><li><a href="../../interfaces/html/index.html">interfaces</a></li><li> <a href="../../interfaces/kimproxy/interface/html/index.html">interface</a></li><li> <a href="../../interfaces/kimproxy/library/html/index.html">library</a></li><li> <a href="../../interfaces/kspeech/html/index.html">kspeech</a></li><li> <a href="../../interfaces/ktexteditor/html/index.html">ktexteditor</a></li><li><a href="../../kabc/html/index.html">kabc</a></li><li><a href="../../kate/html/index.html">kate</a></li><li><a href="../../kcmshell/html/index.html">kcmshell</a></li><li><a href="../../kdecore/html/index.html">kdecore</a></li><li><a href="../../kded/html/index.html">kded</a></li><li><a href="../../kdefx/html/index.html">kdefx</a></li><li><a href="../../kdeprint/html/index.html">kdeprint</a></li><li><a href="../../kdesu/html/index.html">kdesu</a></li><li><a href="../../kdeui/html/index.html">kdeui</a></li><li><a href="../../kdoctools/html/index.html">kdoctools</a></li><li><a href="../../khtml/html/index.html">khtml</a></li><li><a href="../../kimgio/html/index.html">kimgio</a></li><li><a href="../../kinit/html/index.html">kinit</a></li><li><a href="../../kio/html/index.html">kio</a></li><li> <a href="../../kio/bookmarks/html/index.html">bookmarks</a></li><li> <a href="../../kio/httpfilter/html/index.html">httpfilter</a></li><li> <a href="../../kio/kfile/html/index.html">kfile</a></li><li> <a href="../../kio/kio/html/index.html">kio</a></li><li> <a href="../../kio/kioexec/html/index.html">kioexec</a></li><li> <a href="../../kio/kpasswdserver/html/index.html">kpasswdserver</a></li><li> <a href="../../kio/kssl/html/index.html">kssl</a></li><li><a href="../../kioslave/html/index.html">kioslave</a></li><li> <a href="../../kioslave/http/html/index.html">http</a></li><li><a href="../../kjs/html/index.html">kjs</a></li><li><a href="../../kmdi/html/index.html">kmdi</a></li><li> <a href="../../kmdi/kmdi/html/index.html">kmdi</a></li><li><a href="../../knewstuff/html/index.html">knewstuff</a></li><li><a href="../../kparts/html/index.html">kparts</a></li><li><a href="../../kresources/html/index.html">kresources</a></li><li><a href="../../kspell2/html/index.html">kspell2</a></li><li><a href="../../kunittest/html/index.html">kunittest</a></li><li><a href="../../kutils/html/index.html">kutils</a></li><li><a href="../../kwallet/html/index.html">kwallet</a></li><li><a href="../../libkmid/html/index.html">libkmid</a></li><li><a href="../../libkscreensaver/html/index.html">libkscreensaver</a></li>
</ul></div></div>
</td>
</tr>
</table>
<span class="doNotDisplay">
<a href="http://www.kde.org/" accesskey="8">KDE Home</a> |
<a href="http://accessibility.kde.org/" accesskey="9">KDE Accessibility Home</a> |
<a href="http://www.kde.org/media/accesskeys.php" accesskey="0">Description of Access Keys</a>
</span>
<div style="height: 8px"></div>
<div id="footer">
<div id="footer_left">
Maintained by <a href="mailto:groot@kde.org">Adriaan de Groot</a>
and
<a href="mailto:winter@kde.org">Allen Winter</a>.
<br/>
KDE and K Desktop Environment are trademarks of <a href="http://www.kde.org/areas/kde-ev/" title="Homepage of the KDE non-profit Organization">KDE e.V.</a> |
<a href="http://www.kde.org/contact/impressum.php">Legal</a>
</div>
<div id="footer_right"><img src="/media/images/footer_right.png" style="margin: 0px" alt="" /></div>
</div>
<!--
WARNING: DO NOT SEND MAIL TO THE FOLLOWING EMAIL ADDRESS! YOU WILL
BE BLOCKED INSTANTLY AND PERMANENTLY!
<a href="mailto:aaaatrap-425acc3b5374943f@kde.org">Block me</a>
WARNING END
-->
</body>
</html>
