<?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">検証作成の補助</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Cutterライブラリ</refmiscinfo>
</refmeta>
<refnamediv>
<refname>検証作成の補助</refname>
<refpurpose>このセクションにあるシンボルは独自検証を作成することを補助します。</refpurpose>
</refnamediv>

<refsynopsisdiv id="cutter-Assertion-writing-helper.synopsis" role="synopsis">
<title role="synopsis.title">概要</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">説明</title>
<para>読みやすいテストを書くために独自の検証を作成する必要があるでしょう。このセクションのシンボルは独自の検証作成を補助します。</para>
<para>例:</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&gt;\n"
                                      "expected: &lt;%ld&gt;\n"
                                      "  actual: &lt;%ld&gt;",
                                      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">詳細</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>もし、テスト用の補助ライブラリを共有ライブラリとして使っている場合は、補助ライブラリのソースコード中またはビルドオプション（例: -DCUT_RELATIVE_PATH=\""sub/dir/"\"）でこのマクロを定義してください。もし、このパスが設定されていない場合は<link linkend="cut-trace"><function>cut_trace()</function></link>と<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>で正しいパスが得られません。</para>
<para>説明用のディレクト構成例です。</para>
<para>
<informalexample><programlisting>
--- core-lib/ --- XXX.c # コアライブラリ
 |             +- ...
 |             +- YYY.c
 +- util-lib/ --- AAA.c # 便利ライブラリ
 |             +- ...
 |             +- BBB.c
 |
 +- test/ --- core/ --- test-XXX.c # コアライブラリのテスト
           |         +- ...
           |         +- test-YYY.c
           +- util/ --- test-AAA.c # 便利ライブラリのテスト
           |         +- ...
           |         +- test-BBB.c
           +- lib/  --- my-assertions.c # テスト用補助ライブラリ
                     +- my-assertions.h # テスト中（
                     |                  # test/core/test-*.soと
                     |                  # test/util/test-*.soの中）
                     |                  # で共有ライブラリとして使われる
                     +- ...

  % cutter --source-directory=test test
