<?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" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cutter-Cutter">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Cutter.top_of_page">Cutter</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Cutter</refname>
<refpurpose>A Unit Testing Framework for C and C++.</refpurpose>
</refnamediv>

<refsynopsisdiv id="cutter-Cutter.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>#define             <link linkend="CUT-EXPORT:CAPS">CUT_EXPORT</link>
#define             <link linkend="cut-add-data">cut_add_data</link>                        (first_data_name,
                                                         ...)
#define             <link linkend="cut-add-data-backward-compatibility">cut_add_data_backward_compatibility</link> (context,
                                                         ...)
<link linkend="CutTestContext"><returnvalue>CutTestContext</returnvalue></link> *    <link linkend="cut-get-current-test-context">cut_get_current_test_context</link>        (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-keep-message">cut_keep_message</link>                    (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-message">cut_message</link>                         (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-set-attributes">cut_set_attributes</link>                  (<parameter>const <link linkend="char"><type>char</type></link> *first_attribute_name</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-set-current-test-context">cut_set_current_test_context</link>        (<parameter><link linkend="CutTestContext"><type>CutTestContext</type></link> *test_context</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-set-message">cut_set_message</link>                     (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-set-message-va-list">cut_set_message_va_list</link>             (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-setup">cut_setup</link>                           (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-shutdown">cut_shutdown</link>                        (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-startup">cut_startup</link>                         (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-teardown">cut_teardown</link>                        (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="setup">setup</link>                               (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="teardown">teardown</link>                            (<parameter><type>void</type></parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="cutter-Cutter.description" role="desc">
<title role="desc.title">Description</title>
<para>
Cutter is a Unit Testing Framework for C and C++ and has
the following features:
<itemizedlist>
  <listitem><para>
Easy to use. Cutter doesn't introduce any magic macros
like CUTTER_DEFINE_TEST_START and CUTTER_DEFINE_TEST_END
into your test program. You can write your test program
like normal program. You only use <link linkend="cut-assert-XXX"><function>cut_assert_XXX()</function></link> to
check that your program works as you expect.
<informalexample><programlisting>
#include &lt;cutter.h&gt;
#include "my-stack.h"

void
test_my_stack (void)
{
    MyStack *stack = my_stack_new();

    cut_assert_not_null(stack);
    cut_assert(my_stack_is_empty(stack));
    cut_assert_equal_int(0, my_stack_get_size(stack));

    my_stack_push(stack, 10);
    cut_assert(!my_stack_is_empty(stack));
    cut_assert_equal_int(1, my_stack_get_size(stack));

    my_stack_push(stack, 20);
    cut_assert_equal_int(2, my_stack_get_size(stack));

    cut_assert_equal(20, my_stack_pop(stack));
    cut_assert(!my_stack_is_empty(stack));
    cut_assert_equal_int(1, my_stack_get_size(stack));

    cut_assert_equal(10, my_stack_pop(stack));
    cut_assert(my_stack_is_empty(stack));
    cut_assert_equal_int(0, my_stack_get_size(stack));
}
</programlisting></informalexample>
  </para></listitem>
  <listitem><para>
Simple but useful output. Cutter works quietly if tests
are running without any problems by default. The
following is an output of self test:
<informalexample><programlisting>
...........................................................

Finished in 0.213021 seconds

59 test(s), 246 assertion(s), 0 failure(s), 0 error(s), 0 pending(s), 0 notification(s)
</programlisting></informalexample>
Cutter just outputs "." for a passed test and a summary
at the end. Cutter doesn't output each test name, how
many assertions are used for a test and so because we
don't need the information on success.
  </para><para>
Cutter outputs many information on failure:
<informalexample><programlisting>
.....................F.....................................

1) Failure: test_error
&lt;"Strange" == cut_test_result_get_test_name(result)&gt;
expected: &lt;Strange!!!&gt;
 but was: &lt;dummy-error-test>
test/test-cut-assertions.c:240: cut_assert_test_result()

Finished in 0.223657 seconds

59 test(s), 242 assertion(s), 1 failure(s), 0 error(s), 0 pending(s), 0 notification(s)
</programlisting></informalexample>
The above result is happened because I add a strange
expected staring in Cutter's self test:
<informalexample><programlisting>
cut_assert_equal_string("Strange!!!", cut_test_result_get_test_name(result));
</programlisting></informalexample>
The strange assertion is written in the 240th line in
test/test-cut-assertions.c and the line is in the
<link linkend="cut-assert-test-result"><function>cut_assert_test_result()</function></link> function. The function is called
in test_error test. We expected
cut_test_result_get_test_name(result) should return
"Strange!!!" but got "dummy-error-name". We can get the
above information from Cutter output. This will help your
debug.
  </para><para>
Cutter's output format is pragmatic. ' but was:' is
indented and aligned with the above 'expected:'. This
helps that you find difference between expected value and
actual value by your eyes easily. The problem line is
formated as 'FILENAME:LINE: FUNCTION' to integrate
Emacs. In Emacs's compilation-mode, if the format is
appeared in *compilation* buffer, we can jump to FILENAME
at LINE with next-error command. (C-x `) This helps that you
find the problem line rapidly.
  </para><para>
Cutter supports not only easy test writing but also easy
debugging.
  </para></listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 id="cutter-Cutter.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CUT-EXPORT:CAPS" role="macro" condition="since:1.1.2">
<title>CUT_EXPORT</title>
<indexterm zone="CUT-EXPORT:CAPS" role="1.1.2"><primary>CUT_EXPORT</primary></indexterm>
<programlisting>#  define CUT_EXPORT __declspec(dllexport)
</programlisting>
<para>
Marks a function as a exported function. This is needed
for just Windows environment. If you want to run your
tests on Windows, you need to use this. Otherwise, you
don't need to use this.
</para>
<para>
e.g.:
<informalexample><programlisting>
CUT_EXPORT void
test_add (void)
{
  ...
}
</programlisting></informalexample>
</para><para role="since">Since 1.1.2</para></refsect2>
<refsect2 id="cut-add-data" role="macro" condition="since:1.0.3">
<title>cut_add_data()</title>
<indexterm zone="cut-add-data" role="1.0.3"><primary>cut_add_data</primary></indexterm>
<programlisting>#define             cut_add_data(first_data_name, ...)</programlisting>
<para>
Adds data to use data driven test.
</para>
<para>
e.g.:
<informalexample><programlisting>
#include &lt;cutter.h&gt;

void data_translate (void);
void test_translate (const void *data);

static const char*
translate (int input)
{
   switch(input) {
   case 1:
       return "first";
   case 111:
       return "a hundred eleven";
   default:
       return "unsupported";
   }
}

typedef struct _TranslateTestData
{
    char *translated;
    int input;
} TranslateTestData;

static TranslateTestData *
translate_test_data_new (char *translated, int input)
{
    TranslateTestData *data;

    data = malloc(sizeof(TranslateTestData));
    data->translated = strdup(translated);
    data->input = input;

    return data;
}

static void
translate_test_data_free (TranslateTestData *data)
{
    free(data->translated);
    free(data);
}

void
data_translate(void)
{
    cut_add_data("simple data",
                 translate_test_data_new("first", 1),
                 translate_test_data_free,
                 "complex data",
                 translate_test_data_new("a hundred eleven", 111),
                 translate_test_data_free,
                 NULL);
}

void
test_translate(const void *data)
{
     const TranslateTestData *test_data = data;

     cut_assert_equal_string(test_data->translated,
                             translate(test_data->input));
}
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>first_data_name</parameter>&#160;:</term>
<listitem><simpara>The first data name.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>The data and destroy function of the first data,
followed optionally by more
name/data/destroy_function(<link linkend="CutDestroyFunction"><type>CutDestroyFunction</type></link>)
triples. The variable arguments should be terminated
by <link linkend="NULL:CAPS"><literal>NULL</literal></link> since 1.0.6.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="cut-add-data-backward-compatibility" role="macro" condition="deprecated:">
<title>cut_add_data_backward_compatibility()</title>
<indexterm zone="cut-add-data-backward-compatibility" role="deprecated"><primary>cut_add_data_backward_compatibility</primary></indexterm>
<programlisting>#define             cut_add_data_backward_compatibility(context, ...)</programlisting>
<warning><para><literal>cut_add_data_backward_compatibility</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
</para></refsect2>
<refsect2 id="cut-get-current-test-context" role="function" condition="since:1.0.4">
<title>cut_get_current_test_context ()</title>
<indexterm zone="cut-get-current-test-context" role="1.0.4"><primary>cut_get_current_test_context</primary></indexterm>
<programlisting><link linkend="CutTestContext"><returnvalue>CutTestContext</returnvalue></link> *    cut_get_current_test_context        (<parameter><type>void</type></parameter>);</programlisting>
<para>
Returns the current test context. The current test
context is a thread local object. It means that you don't
need to care this if you don't create a new thread in your
test. This is only needed to care if you create a new
thread. You need to pass the current test context in your
test thread to the current test context in a created
thread.
</para>
<para>
e.g.:
<informalexample><programlisting>
int
your_thread_function(void *data)
{
    CutTestContext *test_context = data;
    cut_set_current_test_context(test_context);
    ...
}

void
run_your_thread(void)
{
    int result;
    pthread_t your_thread;

    result = pthread_create(&amp;your_thread, NULL,
                            your_thread_function,
                            cut_get_current_test_context());
    ...
}
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="CutTestContext"><type>CutTestContext</type></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.4</para></refsect2>
<refsect2 id="cut-keep-message" role="function" condition="deprecated:1.1.0: Use cut_message() instead.|since:1.0.6">
<title>cut_keep_message ()</title>
<indexterm zone="cut-keep-message" role="deprecated"><primary>cut_keep_message</primary></indexterm><indexterm zone="cut-keep-message" role="1.0.6"><primary>cut_keep_message</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_keep_message                    (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>cut_keep_message</literal> has been deprecated since version 1.1.0 and should not be used in newly-written code. Use <link linkend="cut-message"><function>cut_message()</function></link> instead.</para></warning>
<para>
Keeps the current message set by <link linkend="cut-set-message"><function>cut_set_message()</function></link> or
<link linkend="cut-set-message-va-list"><function>cut_set_message_va_list()</function></link> after the next assertion.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-message" role="function" condition="since:1.1.0">
<title>cut_message ()</title>
<indexterm zone="cut-message" role="1.1.0"><primary>cut_message</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_message                         (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Specifies optional assertion message.
</para>
<para>
e.g.:
<informalexample><programlisting>
cut_assert_equal_string("abc", "def",
                        cut_message("should fail!"));
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to insert into the format string.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.0</para></refsect2>
<refsect2 id="cut-set-attributes" role="function" condition="since:1.0.4">
<title>cut_set_attributes ()</title>
<indexterm zone="cut-set-attributes" role="1.0.4"><primary>cut_set_attributes</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_set_attributes                  (<parameter>const <link linkend="char"><type>char</type></link> *first_attribute_name</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Sets attributes of the test.
</para>
<para>
e.g.:
<informalexample><programlisting>
#include &lt;cutter.h&gt;

void attributes_repeat (void);
void test_repeat (void);

void
attributes_repeat(void)
{
    cut_set_attributes("description", "a test for repeat function",
                       "bug", "111",
                       "priority", "high",
                       NULL);
}

void
test_repeat(void)
{
     cut_assert_equal_string_with_free("XXX", repeat("X", 3));
}
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>first_attribute_name</parameter>&#160;:</term>
<listitem><simpara>The first attribute name.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>The value of the first attribute, followed
optionally by more name/value pairs.
<link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminate is required since 1.0.7.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.4</para></refsect2>
<refsect2 id="cut-set-current-test-context" role="function" condition="since:1.0.4">
<title>cut_set_current_test_context ()</title>
<indexterm zone="cut-set-current-test-context" role="1.0.4"><primary>cut_set_current_test_context</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_set_current_test_context        (<parameter><link linkend="CutTestContext"><type>CutTestContext</type></link> *test_context</parameter>);</programlisting>
<para>
Set <parameter>test_context</parameter> as the current test context. See
<link linkend="cut-get-current-test-context"><function>cut_get_current_test_context()</function></link> for more details.
</para><variablelist role="params">
<varlistentry><term><parameter>test_context</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="CutTestContext"><type>CutTestContext</type></link> to be the current test
context.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.4</para></refsect2>
<refsect2 id="cut-set-message" role="function" condition="deprecated:1.1.0: Use cut_message() instead.|since:1.0.6">
<title>cut_set_message ()</title>
<indexterm zone="cut-set-message" role="deprecated"><primary>cut_set_message</primary></indexterm><indexterm zone="cut-set-message" role="1.0.6"><primary>cut_set_message</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_set_message                     (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<warning><para><literal>cut_set_message</literal> has been deprecated since version 1.1.0 and should not be used in newly-written code. Use <link linkend="cut-message"><function>cut_message()</function></link> instead.</para></warning>
<para>
Sets a message to be used by the next assertion.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>the parameters to insert into the format string.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-set-message-va-list" role="function" condition="deprecated:1.1.0: Use cut_message() instead.|since:1.0.6">
<title>cut_set_message_va_list ()</title>
<indexterm zone="cut-set-message-va-list" role="deprecated"><primary>cut_set_message_va_list</primary></indexterm><indexterm zone="cut-set-message-va-list" role="1.0.6"><primary>cut_set_message_va_list</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_set_message_va_list             (<parameter>const <link linkend="char"><type>char</type></link> *format</parameter>,
                                                         <parameter><link linkend="va-list"><type>va_list</type></link> args</parameter>);</programlisting>
<warning><para><literal>cut_set_message_va_list</literal> has been deprecated since version 1.1.0 and should not be used in newly-written code. Use <link linkend="cut-message"><function>cut_message()</function></link> instead.</para></warning>
<para>
Sets a message to be used by the next assertion.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>the message format. See the <link linkend="printf"><function>printf()</function></link> documentation.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>args</parameter>&#160;:</term>
<listitem><simpara>the parameters to insert into the format string.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-setup" role="function" condition="since:1.0.6">
<title>cut_setup ()</title>
<indexterm zone="cut-setup" role="1.0.6"><primary>cut_setup</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_setup                           (<parameter><type>void</type></parameter>);</programlisting>
<para>
If you define <link linkend="cut-setup"><function>cut_setup()</function></link> in your test program, cutter
will call your <link linkend="cut-setup"><function>cut_setup()</function></link> before each your test is
run. <link linkend="cut-setup"><function>cut_setup()</function></link> has priority over <link linkend="setup"><function>setup()</function></link>.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-shutdown" role="function" condition="since:1.0.6">
<title>cut_shutdown ()</title>
<indexterm zone="cut-shutdown" role="1.0.6"><primary>cut_shutdown</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_shutdown                        (<parameter><type>void</type></parameter>);</programlisting>
<para>
If you define <link linkend="shutdown"><function>shutdown()</function></link> in your test program, cutter
will call your <link linkend="shutdown"><function>shutdown()</function></link> after each your test case is
run.  <link linkend="cut-shutdown"><function>cut_shutdown()</function></link> has priority over <link linkend="shutdown"><function>shutdown()</function></link>.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-startup" role="function" condition="since:1.0.6">
<title>cut_startup ()</title>
<indexterm zone="cut-startup" role="1.0.6"><primary>cut_startup</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_startup                         (<parameter><type>void</type></parameter>);</programlisting>
<para>
If you define <link linkend="cut-startup"><function>cut_startup()</function></link> in your test program, cutter
will call your <link linkend="cut-startup"><function>cut_startup()</function></link> before each your test case
is run. <link linkend="cut-startup"><function>cut_startup()</function></link> has priority over <link linkend="startup"><function>startup()</function></link>.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-teardown" role="function" condition="since:1.0.6">
<title>cut_teardown ()</title>
<indexterm zone="cut-teardown" role="1.0.6"><primary>cut_teardown</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_teardown                        (<parameter><type>void</type></parameter>);</programlisting>
<para>
If you define <link linkend="cut-teardown"><function>cut_teardown()</function></link> in your test program, cutter
will call your <link linkend="cut-teardown"><function>cut_teardown()</function></link> after each your test is run
even if a test is failed. <link linkend="cut-teardown"><function>cut_teardown()</function></link> has priority
over <link linkend="teardown"><function>teardown()</function></link>.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="setup" role="function" condition="deprecated:1.0.7: Use cut_setup() instead.">
<title>setup ()</title>
<indexterm zone="setup" role="deprecated"><primary>setup</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                setup                               (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>setup</literal> has been deprecated since version 1.0.7 and should not be used in newly-written code. Use <link linkend="cut-setup"><function>cut_setup()</function></link> instead.</para></warning>
<para>
If you define <link linkend="setup"><function>setup()</function></link> in your test program, cutter will
call your <link linkend="setup"><function>setup()</function></link> before each your test is run. If you
define <link linkend="cut-setup"><function>cut_setup()</function></link>, <link linkend="setup"><function>setup()</function></link> is ignored.
</para></refsect2>
<refsect2 id="teardown" role="function" condition="deprecated:1.0.7: Use cut_teardown() instead.">
<title>teardown ()</title>
<indexterm zone="teardown" role="deprecated"><primary>teardown</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                teardown                            (<parameter><type>void</type></parameter>);</programlisting>
<warning><para><literal>teardown</literal> has been deprecated since version 1.0.7 and should not be used in newly-written code. Use <link linkend="cut-teardown"><function>cut_teardown()</function></link> instead.</para></warning>
<para>
If you define <link linkend="teardown"><function>teardown()</function></link> in your test program, cutter will
call your <link linkend="teardown"><function>teardown()</function></link> after each your test is run even if
a test is failed. If you define <link linkend="cut-teardown"><function>cut_teardown()</function></link>,
<link linkend="teardown"><function>teardown()</function></link> is ignored.
</para></refsect2>

</refsect1>
<refsect1 id="cutter-Cutter.see-also">
<title>See Also</title>
<link linkend="cutter-Assertions">Assertions</link>
</refsect1>

</refentry>
