<html>
<head>
<title>CppTest - A C++ Unit Testing Framework</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
</head>
<body bgcolor="#ffffff">
<table width="100%">
<tr>
<td width="40%" align="right" valign="center">
<a href="http://cpptest.sourceforge.net">CppTest home page</a>
</td>
<td></td>
<td width="40%" align="left" valign="center">
<a href="http://sourceforge.net/projects/cpptest">CppTest project page</a>
</td>
</tr>
</table>
<hr>
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1><a class="anchor" id="tutorial">Tutorial </a></h1><h2><a class="anchor" id="Contents">
Contents</a></h2>
<ul>
<li><a class="el" href="tutorial.html#tutorial_introduction">Introduction</a></li>
<li><a class="el" href="tutorial.html#tutorial_tests">Tests</a><ul>
<li><a class="el" href="tutorial.html#tutorial_test_cases">Test cases</a></li>
<li><a class="el" href="tutorial.html#tutorial_asserts">Asserts</a></li>
</ul>
</li>
<li><a class="el" href="tutorial.html#tutorial_output_handlers">Output handlers</a><ul>
<li><a class="el" href="tutorial.html#tutorial_available_output_handlers">Available output handlers</a></li>
<li><a class="el" href="tutorial.html#tutorial_screenshots">Screenshots</a></li>
</ul>
</li>
<li><a class="el" href="tutorial.html#tutorial_test_suites">Test suites</a><ul>
<li><a class="el" href="tutorial.html#tutorial_running_test_suites">Running test suites</a></li>
<li><a class="el" href="tutorial.html#tutorial_embedded_test_suites">Embedded test suites</a></li>
<li><a class="el" href="tutorial.html#tutorial_test_fixtures">Test fixtures</a></li>
</ul>
</li>
</ul>
<h2><a class="anchor" id="tutorial_introduction">
Introduction</a></h2>
<p>CppTest is a portable and powerful, yet simple, unit testing framework for handling automated tests in C++. The focus lies on usability and extendability. Several output formats are supported and new ones are easily added.</p>
<p>This tutorial is intended to quickly get you started.</p>
<p>CppTest is released under the GNU <a href="http://www.gnu.org/copyleft/lesser.html">Lesser General Public License</a>.</p>
<h2><a class="anchor" id="tutorial_tests">
Tests</a></h2>
<h3><a class="anchor" id="tutorial_test_cases">
Test cases</a></h3>
<p>Each test must be created and run within a test suite (see <a class="el" href="tutorial.html#tutorial_test_suites">Test suites</a> below), which must be derived from <a class="el" href="classTest_1_1Suite.html" title="Unit testing suite.">Test::Suite</a>. Tests must be registered with the <a class="el" href="cpptest-suite_8h.html#abe8c3e0a2cf3893ebc1c265264ed9cb8">TEST_ADD(func)</a> macro inorder to be executed. Note that a test function must return <code>void</code> and take no parameters. For example:</p>
<div class="fragment"><pre class="fragment"><span class="keyword">class </span>ExampleTestSuite : <span class="keyword">public</span> Test::Suite
{
<span class="keyword">public</span>:
ExampleTestSuite()
{
<a class="code" href="cpptest-suite_8h.html#abe8c3e0a2cf3893ebc1c265264ed9cb8">TEST_ADD</a>(ExampleTestSuite::first_test)
<a class="code" href="cpptest-suite_8h.html#abe8c3e0a2cf3893ebc1c265264ed9cb8">TEST_ADD</a>(ExampleTestSuite::second_test)
}
private:
<span class="keywordtype">void</span> first_test();
<span class="keywordtype">void</span> second_test();
};
</pre></div><h3><a class="anchor" id="tutorial_asserts">
Asserts</a></h3>
<p>Asserts are used to ensure that the tests are correct. If not, one or more asserts will be generated. There exist several types of asserts, see <a class="el" href="asserts.html">Available asserts</a> for a complete list.</p>
<p>For example, the functions declared within <code>ExampleTestSuite</code> may be declared as:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> ExampleTestSuite::first_test()
{
<span class="comment">// Will succeed since the expression evaluates to true</span>
<span class="comment">//</span>
<a class="code" href="cpptest-assert_8h.html#a29a763f14098f5574ae5c68291dc6ddd">TEST_ASSERT</a>(1 + 1 == 2)
<span class="comment">// Will fail since the expression evaluates to false</span>
<span class="comment">//</span>
<a class="code" href="cpptest-assert_8h.html#a29a763f14098f5574ae5c68291dc6ddd">TEST_ASSERT</a>(0 == 1);
}
<span class="keywordtype">void</span> ExampleTestSuite::second_test()
{
<span class="comment">// Will succeed since the expression evaluates to true</span>
<span class="comment">//</span>
<a class="code" href="cpptest-assert_8h.html#a9583b1709f4b9dfb3ff2849bfec5c885">TEST_ASSERT_DELTA</a>(0.5, 0.7, 0.3);
<span class="comment">// Will fail since the expression evaluates to false</span>
<span class="comment">//</span>
<a class="code" href="cpptest-assert_8h.html#a9583b1709f4b9dfb3ff2849bfec5c885">TEST_ASSERT_DELTA</a>(0.5, 0.7, 0.1);
}
</pre></div><h2><a class="anchor" id="tutorial_output_handlers">
Output handlers</a></h2>
<h3><a class="anchor" id="tutorial_available_output_handlers">
Available output handlers</a></h3>
<p>An output handler takes care of all assert messages and generates some output as result. There exist several output handlers that all fit different needs. Currently, the following output handlers exist:</p>
<ul>
<li><a class="el" href="classTest_1_1TextOutput.html" title="Text output handler that outputs to the a stream.">Test::TextOutput</a>, which is a simple output handler that outputs its result to standard out in either terse or verbose mode.</li>
<li><a class="el" href="classTest_1_1CompilerOutput.html" title="Compiler-like output handler.">Test::CompilerOutput</a>, which emulates the output of a compiler. This makes it easy to integrate unit testing into your build environment.</li>
<li><a class="el" href="classTest_1_1HtmlOutput.html" title="HTML output.">Test::HtmlOutput</a>, which outputs a fancy HTML table.</li>
</ul>
<p>New output handlers should be derived from <a class="el" href="classTest_1_1Output.html" title="Test suite output handler.">Test::Output</a>.</p>
<h3><a class="anchor" id="tutorial_screenshots">
Screenshots</a></h3>
<p>The result from the different output handlers is shown below:</p>
<ul>
<li><a href="screenshot-text-terse.png">Terse text output</a></li>
<li><a href="screenshot-text-verbose.png">Verbose text output</a></li>
<li><a href="screenshot-compiler.png">Compiler output</a></li>
<li><a href="html-example.html">HTML output</a></li>
</ul>
<h2><a class="anchor" id="tutorial_test_suites">
Test suites</a></h2>
<h3><a class="anchor" id="tutorial_running_test_suites">
Running test suites</a></h3>
<p>The tests within a test suite are all executed when <a class="el" href="classTest_1_1Suite.html#ad17746e218da79c537bc9d21e389f570">Test::Suite::run()</a> is called. This method returns a boolean value that only returns true if all tests were successful. This value may be used to return a suiteable value from the program. For example, the following is required to execute our tests within <code>ExampleTestSuite</code>:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classTest_1_1TextOutput.html" title="Text output handler that outputs to the a stream.">Test::TextOutput</a> output(<a class="code" href="classTest_1_1TextOutput.html#ae7b22c9458e6c566996bf4517c73feb1a85dd6e42f6261a23fd504201f5cc2792">Test::TextOutput::Verbose</a>);
ExampleTestSuite ets;
<span class="keywordflow">return</span> ets.run(output) ? EXIT_SUCCESS : EXIT_FAILURE;
</pre></div><p>Note that a single test normally continues after an assert. However, this behavior may be changed with an optional parameter to <a class="el" href="classTest_1_1Suite.html#ad17746e218da79c537bc9d21e389f570">Test::Suite::run()</a>. For example:</p>
<div class="fragment"><pre class="fragment"><span class="keyword">class </span>SomeTestSuite: <span class="keyword">public</span> Test::Suite
{
<span class="keyword">public</span>:
SomeTestSuite() { <a class="code" href="cpptest-suite_8h.html#abe8c3e0a2cf3893ebc1c265264ed9cb8">TEST_ADD</a>(SomeTestSuite::test) }
<span class="keyword">private</span>:
<span class="keywordtype">void</span> test()
{
<a class="code" href="cpptest-assert_8h.html#a947ab44cc42369eb7cfe33f8a1e38e4b">TEST_FAIL</a>(<span class="stringliteral">"this will always fail"</span>)
<a class="code" href="cpptest-assert_8h.html#a947ab44cc42369eb7cfe33f8a1e38e4b">TEST_FAIL</a>("this assert will never be executed")
}
};
<span class="keywordtype">bool</span> run_tests()
{
SomeTestSuite sts;
<a class="code" href="classTest_1_1TextOutput.html" title="Text output handler that outputs to the a stream.">Test::TextOutput</a> output(<a class="code" href="classTest_1_1TextOutput.html#ae7b22c9458e6c566996bf4517c73feb1a85dd6e42f6261a23fd504201f5cc2792">Test::TextOutput::Verbose</a>);
<span class="keywordflow">return</span> sts.run(output, <span class="keyword">false</span>); <span class="comment">// Note the 'false' parameter</span>
}
</pre></div><h3><a class="anchor" id="tutorial_embedded_test_suites">
Embedded test suites</a></h3>
<p><a class="el" href="namespaceTest.html">Test</a> suites may also be added other test suites using Test::Suite::add(). This way, you may develop logically separated test suites and run all tests at once. For example:</p>
<div class="fragment"><pre class="fragment"><span class="keyword">class </span>TestSuite1: <span class="keyword">public</span> Test::Suite { }; <span class="comment">// ... with many tests</span>
<span class="keyword">class </span>TestSuite2: <span class="keyword">public</span> Test::Suite { }; <span class="comment">// ... with many tests</span>
<span class="keyword">class </span>TestSuite3: <span class="keyword">public</span> Test::Suite { }; <span class="comment">// ... with many tests</span>
<span class="keywordtype">bool</span> run_tests()
{
<a class="code" href="classTest_1_1Suite.html" title="Unit testing suite.">Test::Suite</a> ts;
ts.add(auto_ptr<Test::Suite>(<span class="keyword">new</span> TestSuite1));
ts.add(auto_ptr<Test::Suite>(<span class="keyword">new</span> TestSuite2));
ts.add(auto_ptr<Test::Suite>(<span class="keyword">new</span> TestSuite3));
<a class="code" href="classTest_1_1TextOutput.html" title="Text output handler that outputs to the a stream.">Test::TextOutput</a> output(<a class="code" href="classTest_1_1TextOutput.html#ae7b22c9458e6c566996bf4517c73feb1a85dd6e42f6261a23fd504201f5cc2792">Test::TextOutput::Verbose</a>);
<span class="keywordflow">return</span> ts.<a class="code" href="classTest_1_1Suite.html#ad17746e218da79c537bc9d21e389f570">run</a>(output);
}
</pre></div><h3><a class="anchor" id="tutorial_test_fixtures">
Test fixtures</a></h3>
<p><a class="el" href="namespaceTest.html">Test</a> cases in the same test suite often share the same requirements, they all require some known set of objects or resources. Instead of repeating all initialization code for each test it may be moved to the <a class="el" href="classTest_1_1Suite.html#afb4c733e6c46a011818bb02f2e8d5bb8">Test::Suite::setup()</a> and <a class="el" href="classTest_1_1Suite.html#a37d3595625cff09b8e43bf6c414ff610">Test::Suite::tear_down()</a> functions. The setup function is called before each test function is called, and the tear down function is called after each test function has been called. For example:</p>
<div class="fragment"><pre class="fragment"><span class="keyword">class </span>SomeTestSuite: <span class="keyword">public</span> Test::Suite
{
<span class="keyword">public</span>:
SomeTestSuite()
{
<a class="code" href="cpptest-suite_8h.html#abe8c3e0a2cf3893ebc1c265264ed9cb8">TEST_ADD</a>(SomeTestSuite::test1)
<a class="code" href="cpptest-suite_8h.html#abe8c3e0a2cf3893ebc1c265264ed9cb8">TEST_ADD</a>(SomeTestSuite::test2)
}
protected:
virtual <span class="keywordtype">void</span> setup() {} <span class="comment">// setup resources... </span>
<span class="keyword">virtual</span> <span class="keywordtype">void</span> tear_down() {} <span class="comment">// remove resources...</span>
<span class="keyword">private</span>:
<span class="keywordtype">void</span> test1() {} <span class="comment">// use common resources...</span>
<span class="keywordtype">void</span> test2() {} <span class="comment">// use common resources...</span>
};
</pre></div> </div>
<hr>
<div align="center">
Supported by:
<br><br>
<img src="http://sourceforge.net/sflogo.php?group_id=77564"
width="88" height="31" border="0" alt="SourceForge Logo"></a>
</div>
</body>
</html>
