<?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="readme">
<refmeta>
  <refentrytitle role="top_of_page" id="readme.top_of_page">はじめに</refentrytitle>
  <refmiscinfo>Cutterライブラリ</refmiscinfo>
</refmeta>
<refnamediv>
  <refname>はじめに</refname>
  <refpurpose>C言語・C++言語用単体テストフレームワークCutterの概要</refpurpose>
</refnamediv>
<refsect1>
  <title>名前</title>
  <para>Cutter</para>
</refsect1>

<refsect1>
  <title>作者</title>
  <refsect2>
  <title>プログラム</title>
  <itemizedlist>
  <listitem>
  <para>Kouhei Sutou &lt;kou@clear-code.com&gt;</para>
</listitem>
  <listitem>
  <para>Hiroyuki Ikezoe &lt;ikezoe@clear-code.com&gt;</para>
</listitem>
  <listitem>
  <para>Yuto Hayamizu &lt;y.hayamizu@gmail.com&gt;</para>
</listitem>
</itemizedlist>
</refsect2>

  <refsect2>
  <title>きのたんアイコン</title>
  <itemizedlist>
  <listitem>
  <para>Mayu &amp; Co.</para>
</listitem>
</itemizedlist>
</refsect2>

</refsect1>

<refsect1>
  <title>ライセンス</title>
  <itemizedlist>
  <listitem>
  <para>
  ソースコード: LGPLバージョン3またはそれ以降のバージョン（詳細:
  <ulink url="http://www.gnu.org/licenses/lgpl.html">license/lgpl-3.txt</ulink>
  ）です。
</para>
</listitem>
  <listitem>
  <para>ドキュメントときのたんアイコン: LGPLとGFDLとクリエイティブ・コモンズ・ライセンスのトリプルライセンス。</para>
  <itemizedlist>
  <listitem>
  <para>
  LGPLバージョン3またはそれ以降のバージョン（詳細:
  <ulink url="http://www.gnu.org/licenses/lgpl.html">license/lgpl-3.txt</ulink>
  ）です。
</para>
</listitem>
  <listitem>
  <para>
  GFDLはバージョン1.3またはそれ以降のバージョン（詳細:
  <ulink url="http://www.gnu.org/licenses/fdl.html">license/gfdl-1.3.txt</ulink>
  ）です。
</para>
</listitem>
  <listitem>
  <para>
  クリエイティブ・コモンズ・ライセンスは
  <ulink url="http://creativecommons.org/licenses/by-sa/3.0/">表示-継承（CC BY-SA）</ulink>
  です。
</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>例外:</para>
  <itemizedlist>
  <listitem>
  <para>
  glib-compatible/glibintl.h, glib-compatible/gregex.*, glib-compatible/gscripttable.h, glib-compatible/gsequence.*, glib-compatible/gstring.*, glib-compatible/gunicode.h, glib-compatible/guniprop.c: LGPLバージョン2.0またはそれ以降のバージョン（詳細:
  <ulink url="http://www.gnu.org/licenses/old-licenses/lgpl-2.0.html">glib-compatible/COPYING</ulink>
  ）
</para>
</listitem>
  <listitem>
  <para>
  glib-compatible/pcre/: PCREライセンス（詳細:
  <ulink url="http://www.pcre.org/licence.txt">glib-compatible/pcre/COPYING</ulink>
  ）
</para>
</listitem>
  <listitem>
  <para>
  html/blog.*, html/download.*, html/heading-mark.* html/install.*, html/readme.*, html/reference.*, html/tango-logo.png, html/tutorial.*, html/mini-*.svg:パブリックドメイン。
  <ulink url="http://tango.freedesktop.org/">Tango Desktop Project</ulink>
  の成果物を利用しています。（一部改変しているものもある）
</para>
</listitem>
  <listitem>
  <para>
  html/ja.png, html/us.png, html/famfamfam-logo.png:パブリックドメイン。
  <ulink url="http://famfamfam.com/">famfamfam.com</ulink>
  が配布している国旗です。
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</refsect1>

<refsect1>
  <title>Cutter?</title>
  <para>CutterはC言語・C++言語のためのxUnit系の単体テストフレームワークです。</para>
  <para>Cutterの特徴は以下の通りです。</para>
  <itemizedlist>
  <listitem>
  <para>テストが簡単に書ける</para>
