<?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-Assertion-writing-helper">
<refmeta>
<refentrytitle role="top_of_page" id="cutter-Assertion-writing-helper.top_of_page">Assertion writing helper</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Assertion writing helper</refname>
<refpurpose>Symbols in this section help you
                    writing your own assertions.</refpurpose>
</refnamediv>

<refsynopsisdiv id="cutter-Assertion-writing-helper.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>#define             <link linkend="CUT-RELATIVE-PATH:CAPS">CUT_RELATIVE_PATH</link>
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-append-diff">cut_append_diff</link>                     (<parameter>const <link linkend="char"><type>char</type></link> *message</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *from</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *to</parameter>);
<link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>         <link linkend="cut-equal-double">cut_equal_double</link>                    (<parameter><link linkend="double"><type>double</type></link> double1</parameter>,
                                                         <parameter><link linkend="double"><type>double</type></link> double2</parameter>,
                                                         <parameter><link linkend="double"><type>double</type></link> error</parameter>);
#define             <link linkend="cut-equal-sockaddr">cut_equal_sockaddr</link>                  (address1,
                                                         address2)
<link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>         <link linkend="cut-equal-string">cut_equal_string</link>                    (<parameter>const <link linkend="char"><type>char</type></link> *string1</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *string2</parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-get-source-directory">cut_get_source_directory</link>            (<parameter><type>void</type></parameter>);
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-get-test-directory">cut_get_test_directory</link>              (<parameter><type>void</type></parameter>);
#define             <link linkend="cut-inspect-sockaddr">cut_inspect_sockaddr</link>                (address)
const <link linkend="char"><returnvalue>char</returnvalue></link> *        <link linkend="cut-inspect-string-array">cut_inspect_string_array</link>            (<parameter>const <link linkend="char"><type>char</type></link> **strings</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-pop-backtrace">cut_pop_backtrace</link>                   (<parameter><type>void</type></parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-push-backtrace">cut_push_backtrace</link>                  (<parameter>const <link linkend="char"><type>char</type></link> *expression</parameter>);
#define             <link linkend="cut-set-actual">cut_set_actual</link>                      (actual)
#define             <link linkend="cut-set-expected">cut_set_expected</link>                    (expected)
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-test-fail">cut_test_fail</link>                       (<parameter>const <link linkend="char"><type>char</type></link> *system_message</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-test-fail-va-list">cut_test_fail_va_list</link>               (<parameter>const <link linkend="char"><type>char</type></link> *system_message</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *user_message_format</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="cut-test-pass">cut_test_pass</link>                       (<parameter><type>void</type></parameter>);
#define             <link linkend="cut-trace">cut_trace</link>                           (expression)
#define             <link linkend="cut-trace-with-info-expression">cut_trace_with_info_expression</link>      (expression,
                                                         info_expression)
</synopsis>
</refsynopsisdiv>

<refsect1 id="cutter-Assertion-writing-helper.description" role="desc">
<title role="desc.title">Description</title>
<para>
You will need to write your own assertions for writing
easy to read test. Symbols in this section help you
writing your own assertions.
</para>
<para>
e.g.:
</para>
<para>
my-assertions.h:
<informalexample><programlisting>
#ifndef __MY_ASSERTIONS_H__
#define __MY_ASSERTIONS_H__

#include &lt;cutter.h&gt;

#ifdef __cplusplus
extern "C" {
#endif

#define my_assert_equal_int(expected, actual)                    \
    cut_trace_with_info_expression(                              \
        my_assert_equal_int_helper((expected), (actual),         \
                                   # expected, # actual),        \
        my_assert_equal_int(expected, actual, __VA_ARGS__))

void my_assert_equal_int_help (long expected,
                               long actual,
                               const char *expression_expected,
                               const char *expression_actual);

#ifdef __cplusplus
}
#endif

#endif
</programlisting></informalexample>
</para>
<para>
my-assertions.c:
<informalexample><programlisting>
#include "my-assertions.h"

void
my_assert_equal_int_helper (long expected,
                            long actual,
                            const char *expression_expected,
                            const char *expression_actual)
{
    if (expected == actual) {
        cut_test_pass();
    } else {
        cut_test_fail(cut_take_printf("&lt;%s == %s>\n"
                                      "expected: &lt;%ld>\n"
                                      "  actual: &lt;%ld>",
                                      expression_expected,
                                      expression_actual,
                                      expected, actual));
    }
}
</programlisting></informalexample>
</para>
<para>
Makefile.am:
<informalexample><programlisting>
AM_CFLAGS = $(CUTTER_CFLAGS)
LIBS = $(CUTTER_LIBS)
noinst_LTLIBRARIES = libmy-assertions.la
libmy_assertions_la_SOURCES = my-assertions.c my-assertions.h
AM_LDFLAGS = -module -rpath $(libdir) -avoid-version -no-undefined
</programlisting></informalexample>
</para>
</refsect1>
<refsect1 id="cutter-Assertion-writing-helper.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CUT-RELATIVE-PATH:CAPS" role="macro" condition="since:1.0.6">
<title>CUT_RELATIVE_PATH</title>
<indexterm zone="CUT-RELATIVE-PATH:CAPS" role="1.0.6"><primary>CUT_RELATIVE_PATH</primary></indexterm>
<programlisting>#  define CUT_RELATIVE_PATH NULL
</programlisting>
<para>
Define this macro in a source code or build option
(e.g. -DCUT_RELATIVE_PATH=\""sub/dir/"\") if the source
code is built as shared library and used it as helper
library of your test. If this path isn't set, you can't
get correct path from <link linkend="cut-trace"><function>cut_trace()</function></link> and
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>.
</para>
<para>
Here is an example structure for explain:
</para>
<para>
<informalexample><programlisting>
--- core-lib/ --- XXX.c # Your core library
 |             +- ...
 |             +- YYY.c
 +- util-lib/ --- AAA.c # Your utility library
 |             +- ...
 |             +- BBB.c
 |
 +- test/ --- core/ --- test-XXX.c # Tests for your core library
           |         +- ...
           |         +- test-YYY.c
           +- util/ --- test-AAA.c # Tests for your utility library
           |         +- ...
           |         +- test-BBB.c
           +- lib/  --- my-assertions.c # Your library of tests.
                     +- my-assertions.h # This library will be used
                     |                  # as shared library of your
                     |                  # tests (test/core/test-*.so
                     |                  # and test/util/test-*.so)
                     +- ...

  % cutter --source-directory=test test
</programlisting></informalexample>
</para>
<para>
In the above example structure, you need to define
<link linkend="CUT-RELATIVE-PATH:CAPS"><literal>CUT_RELATIVE_PATH</literal></link> as "lib" in test/lib/my-assertions.c
because my-assertions.c is in lib/ directory from source
directory "test" specified by command line option
--source-directory.
</para>
<para>
Here are example code and build option:
</para>
<para>
<informalexample><programlisting>
test/lib/my-assertions.c:
  #define CUT_RELATIVE_PATH "lib"
  #include &lt;cutter.h&gt;

build option:
  % gcc -DCUT_RELATIVE_PATH="\"lib\"" ...
</programlisting></informalexample>
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-append-diff" role="function" condition="deprecated|since:1.0.3">
<title>cut_append_diff ()</title>
<indexterm zone="cut-append-diff" role="deprecated"><primary>cut_append_diff</primary></indexterm><indexterm zone="cut-append-diff" role="1.0.3"><primary>cut_append_diff</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_append_diff                     (<parameter>const <link linkend="char"><type>char</type></link> *message</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *from</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *to</parameter>);</programlisting>
<warning><para><literal>cut_append_diff</literal> has been deprecated since version 1.0.9 and should not be used in newly-written code. Use <link linkend="cut-set-expected"><function>cut_set_expected()</function></link> and
<link linkend="cut-set-actual"><function>cut_set_actual()</function></link> instead.</para></warning>
<para>
Computes diff between <parameter>from</parameter> and <parameter>to</parameter> and append the diff
to <parameter>message</parameter>. Returned string is owned by Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter>&#160;:</term>
<listitem><simpara>the string to be appended diff.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>from</parameter>&#160;:</term>
<listitem><simpara>the original string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>to</parameter>&#160;:</term>
<listitem><simpara>the modified string.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><parameter>message</parameter> with diff between <parameter>from</parameter> and <parameter>to</parameter> or same
as <parameter>message</parameter> if the diff not interested. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.3</para></refsect2>
<refsect2 id="cut-equal-double" role="function" condition="since:1.0.5">
<title>cut_equal_double ()</title>
<indexterm zone="cut-equal-double" role="1.0.5"><primary>cut_equal_double</primary></indexterm>
<programlisting><link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>         cut_equal_double                    (<parameter><link linkend="double"><type>double</type></link> double1</parameter>,
                                                         <parameter><link linkend="double"><type>double</type></link> double2</parameter>,
                                                         <parameter><link linkend="double"><type>double</type></link> error</parameter>);</programlisting>
<para>
Compare <parameter>double1</parameter> to <parameter>double2</parameter> with <parameter>error</parameter> range.
</para><variablelist role="params">
<varlistentry><term><parameter>double1</parameter>&#160;:</term>
<listitem><simpara>a double value.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>double2</parameter>&#160;:</term>
<listitem><simpara>a double value.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara>a double value that specifies error range.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link> if |<parameter>double1</parameter> - <parameter>double2</parameter>| &lt;= <parameter>error</parameter>;
<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link> otherwise.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-equal-sockaddr" role="macro" condition="since:1.1.1">
<title>cut_equal_sockaddr()</title>
<indexterm zone="cut-equal-sockaddr" role="1.1.1"><primary>cut_equal_sockaddr</primary></indexterm>
<programlisting>#define cut_equal_sockaddr(address1, address2) CUT_FALSE
</programlisting>
<para>
Compare <parameter>address1</parameter> to <parameter>address2</parameter>.
</para>
<para>
This function can be disabled by defining CUT_DISABLE_SOCKET_SUPPORT.
</para><variablelist role="params">
<varlistentry><term><parameter>address1</parameter>&#160;:</term>
<listitem><simpara>a socket address.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>address2</parameter>&#160;:</term>
<listitem><simpara>a socket address.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link> if <parameter>address1</parameter> == <parameter>address2</parameter>,
<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link> otherwise.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="cut-equal-string" role="function" condition="since:1.0.5">
<title>cut_equal_string ()</title>
<indexterm zone="cut-equal-string" role="1.0.5"><primary>cut_equal_string</primary></indexterm>
<programlisting><link linkend="cut-boolean"><returnvalue>cut_boolean</returnvalue></link>         cut_equal_string                    (<parameter>const <link linkend="char"><type>char</type></link> *string1</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *string2</parameter>);</programlisting>
<para>
Compare <parameter>string1</parameter> to <parameter>string2</parameter>. <parameter>string1</parameter> and/or <parameter>string2</parameter>
maybe <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>string1</parameter>&#160;:</term>
<listitem><simpara>a string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string2</parameter>&#160;:</term>
<listitem><simpara>a string.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara><link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link> if both <parameter>string1</parameter> and <parameter>string2</parameter> are <link linkend="NULL:CAPS"><literal>NULL</literal></link> or
have the same contents; <link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link> otherwise.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-get-source-directory" role="function" condition="since:1.1.5">
<title>cut_get_source_directory ()</title>
<indexterm zone="cut-get-source-directory" role="1.1.5"><primary>cut_get_source_directory</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_get_source_directory            (<parameter><type>void</type></parameter>);</programlisting>
<para>
Gets the source directory name which is specified by command line.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a string owned by Cutter that must not be modified or freed.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.5</para></refsect2>
<refsect2 id="cut-get-test-directory" role="function" condition="since:1.1.4">
<title>cut_get_test_directory ()</title>
<indexterm zone="cut-get-test-directory" role="1.1.4"><primary>cut_get_test_directory</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_get_test_directory              (<parameter><type>void</type></parameter>);</programlisting>
<para>
Gets the test directory name which is specified by command line.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a string owned by Cutter that must not be modified or freed.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.4</para></refsect2>
<refsect2 id="cut-inspect-sockaddr" role="macro" condition="since:1.1.1">
<title>cut_inspect_sockaddr()</title>
<indexterm zone="cut-inspect-sockaddr" role="1.1.1"><primary>cut_inspect_sockaddr</primary></indexterm>
<programlisting>#define             cut_inspect_sockaddr(address)</programlisting>
<para>
Formats <parameter>address</parameter> as human readable string that is owned
by Cutter.
</para>
<para>
This function can be disabled by defining CUT_DISABLE_SOCKET_SUPPORT.
</para><variablelist role="params">
<varlistentry><term><parameter>address</parameter>&#160;:</term>
<listitem><simpara>the socket address to be inspected.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a inspected socket address owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.1.1</para></refsect2>
<refsect2 id="cut-inspect-string-array" role="function">
<title>cut_inspect_string_array ()</title>
<indexterm zone="cut-inspect-string-array"><primary>cut_inspect_string_array</primary></indexterm>
<programlisting>const <link linkend="char"><returnvalue>char</returnvalue></link> *        cut_inspect_string_array            (<parameter>const <link linkend="char"><type>char</type></link> **strings</parameter>);</programlisting>
<para>
Formats <parameter>strings</parameter> as human readable string that is owned by Cutter.
</para><variablelist role="params">
<varlistentry><term><parameter>strings</parameter>&#160;:</term>
<listitem><simpara>the array of strings to be inspected.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a inspected string owned by Cutter. Don't free it.</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="cut-pop-backtrace" role="function" condition="since:1.0.6">
<title>cut_pop_backtrace ()</title>
<indexterm zone="cut-pop-backtrace" role="1.0.6"><primary>cut_pop_backtrace</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_pop_backtrace                   (<parameter><type>void</type></parameter>);</programlisting>
<para>
Pops a backtrace from the backtrace stack.
</para>
<para>
Normally, you don't need to use it directory. <link linkend="cut-trace"><function>cut_trace()</function></link>
is enough.
</para><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-push-backtrace" role="function" condition="since:1.0.6">
<title>cut_push_backtrace ()</title>
<indexterm zone="cut-push-backtrace" role="1.0.6"><primary>cut_push_backtrace</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_push_backtrace                  (<parameter>const <link linkend="char"><type>char</type></link> *expression</parameter>);</programlisting>
<para>
Pushes <parameter>expression</parameter> and the current source place to the
backtrace stack.
</para>
<para>
Normally, you don't need to use it directory. <link linkend="cut-trace"><function>cut_trace()</function></link>
is enough.
</para><variablelist role="params">
<varlistentry><term><parameter>expression</parameter>&#160;:</term>
<listitem><simpara>an expression to be traced.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.6</para></refsect2>
<refsect2 id="cut-set-actual" role="macro" condition="since:1.0.9">
<title>cut_set_actual()</title>
<indexterm zone="cut-set-actual" role="1.0.9"><primary>cut_set_actual</primary></indexterm>
<programlisting>#define             cut_set_actual(actual)</programlisting>
<para>
Sets an inspected actual object to be used by the next
assertion.
</para>
<para>
If both of expected and actual object are set and diff of
them is needed, the diff is generated automatically.
</para>
<para>
See also <link linkend="cut-set-expected"><function>cut_set_expected()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>actual</parameter>&#160;:</term>
<listitem><simpara>the inspected actual object.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.9</para></refsect2>
<refsect2 id="cut-set-expected" role="macro" condition="since:1.0.9">
<title>cut_set_expected()</title>
<indexterm zone="cut-set-expected" role="1.0.9"><primary>cut_set_expected</primary></indexterm>
<programlisting>#define             cut_set_expected(expected)</programlisting>
<para>
Sets an inspected expected object to be used by the next
assertion.
</para>
<para>
If both of expected and actual object are set and diff of
them is needed, the diff is generated automatically.
</para>
<para>
See also <link linkend="cut-set-actual"><function>cut_set_actual()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>expected</parameter>&#160;:</term>
<listitem><simpara>the inspected expected object.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.9</para></refsect2>
<refsect2 id="cut-test-fail" role="function" condition="since:1.0.5">
<title>cut_test_fail ()</title>
<indexterm zone="cut-test-fail" role="1.0.5"><primary>cut_test_fail</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_test_fail                       (<parameter>const <link linkend="char"><type>char</type></link> *system_message</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Call <link linkend="cut-test-fail"><function>cut_test_fail()</function></link> if an assertion is failed.
<link linkend="cut-test-fail"><function>cut_test_fail()</function></link> counts up n-failures and terminate the
current test.
</para><variablelist role="params">
<varlistentry><term><parameter>system_message</parameter>&#160;:</term>
<listitem><simpara>a failure message from testing system.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>optional format string, followed by parameters to insert
into the format string. (as with <link linkend="printf"><function>printf()</function></link>) This is
deprecated since 0.1.6. Use <link linkend="cut-set-message"><function>cut_set_message()</function></link> instead.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-test-fail-va-list" role="function" condition="deprecated:1.0.6: Use cut_test_fail() instead.|since:1.0.5">
<title>cut_test_fail_va_list ()</title>
<indexterm zone="cut-test-fail-va-list" role="deprecated"><primary>cut_test_fail_va_list</primary></indexterm><indexterm zone="cut-test-fail-va-list" role="1.0.5"><primary>cut_test_fail_va_list</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_test_fail_va_list               (<parameter>const <link linkend="char"><type>char</type></link> *system_message</parameter>,
                                                         <parameter>const <link linkend="char"><type>char</type></link> *user_message_format</parameter>);</programlisting>
<warning><para><literal>cut_test_fail_va_list</literal> has been deprecated since version 1.0.6 and should not be used in newly-written code. Use <link linkend="cut-test-fail"><function>cut_test_fail()</function></link> instead.</para></warning>
<para>
See <link linkend="cut-test-fail"><function>cut_test_fail()</function></link> for <link linkend="cut-test-fail-va-list"><function>cut_test_fail_va_list()</function></link>'s
behavior. <parameter>user_message_format</parameter> is the prior variable of
variable length arguments.
</para>
<para>
e.g.:
<informalexample><programlisting>
void
my_assert(cut_boolean result,
          const gchar *user_message_format,
          ...)
{
    if (result) {
        cut_test_pass();
    } else {
        cut_test_fail_va_list("Fail!", user_message_format);
    }
}
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>system_message</parameter>&#160;:</term>
<listitem><simpara>a failure message from testing
system.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_message_format</parameter>&#160;:</term>
<listitem><simpara>a failure message from user.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-test-pass" role="function" condition="since:1.0.5">
<title>cut_test_pass ()</title>
<indexterm zone="cut-test-pass" role="1.0.5"><primary>cut_test_pass</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                cut_test_pass                       (<parameter><type>void</type></parameter>);</programlisting>
<para>
Call <link linkend="cut-test-pass"><function>cut_test_pass()</function></link> if an assertion is
passed. <link linkend="cut-test-pass"><function>cut_test_pass()</function></link> counts up n-assertions.
</para><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-trace" role="macro" condition="since:1.0.5">
<title>cut_trace()</title>
<indexterm zone="cut-trace" role="1.0.5"><primary>cut_trace</primary></indexterm>
<programlisting>#define             cut_trace(expression)</programlisting>
<para>
Mark the current file, line, function and <parameter>expression</parameter> and
show it when assertion is failed in
<parameter>expression</parameter>. Most of <parameter>expression</parameter> will be function call.
</para>
<para>
Note that you can't get return value of <parameter>expression</parameter>.
</para>
<para>
Here is an example of <link linkend="cut-trace"><function>cut_trace()</function></link>. If
cut_assert_not_null(object) is failed, you will get a
backtrace that contains two line;
cut_assert_not_null(object) and create_my_object("my-name").
</para>
<para>
e.g.:
<informalexample><programlisting>
static MyObject *object;

static void
create_my_object(const char *name)
{
    object = my_object_new(name);
    cut_assert_not_null(object);
}

void
test_my_object_name(void)
{
    cut_trace(create_my_object("my-name"));
    cut_assert_equal_string("my-name",
                            my_object_get_name(object));
}
</programlisting></informalexample>
</para>
<para>
You will use <link linkend="cut-trace"><function>cut_trace()</function></link> with macro for test readability:
<informalexample><programlisting>
static MyObject *object;

static void
create_my_object_helper(const char *name)
{
    object = my_object_new(name);
    cut_assert_not_null(object);
}

#define create_my_object(...)                        \
    cut_trace(create_my_object_helper(__VA_ARGS__))

void
test_my_object_name(void)
{
    create_my_object("my-name");
    cut_assert_equal_string("my-name",
                            my_object_get_name(object));
}
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>expression</parameter>&#160;:</term>
<listitem><simpara>an expression to be traced.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>
<refsect2 id="cut-trace-with-info-expression" role="macro" condition="since:1.0.5">
<title>cut_trace_with_info_expression()</title>
<indexterm zone="cut-trace-with-info-expression" role="1.0.5"><primary>cut_trace_with_info_expression</primary></indexterm>
<programlisting>#define             cut_trace_with_info_expression(expression, info_expression)</programlisting>
<para>
It's difference between <link linkend="cut-trace"><function>cut_trace()</function></link> and
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link> that traced expression
is the same expression as <parameter>expression</parameter> or
not. <link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link> is useful when you
want to hide some information in <parameter>expression</parameter> for
backtrace readability.
</para>
<para>
Here is an example of
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>. If
cut_assert_not_null(object) is failed, you will get a
backtrace that contains two line:
<itemizedlist>
  <listitem><para>cut_assert_not_null(object)</para></listitem>
  <listitem><para>create_my_object("my-name") not
create_my_object_helper("my-name")</para></listitem>
</itemizedlist>
If you use <link linkend="cut-trace"><function>cut_trace()</function></link> instead of
<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>, you will get
create_my_object_helper("my-name"). You may be confused
about 'Where is create_my_object_helper("my-name") from?
<link linkend="test-my-object-name"><function>test_my_object_name()</function></link> uses create_my_object("my-name")
but does not use create_my_object_helper("my-name").'.
</para>
<para>
e.g.:
<informalexample><programlisting>
static MyObject *object;

static void
create_my_object_helper(const char *name)
{
    object = my_object_new(name);
    cut_assert_not_null(object);
}

#define create_my_object(...)                        \
    cut_trace_with_info_expression(                  \
        create_my_object_helper(__VA_ARGS__),        \
        create_my_object(__VA_ARGS__))

void
test_my_object_name(void)
{
    create_my_object("my-name");
    cut_assert_equal_string("my-name",
                            my_object_get_name(object));
}
</programlisting></informalexample>
</para><variablelist role="params">
<varlistentry><term><parameter>expression</parameter>&#160;:</term>
<listitem><simpara>an expression to be traced.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>info_expression</parameter>&#160;:</term>
<listitem><simpara>a traced expression.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.5</para></refsect2>

</refsect1>

</refentry>