</programlisting></informalexample>
</para>
<para>上記の構成例では、test/lib/my-assertions.cでは<link linkend="CUT-RELATIVE-PATH:CAPS"><literal>CUT_RELATIVE_PATH</literal></link>を"lib"と定義しなければいけません。これは、:source-directoryコマンドラインオプションで指定した"test"ソースディレクトリからみてlib/ディレクトリにmy-assertions.cがあるからです。</para>
<para>コードとビルドオプションの例です。</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">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>はバージョン1.0.9から非推奨になりました。新しく書くコードでは使わないでください。代わりに<link linkend="cut-set-expected"><function>cut_set_expected()</function></link>と<link linkend="cut-set-actual"><function>cut_set_actual()</function></link>を使ってください。</para></warning>
<para><parameter>from</parameter>と<parameter>to</parameter>のdiffを計算し、そのdiffを<parameter>message</parameter>に追加します。戻り値の文字列の所有者はCutterです。</para><variablelist role="params">
<varlistentry><term><parameter>message</parameter> :</term>
<listitem><simpara>diffが追加される文字列。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>from</parameter> :</term>
<listitem><simpara>元の文字列。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>to</parameter> :</term>
<listitem><simpara>修正された文字列。</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara><parameter>from</parameter>と<parameter>to</parameter>間のdiff付きの<parameter>message</parameter>。必要なさそうなdiffであれば<parameter>message</parameter>と同じ。開放しないでください。</simpara></listitem></varlistentry>
</variablelist><para role="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><parameter>double1</parameter>と<parameter>double2</parameter>を誤差範囲<parameter>error</parameter>で比較します。</para><variablelist role="params">
<varlistentry><term><parameter>double1</parameter> :</term>
<listitem><simpara>浮動小数点値。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>double2</parameter> :</term>
<listitem><simpara>浮動小数点値。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter> :</term>
<listitem><simpara>誤差範囲を示す浮動小数点数。</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara>|<parameter>double1</parameter> - <parameter>double2</parameter>| &lt;= <parameter>error</parameter>なら<link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link>、そうでなければ<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link>。</simpara></listitem></varlistentry>
</variablelist><para role="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><parameter>address1</parameter>と<parameter>address2</parameter>を比較します。</para>
<para>この関数はCUT_DISABLE_SOCKET_SUPPORTを定義すると無効にできます。</para><variablelist role="params">
<varlistentry><term><parameter>address1</parameter> :</term>
<listitem><simpara>ソケットアドレス。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>address2</parameter> :</term>
<listitem><simpara>ソケットアドレス。</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara><parameter>sub_process</parameter>が異常終了したときは<link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link>、そうでない場合は<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link>。</simpara></listitem></varlistentry>
</variablelist><para role="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><parameter>string1</parameter>と<parameter>string2</parameter>を比較します。<parameter>string1</parameter>あるいは<parameter>string2</parameter>、または両方が<link linkend="NULL:CAPS"><literal>NULL</literal></link>でもかまいません。</para><variablelist role="params">
<varlistentry><term><parameter>string1</parameter> :</term>
<listitem><simpara>文字列。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>string2</parameter> :</term>
<listitem><simpara>文字列。</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara><parameter>string1</parameter>と<parameter>string2</parameter>が両方<link linkend="NULL:CAPS"><literal>NULL</literal></link>、あるいは同じ内容の場合は<link linkend="CUT-TRUE:CAPS"><literal>CUT_TRUE</literal></link>、そうでない場合は<link linkend="CUT-FALSE:CAPS"><literal>CUT_FALSE</literal></link>。</simpara></listitem></varlistentry>
</variablelist><para role="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>コマンドラインで指定されたソースディレクトリ名を返します。</para><variablelist role="params">
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara>Cutterが所有する文字列。解放しないで下さい。</simpara></listitem></varlistentry>
</variablelist><para role="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>コマンドラインで指定されたテストディレクトリ名を返します。</para><variablelist role="params">
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara>Cutterが所有する文字列。解放しないで下さい。</simpara></listitem></varlistentry>
</variablelist><para role="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><parameter>address</parameter>を人が読みやすい文字列に整形します。整形された文字列の所有者はCutterです。</para>
<para>この関数はCUT_DISABLE_SOCKET_SUPPORTを定義すると無効にできます。</para><variablelist role="params">
<varlistentry><term><parameter>address</parameter> :</term>
<listitem><simpara>詳細化されるソケットアドレス。</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara>Cutterが所有する整形されたソケットアドレス。解放しないで下さい。</simpara></listitem></varlistentry>
</variablelist><para role="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><parameter>strings</parameter>を人が読みやすい文字列に整形します。整形された文字列の所有者はCutterです。</para><variablelist role="params">
<varlistentry><term><parameter>strings</parameter> :</term>
<listitem><simpara>整形される文字列の配列。</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>戻り値</emphasis> :</term><listitem><simpara>Cutterが所有する整形された文字列。解放しないで下さい。</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>バックトレーススタックからバックトレースをポップします。</para>
<para>通常は直接使う必要はありません。<link linkend="cut-trace"><function>cut_trace()</function></link>で十分です。</para><para role="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><parameter>expression</parameter>と現在のソースの場所をバックトレーススタックにプッシュします。</para>
<para>通常は直接使う必要はありません。<link linkend="cut-trace"><function>cut_trace()</function></link>で十分です。</para><variablelist role="params">
<varlistentry><term><parameter>expression</parameter> :</term>
<listitem><simpara>呼び出されたことを記録される式。</simpara></listitem></varlistentry>
</variablelist><para role="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>次の検証で使う詳細化した実際値オブジェクトを設定します。</para>
<para>期待値オブジェクトと実際値オブジェクトの両方が設定され、それらのdiffが必要な場合は自動的にdiffを生成します。</para>
<para><link linkend="cut-set-expected"><function>cut_set_expected()</function></link>も見てください。</para><variablelist role="params">
<varlistentry><term><parameter>actual</parameter> :</term>
<listitem><simpara>実測値オブジェクトの詳細。</simpara></listitem></varlistentry>
</variablelist><para role="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>次の検証で使う詳細化した期待値オブジェクトを設定します。</para>
<para>期待値オブジェクトと実際値オブジェクトの両方が設定され、それらのdiffが必要な場合は自動的にdiffを生成します。</para>
<para><link linkend="cut-set-actual"><function>cut_set_actual()</function></link>も見てください。</para><variablelist role="params">
<varlistentry><term><parameter>expected</parameter> :</term>
<listitem><simpara>期待値オブジェクトの詳細。</simpara></listitem></varlistentry>
</variablelist><para role="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>検証が失敗したら<link linkend="cut-test-fail"><function>cut_test_fail()</function></link>を呼んでください。<link linkend="cut-test-fail"><function>cut_test_fail()</function></link>は失敗数を増やし、現在のテストを中断します。</para><variablelist role="params">
<varlistentry><term><parameter>system_message</parameter> :</term>
<listitem><simpara>テストフレームワーク指定の失敗メッセージ。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter> :</term>
<listitem><simpara>省略可能な整形文字列。以降のパラメータが整形文字列に挿入されます。（<link linkend="printf"><function>printf()</function></link>と同じ。）このパラメータは0.1.6から非推奨となっています。代わりに<link linkend="cut-set-message"><function>cut_set_message()</function></link>を使ってください。</simpara></listitem></varlistentry>
</variablelist><para role="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>はバージョン1.0.6から非推奨になりました。新しく書くコードでは使わないで下さい。代わりに<link linkend="cut-test-fail"><function>cut_test_fail()</function></link>を使ってください。</para></warning>
<para><link linkend="cut-test-fail-va-list"><function>cut_test_fail_va_list()</function></link>の動作については<link linkend="cut-test-fail"><function>cut_test_fail()</function></link>を見てください。<parameter>user_message_format</parameter>は可変長引数の1つ前の引数です。</para>
<para>例: <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> :</term>
<listitem><simpara>テストフレームワーク指定の失敗メッセージ。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_message_format</parameter> :</term>
<listitem><simpara>ユーザ指定の失敗メッセージ。</simpara></listitem></varlistentry>
</variablelist><para role="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>検証をパスしたら<link linkend="cut-test-pass"><function>cut_test_pass()</function></link>を呼んでください。<link linkend="cut-test-pass"><function>cut_test_pass()</function></link>は検証数を増やします。</para><para role="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>現在のファイル名、行番号、関数名、<parameter>expression</parameter>を記憶し、<parameter>expression</parameter>内で検証が失敗した場合に表示します。<parameter>expression</parameter>の多くは関数呼び出しになるでしょう。</para>
<para><parameter>expression</parameter>の戻り値を取得できないことに注意してください。</para>
<para><link linkend="cut-trace"><function>cut_trace()</function></link>は以下の通りです。もし、cut_assert_not_null(object)が失敗したら、バックトレースには2行含まれます。cut_assert_not_null(object)とcreate_my_object("my-name")です。</para>
<para>例: <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>テストを読みやすくするために<link linkend="cut-trace"><function>cut_trace()</function></link>を使ったマクロを書くかもしれません: <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> :</term>
<listitem><simpara>呼び出されたことを記録される式。</simpara></listitem></varlistentry>
</variablelist><para role="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><link linkend="cut-trace"><function>cut_trace()</function></link>と<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>の違いは記録される式が<parameter>expression</parameter>と同じかどうかです。<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>はバックトレースの読みやすさのために<parameter>expression</parameter>から情報を隠したいときに便利です。</para>
<para><link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>の例です。cut_assert_not_null(object)が失敗すると以下の2行を含んだバックトレースが得られます:<itemizedlist>
  <listitem><para>cut_assert_not_null(object)</para></listitem>
  <listitem><para>create_my_object_helper("my-name")ではなくcreate_my_object("my-name")</para></listitem>
</itemizedlist>もし、<link linkend="cut-trace-with-info-expression"><function>cut_trace_with_info_expression()</function></link>ではなく<link linkend="cut-trace"><function>cut_trace()</function></link>を使った場合はcreate_my_object_helper("my-name")になります。もし、create_my_object_helper("my-name")が得られたら以下のように混乱してしまうかもしれません。「create_my_object_helper("my-name")はどこからきたんだ？<link linkend="test-my-object-name"><function>test_my_object_name()</function></link>はcreate_my_object("my-name")は使っているけど、create_my_object_helper("my-name")は使っていないぞ。」</para>
<para>例: <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> :</term>
<listitem><simpara>呼び出されたことを記録される式。</simpara></listitem></varlistentry>
<varlistentry><term><parameter>info_expression</parameter> :</term>
<listitem><simpara>呼び出されたと記録される式。</simpara></listitem></varlistentry>
</variablelist><para role="since">1.0.5から</para></refsect2>

</refsect1>

</refentry>