</listitem>
  <listitem>
  <para>出力結果がデバッグに使いやすい</para>
</listitem>
  <listitem>
  <para>テストを共有ライブラリとしてビルドする</para>
</listitem>
</itemizedlist>
  <para>
  詳細は
  <link linkend="features">特徴</link>
  を見てください。
</para>
</refsect1>

<refsect1>
  <title>依存ライブラリ</title>
  <itemizedlist>
  <listitem>
  <para>GLib &gt;= 2.16</para>
</listitem>
</itemizedlist>
</refsect1>

<refsect1>
  <title>入手方法</title>
  <para>tar.gz:</para>
  <programlisting>% wget http://downloads.sourceforge.net/cutter/cutter-1.1.0.tar.gz</programlisting>
  <para>Subversion:</para>
  <programlisting>% svn co https://cutter.svn.sourceforge.net/svnroot/cutter/cutter/trunk cutter</programlisting>
</refsect1>

<refsect1>
  <title>インストール</title>
  <para>
  <ulink url="install.html">インストール</ulink>
  を見てください。
</para>
</refsect1>

<refsect1>
  <title>使い方</title>
  <programlisting>% cutter [オプション ...] テストディレクトリ</programlisting>
  <para>テストディレクトリにはtest_*.soがあるディレクトリを指定します。cutterはテストディレクトリ以下にあるtest_*.soを再帰的に検索します。</para>
  <para>
  詳細は
  <link linkend="cutter">cutter</link>
  を見てください。
</para>
</refsect1>

<refsect1>
  <title>テストの仕方</title>
  <para>テストの実行は以下のような流れになります．</para>
  <orderedlist>
  <listitem>
  <para>テストを作成する</para>
</listitem>
  <listitem>
  <para>コンパイルし、test_*.soを作成する</para>
</listitem>
  <listitem>
  <para>cutterを起動し、test_*.soを読み込ませ、テストをする</para>
</listitem>
</orderedlist>
  <para>
  詳しくは
  <link linkend="tutorial">チュートリアル</link>
  とsample/stack/を参考にしてください。
</para>
</refsect1>

<refsect1>
  <title>テスト結果</title>
  <para>テスト結果は例えば以下のようになります。</para>
  <programlisting>..........F.................................................

1) Failure: test_test_case_count
&lt;1 == cut_test_case_get_n_tests(test_object, NULL)&gt;
expected: &lt;1&gt;
 but was: &lt;0&gt;
test/test-cut-test-case.c:143: test_test_case_count()

Finished in 0.020857 seconds

60 test(s), 253 assertion(s), 1 failure(s), 0 error(s), 0 pending(s), 0 notification(s)</programlisting>
  <refsect2>
  <title>進行状況</title>
  <para>一番上にある「.」と「F」の部分がテストの進行状況を示しています。</para>
  <programlisting>..........F.................................................</programlisting>
  <para>各「.」、「F」が1つのテストケース（テスト関数）を表しています。「.」が成功したテストケース、「F」が失敗したテストケースを表しています。他にも「E」、「P」、「N」があり、それぞれエラー、保留、通知を表しています。まとめると以下のようになります。</para>
  <variablelist>
  <varlistentry>
  <term id="readme.-">.</term>
  <listitem>
  <para>成功したテスト</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="readme.F">F</term>
  <listitem>
  <para>表明が失敗したテスト</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="readme.E">E</term>
  <listitem>
  <para>異常終了したテスト</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="readme.P">P</term>
  <listitem>
  <para>保留マークがついているテスト</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term id="readme.N">N</term>
  <listitem>
  <para>通知が行われたテスト</para>
</listitem>
</varlistentry>
</variablelist>
  <para>上記のテストを表す印はテストが実行される毎に出力されます。テスト実行中は、この出力で実行状況を確認できます。</para>
</refsect2>

  <refsect2>
  <title>テスト結果のまとめ</title>
  <para>テストが終了すると、テスト結果のまとめを出力します。まとめは、まず、成功しなかったテストの詳細をそれぞれ表示します。例では1つ失敗があったのでそれを表示しています。</para>
  <programlisting>1) Failure: test_test_case_count
