<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry 
  PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="features">
<refmeta>
  <refentrytitle role='top_of_page' id='features.top_of_page'>Features</refentrytitle>
  <refmiscinfo>CUTTER Library</refmiscinfo>
</refmeta>
<refnamediv>
  <refname>Features</refname>
  <refpurpose>What can be done with Cutter</refpurpose>
</refnamediv>
<refsect1>
  <title>Introduction</title>
  <para>Cutter has basic features of a unit testing framework:</para>
  <itemizedlist>
  <listitem>
  <para>Fixture</para>
</listitem>
  <listitem>
  <para>No test registration code</para>
</listitem>
  <listitem>
  <para>Result output with useful format for debugging</para>
</listitem>
  <listitem>
  <para>Many assertions</para>
</listitem>
</itemizedlist>
  <para>Cutter also has many useful advanced features:</para>
  <itemizedlist>
  <listitem>
  <para>Cross platform</para>
</listitem>
  <listitem>
  <para>Data-Driven Testing support</para>
</listitem>
  <listitem>
  <para>Coverage support</para>
</listitem>
  <listitem>
  <para>Backtrace on crash</para>
</listitem>
  <listitem>
  <para>Serialize/deserialize test result</para>
</listitem>
  <listitem>
  <para>Multi-process/multi-thread support</para>
</listitem>
  <listitem>
  <para>Image diff</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</refsect1>

<refsect1>
  <title>Basic</title>
  <para>This section explains how Cutter provides features that are considered about basic unit testing framework features.</para>
  <refsect2>
  <title>Fixture</title>
  <para>
  Fixture in a unit testing framework is a mechanism that set up test data before each test. It is usually implemented by executing setup/teardown process. See also
  <ulink url='http://en.wikipedia.org/wiki/Test_fixture'>Test fixture (Wikipedia)</ulink>
  .
</para>
  <para>In Cutter, if cut_setup()/cut_teardown() functions are defined in a test program like the following, their functions are treated as setup/teardown processes:</para>
  <programlisting>void
cut_setup (void)
{
   /* set up test data */
}

void
cut_teardown (void)
{
   /* tear down test data */
}</programlisting>
  <para>Cutter also supports cut_startup()/cut_shutdown() functions that are called on each test case starting/completing:</para>
  <programlisting>void
cut_startup (void)
{
   /* set up the test case */
}

void
cut_shutdown (void)
{
   /* tear down the test case*/
}</programlisting>
  <para>Their functions are called the following order:</para>
  <itemizedlist>
  <listitem>
  <para>cut_startup()</para>
  <itemizedlist>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>run test1</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>run test2</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_shutdown()</para>
</listitem>
</itemizedlist>
  <para>Cutter also supports functions that are called on all test starting/completing as experimental features. Their functions are called warmup/cooldown. Here is the call order:</para>
  <itemizedlist>
  <listitem>
  <para>run warmup</para>
  <itemizedlist>
  <listitem>
  <para>cut_startup() of test case1</para>
  <itemizedlist>
  <listitem>
  <para>cut_setup() of test case1</para>
  <itemizedlist>
  <listitem>
  <para>run test1-1</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown() of test case1</para>
</listitem>
  <listitem>
  <para>cut_setup() of test case1</para>
  <itemizedlist>
  <listitem>
  <para>run test1-2</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown() of test case1</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_shutdown() of test case1</para>
</listitem>
  <listitem>
  <para>cut_startup() of test case2</para>
  <itemizedlist>
  <listitem>
  <para>cut_setup() of test case2</para>
  <itemizedlist>
  <listitem>
  <para>run test2-1</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown() of test case2</para>
</listitem>
  <listitem>
  <para>cut_setup() of test case2</para>
  <itemizedlist>
  <listitem>
  <para>run test2-2</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown() of test case2</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_shutdown() of test case1</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>run cooldown</para>