&lt;1 == cut_test_case_get_n_tests(test_object, NULL)&gt;
expected: &lt;1&gt;
 but was: &lt;0&gt;
test/test-cut-test-case.c:143: test_test_case_count()</programlisting>
  <para>この例ではtest_test_case_countテストケースが失敗し、cut_test_case_get_n_tests(test_object, NULL)が1になって欲しかったのに実際は0になっていることを表しています。また、この失敗した表明はtest/test-cut-test-case.cの143行目、test_test_case_count()関数内で起こったことがわかります。</para>
  <para>テスト結果の詳細一覧の後はテストにかかった時間が表示されます。</para>
  <programlisting>Finished in 0.020857 seconds</programlisting>
  <para>最後にテスト結果の要約が表示されます。</para>
  <programlisting>60 test(s), 253 assertion(s), 1 failure(s), 0 error(s), 0 pending(s), 0 notification(s)</programlisting>
  <para>それぞれは以下のような意味です。</para>
  <variablelist>
  <varlistentry>
  <term id="readme.n">n test(s)</term>
  <listitem>
  <para>n個のテストケース（テスト関数）を実行した</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term>n assertion(s)</term>
  <listitem>
  <para>n個の表明にパスした</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term>n failure(s)</term>
  <listitem>
  <para>n個の表明に失敗した</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term>n error(s)</term>
  <listitem>
  <para>n個の異常事態が発生した（cut_error()を使用した）</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term>n pending(s)</term>
  <listitem>
  <para>n個のテストケースを保留にした（cut_pending()を使用した）</para>
</listitem>
</varlistentry>
  <varlistentry>
  <term>n notification(s)</term>
  <listitem>
  <para>n個の通知が発生した（cut_notification()を使用した）</para>
</listitem>
</varlistentry>
</variablelist>
  <para>この例では60個のテストケースを実行し、253個の表明にパスし、1個の表明に失敗したということになります。異常事態や保留にしたテストケースなどはありませんでした。</para>
</refsect2>

  <refsect2>
  <title>XML出力</title>
  <para>--xml-reportオプションを指定することでテスト結果をXML形式で出力することができます。出力されるXMLは以下のような構造になっています。</para>
  <programlisting>&lt;report&gt;
  &lt;result&gt;
    &lt;test-case&gt;
      &lt;name&gt;テストケース名&lt;/name&gt;
      &lt;description&gt;テストケースの説明（もしあれば）&lt;/description&gt;
    &lt;/test-case&gt;
    &lt;test&gt;
      &lt;name&gt;テスト名&lt;/name&gt;
      &lt;description&gt;テストの説明（もしあれば）&lt;/description&gt;
      &lt;option&gt;&lt;!-- 属性情報（もしあれば） --&gt;
        &lt;name&gt;属性名（例: bug）&lt;/name&gt;
        &lt;value&gt;属性値（例: 1234）&lt;/value&gt;
      &lt;/option&gt;
      &lt;option&gt;
        ...
      &lt;/option&gt;
    &lt;/test&gt;
    &lt;status&gt;テスト結果（[success|failure|error|pending|notification]）&lt;/status&gt;
    &lt;detail&gt;テスト結果の詳細（もしあれば）&lt;/detail&gt;
    &lt;backtrace&gt;&lt;!-- バックトレース（もしあれば） --&gt;
      &lt;entry&gt;
        &lt;file&gt;ファイル名&lt;/file&gt;
        &lt;line&gt;行&lt;/line&gt;
        &lt;info&gt;付加情報&lt;/info&gt;
      &lt;/entry&gt;
      &lt;entry&gt;
        ...
      &lt;/entry&gt;
    &lt;/backtrace&gt;
    &lt;elapsed&gt;実行時間（例: 0.000010）&lt;/elapsed&gt;
  &lt;/result&gt;
  &lt;result&gt;
    ...
  &lt;/result&gt;
  ...
&lt;/report&gt;</programlisting>
</refsect2>

  <refsect2>
  <title>テストカバレッジ</title>
  <para>
  システムに
  <ulink url="http://ltp.sourceforge.net/">LTP tools</ulink>
  がインストールされている場合は、Cutterを使ったテストを用いてコードカバレッジを出力することができます。カバレッジを出力するにはconfigure.acに以下を追加して、&quot;make coverage&quot;を実行してください。
</para>
  <programlisting>AC_CHECK_COVERAGE</programlisting>
</refsect2>

</refsect1>

<refsect1>
  <title>リファレンス</title>
  <refsect2>
  <title>表明</title>
  <para>
  <link linkend="cutter-cut-assertions">cutter/cut-assertions.h</link>
  を見てください。
</para>
</refsect2>

  <refsect2>
  <title>属性</title>
  <para>テストに属性を加えて、テスト失敗時により有益な情報を利用することができます。例えば、以下のようにテストにBug IDの情報を付加することができます。</para>
  <programlisting>void attributes_invalid_input(void);
void test_invalid_input(void);

void
attributes_invalid_input (void)
{
    cut_set_attributes(&quot;bug&quot;, &quot;123&quot;);
}

void
test_invalid_input (void)
{
    cut_assert_equal(&quot;OK&quot;, get_input());
}</programlisting>
  <para>この例では、test_invalid_inputテストがBug #123のテストであるという情報を付加しています。</para>
  <para>属性は&quot;「attributes_「テスト名からtest_を除いたもの」&quot;という名前の関数を定義し、その関数の中でcut_set_attributes()を使って設定できます。上記の例では「test_invalid_input」テストに「123」という値の「bug」属性を追加するために「attributes_invalid_input」という関数を定義し、その中でcut_set_attributes(&quot;bug&quot;, &quot;123&quot;)を呼び、属性を設定しています。</para>
</refsect2>

  <refsect2>
  <title>雛型</title>
  <para>テストの雛型は以下のようになります．</para>
  <programlisting>#include &lt;cutter.h&gt;

#include &quot;自分のプログラムのヘッダファイル&quot;

void test_condition(void);
void test_strstr(void);

static int condition = 0;

void
cut_setup (void)
{
    /* 初期化用コード */
    condition = 1;
}

void
cut_teardown (void)
{
    /* 後片付け用コード */
    condition = 0;
}

void
test_condition(void)
{
    cut_set_message(&quot;conditionの値はcut_setup()で1に設定されているはず&quot;);
    cut_assert_equal_int(1, condition);
  ...
}

void
test_strstr(void)
{
    cut_assert_equal_string(&quot;sub-string&quot;,
                            strstr(&quot;string sub-string&quot;, &quot;sub&quot;));
    ...
}</programlisting>
</refsect2>

</refsect1>

<refsect1>
  <title>感謝</title>
  <itemizedlist>
  <listitem>
  <para>Kazumasa Matsunagaさん: ビルドの不具合を報告してくれました。</para>
</listitem>
  <listitem>
  <para>Daijiro MORIさん: 不具合を報告してくれました。</para>
</listitem>
  <listitem>
  <para>海野さん:</para>
  <itemizedlist>
  <listitem>
  <para>チュートリアルの不具合に気づかせてくれました。</para>
</listitem>
  <listitem>
  <para>Solaris用インストールドキュメントの作成を手伝ってくれました。</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>グニャラくん: APIについてアドバイスしてくれました。</para>
</listitem>
  <listitem>
  <para>山川さん: Cygwinでの動作を教えてくれました。</para>
</listitem>
  <listitem>
  <para>奥地さん:</para>
  <itemizedlist>
  <listitem>
  <para>Localeまわりの不具合を報告してくれました。</para>
</listitem>
  <listitem>
  <para>新機能を提案してくれました。</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>Zed Shawさん: 不具合を報告してくれました。</para>
</listitem>
  <listitem>
  <para>Romuald Contyさん: ドキュメントの不具合を報告してくれました。</para>
</listitem>
  <listitem>
  <para>Romain Tartièreさん:</para>
  <itemizedlist>
  <listitem>
  <para>不具合を報告してくれました。</para>
</listitem>
  <listitem>
  <para>改良方法を提案してくれました。</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>Ilya Baryginさん:</para>
  <itemizedlist>
  <listitem>
  <para>テストの不具合を報告してくれました。</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>中村弘輝さん</para>
  <itemizedlist>
  <listitem>
  <para>CentOSでの不具合を報告してくれました。</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</refsect1>
</refentry>