</listitem>
</itemizedlist>
  <para>The last two functions are useful for testing a library that has initialize/finalize functions of itself. But they are experimental features. So explanation of their usage is omitted. If you want to use them, please contact us.</para>
</refsect2>

  <refsect2>
  <title>No test registration code</title>
  <para>Most of unit testing frameworks for dynamic languages doesn&#39;t require that users register their tests. Tests are found by frameworks and ran. But most of unit testing frameworks for C require that users register their tests.</para>
  <para>Cutter finds test functions automatically like frameworks for dynamic languages to write tests easily. Public functions that their name starts with &quot;test_&quot; are recognized as test functions. Here is a sample test function definition:</para>
  <programlisting>void test_my_function (void);

void
test_my_function (void)
{
    /* a test function */
}</programlisting>
</refsect2>

  <refsect2>
  <title>Result output with useful format for debugging</title>
  <para>Cutter outputs a test result to confirm and fix a problem quickly. In particular Cutter outputs</para>
  <itemizedlist>
  <listitem>
  <para>no problem parts simply and</para>
</listitem>
  <listitem>
  <para>problem parts verbosely.</para>
</listitem>
</itemizedlist>
  <para>Cutter outputs no problem parts simply (they may not be displayed) to avoid important parts are buried.</para>
  <para>Cutter outputs information of problem parts as many as possible to provide users information to judge what is a problem.</para>
  <para>For example, we assume that an expected string and an actual string are different on string equality check test. Cutter arranges and displays the expected string and the actual string to confirm difference between them easily:</para>
  <programlisting>expected: &lt;abc def ghi jkl&gt;
 but was: &lt;abc DEF ghi jkl&gt;</programlisting>
  <para>If their aren&#39;t arranged or displayed in the same line, it&#39;s difficult to find difference between them:</para>
  <programlisting>expected: &lt;abc def ghi jkl&gt;
but was: &lt;abc DEF ghi jkl&gt;

&lt;abc def ghi jkl&gt; is expected but was &lt;abc DEF ghi jkl&gt;</programlisting>
  <para>Cutter also outputs diff between the expected string and the actual string to show where is different explicitly:</para>
  <programlisting>expected: &lt;abc def ghi jkl&gt;
 but was: &lt;abc DEF ghi jkl&gt;

diff:
- abc def ghi jkl
?     ^^^
+ abc DEF ghi jkl
?     ^^^</programlisting>
  <para>Cutter strongly helps us to confirm a problem on test failure as mentioned above.</para>
</refsect2>

  <refsect2>
  <title>Many assertions</title>
  <para>
  <ulink url='http://en.wikipedia.org/wiki/XUnit'>xUnit</ulink>
   based unit testing frameworks provides assertions to assert test target works as we had expected. For example, many frameworks provides assertions like the followings:
</para>
  <itemizedlist>
  <listitem>
  <para>assert: asserts that target is true value</para>
</listitem>
  <listitem>
  <para>assert_equal: asserts that an actual value equals an expected value</para>
</listitem>
</itemizedlist>
  <para>In Cutter, the following assertions are corresponding the above assertions:</para>
  <itemizedlist>
  <listitem>
  <para>cut_assert()</para>
</listitem>
  <listitem>
  <para>cut_assert_true(): asserts same as cut_assert() but it clearly specifies &quot;true value&quot; (Cutter recommends to use it because it&#39;s self-describing rather than cut_assert())</para>
</listitem>
  <listitem>
  <para>cut_assert_equal_int()</para>
</listitem>
  <listitem>
  <para>cut_assert_equal_uint()</para>
</listitem>
  <listitem>
  <para>cut_assert_equal_string()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
  <para>Cutter also provides many built-in assertions than common assertions as mentioned above to write tests easily. For example, Cutter provides built-in assertions like the followings:</para>
  <itemizedlist>
  <listitem>
  <para>cut_assert_errno(): asserts that errno is 0</para>
</listitem>
  <listitem>
  <para>cut_assert_match(): asserts that an expected string matches an actual string</para>
</listitem>
  <listitem>
  <para>cut_assert_path_exist(): asserts that specified path exists</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
  <para>
  See 
  <link linkend='cutter-cut-assertions'>Assertions</link>
   and
  <link linkend='cutter-gcut-assertions'>Assertions with GLib support</link>
   in the reference manual for assertion list.
</para>
</refsect2>

</refsect1>


<refsect1>
  <title>Advanced</title>
  <para>This section explains how Cutter provides features that are provided by a few unit testing frameworks or not provided any unit testing frameworks.</para>
  <refsect2>
  <title>Cross platform</title>
  <para>For now, Cutter works on the following platforms:</para>
  <itemizedlist>
  <listitem>
  <para>GNU/Linux</para>
</listitem>
  <listitem>
  <para>FreeBSD</para>
</listitem>
  <listitem>
  <para>Mac OS X</para>
</listitem>
  <listitem>
  <para>Windows (MinGW)</para>
</listitem>
</itemizedlist>
</refsect2>
  <refsect2>
  <title>Data-Driven Testing support</title>
  <para>
  There is a testing method called 
  <ulink url='http://en.wikipedia.org/wiki/Data-driven_testing'>Data-Driven Testing</ulink>
  .
</para>
  <para>
  Cutter supports Data-Driven Testing. See 
  <ulink url='http://cutter.sourceforge.net/reference/cutter-cutter.html#cut-add-data'>cut_add_data()</ulink>
  for writing a data-driven test.
</para>
  <para>Data-driven tests are executed by the following order:</para>
  <itemizedlist>
  <listitem>
  <para>call data setup function</para>
</listitem>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>run test with test data1</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>run test with test data2</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</refsect2>
  <refsect2>
  <title>Coverage support</title>
  <para>
  <ulink url='http://en.wikipedia.org/wiki/Code_coverage'>Code coverage</ulink>
  is a measure for how code is tested cyclopaedically.
</para>
  <para>Cutter provides a M4 macro to help us measuring code coverage. If you use GNU Autoconf/GNU Automake, you can add code coverage support into your build system easily.</para>
  <para>
  See about AC_CHECK_COVERAGE in 
  <link linkend='readme'>README</link>
   and
  <link linkend='tutorial'>TUTORIAL</link>
  .
</para>
</refsect2>
  <refsect2>
  <title>Backtrace on crash</title>
  <para>It&#39;s natural that a program written in C and/or C++crashes. Cutter tries to retrieve a backtrace on SEGV signal is raised. If a backtrace is retrieved, Cutter outputs it and exit. Of course Cutter cannot always retrieve a backtrace because the test process is broken.</para>
  <para>To check details of a problem, we need to use a debugger like GDB. But we can use a backtrace as the first step.</para>
</refsect2>
  <refsect2>
  <title>Serialize/deserialize test result</title>
  <para>There are some methods to confirm how high software&#39;s quality:</para>
  <itemizedlist>
  <listitem>
  <para>measuring transition between test status and number of found bugs.</para>
</listitem>
  <listitem>
  <para>measuring transition between test status and number of reported bugs.</para>
</listitem>
  <listitem>
  <para>measuring transition between test status and source code size.</para>
</listitem>
</itemizedlist>
  <para>For example, if number of tests are grown but number of found bugs aren&#39;t grown, we may be doing inefficient test or software quality might be high without test. If number of tests are grown but number of reported bugs are grown, we may be testing irrelevance points. If source code size is grown but number of tests aren&#39;t grown, we may lazy.</para>
  <para>We can analyze software development status with test result logs in chronological order not just the current test result. We may use analyzed result to improve software quality.</para>
  <para>Cutter can save a test result to a file as XML. Cutter can also read saved XML and restore a test result.</para>
  <para>Cutter will provide a feature that charts test result logs.</para>
</refsect2>
</refsect1>
</refentry>
