<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry 
  PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="features">
<refmeta>
  <refentrytitle id="features.top_of_page" role="top_of_page">機能</refentrytitle>
  <refmiscinfo>Cutterライブラリ</refmiscinfo>
</refmeta>
<refnamediv>
  <refname>機能</refname>
  <refpurpose>Cutterの機能</refpurpose>
</refnamediv>
<refsect1>
  <title>はじめに</title>
  <para>Cutterは以下のような単体テストフレームワークの基本的な機能を持っています。</para>
  <itemizedlist>
  <listitem>
  <para>フィクスチャ</para>
</listitem>
  <listitem>
  <para>テスト登録コード不要</para>
</listitem>
  <listitem>
  <para>デバッグに便利な結果出力</para>
</listitem>
  <listitem>
  <para>豊富な検証機能</para>
</listitem>
</itemizedlist>
  <para>Cutterは以下のようなテスト環境をもっと便利にする高度な機能もあります。</para>
  <itemizedlist>
  <listitem>
  <para>複数のプラットフォーム対応</para>
</listitem>
  <listitem>
  <para>データ駆動テストのサポート</para>
</listitem>
  <listitem>
  <para>カバレッジのサポート</para>
</listitem>
  <listitem>
  <para>クラッシュ時のバックトレース出力</para>
</listitem>
  <listitem>
  <para>テスト結果の保存・復元</para>
</listitem>
  <listitem>
  <para>マルチプロセス・マルチスレッドのサポート</para>
</listitem>
  <listitem>
  <para>画像差分</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</refsect1>

<refsect1>
  <title>基本機能</title>
  <para>単体テストフレームワークが一般的に提供している機能について、Cutterがどのようにその機能を提供しているかについてを説明します。</para>
  <refsect2>
  <title>フィクスチャ</title>
  <para>単体テストフレームワークでいうフィクスチャとは、各テストを実行する前にテスト用データを用意するための仕組みのことです。これは、一般的には各テスト毎にsetup/teardownと呼ばれる初期化処理/終了処理を実行することによって実現します。</para>
  <para>Cutterでは以下のようにテストプログラム中にcut_setup()/cut_teardown() 関数を定義すると、それらの関数が初期化処理/終了処理として扱われます。</para>
  <programlisting>void
cut_setup (void)
{
   /* 初期化処理 */
}

void
cut_teardown (void)
{
   /* 終了処理 */
}</programlisting>
  <para>また、Cutterではテストケース毎の初期化処理/終了処理のためにcut_startup()/cut_shutdown()もサポートしてます。</para>
  <programlisting>void
cut_startup (void)
{
   /* テストケースの初期化処理 */
}

void
cut_shutdown (void)
{
   /* テストケースの終了処理 */
}</programlisting>
  <para>これらの関数は以下のような順番で呼ばれます。</para>
  <itemizedlist>
  <listitem>
  <para>cut_startup()</para>
  <itemizedlist>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テスト1実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テスト2実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_shutdown()</para>
</listitem>
</itemizedlist>
  <para>また、実験的な機能ですが、テスト全体を実行する前、テスト全体を実行した後に呼び出す関数を登録することもできます。これらの関数をそれぞれwarmup/cooldownと呼んでいます。呼び出し順序はこうなります。</para>
  <itemizedlist>
  <listitem>
  <para>warmup実行</para>
  <itemizedlist>
  <listitem>
  <para>テストケース1のcut_startup()</para>
  <itemizedlist>
  <listitem>
  <para>テストケース1のcut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テスト1-1実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>テストケース1のcut_teardown()</para>
</listitem>
  <listitem>
  <para>テストケース1のcut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テスト1-2実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>テストケース1のcut_teardown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>テストケース1のcut_shutdown()</para>
</listitem>
  <listitem>
  <para>テストケース2のcut_startup()</para>
  <itemizedlist>
  <listitem>
  <para>テストケース2のcut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テスト2-1実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>テストケース2のcut_teardown()</para>
</listitem>
  <listitem>
  <para>テストケース2のcut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テスト2-2実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>テストケース2のcut_teardown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>テストケース2のcut_shutdown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cooldown実行</para>
</listitem>
</itemizedlist>
  <para>この機能は、テスト対象のライブラリがライブラリ初期化関数・終了関数を用意している場合に有用です。ただ、この機能は実験的な機能なのでここでその使い方を紹介するのは控えておきます。もし、使いたい場合は聞いてください。</para>
</refsect2>

  <refsect2>
  <title>テスト登録コード不要</title>
  <para>動的な言語用の単体テストフレームワークの多くでは明示的にテストを登録する必要はありません。自動的にテストメソッド・テスト関数などを見つけて実行します。しかし、C言語用の単体テストフレームワークの多くでは明示的にテストを登録する必要があります。</para>
  <para>Cutterはテストを簡単に書けるようにするため、多くの動的な言語用の単体テストフレームワークのように自動的にテスト関数を見つけます。そのため、以下のように名前が「test_」からはじまる公開関数を定義するだけでその関数がテスト関数として認識されます。</para>
  <programlisting>void test_my_function (void);

void
test_my_function (void)
{
    /* テスト関数 */
}</programlisting>
</refsect2>

  <refsect2>
  <title>デバッグに便利な結果出力</title>
  <para>Cuterは迅速に問題の確認・修正が行えるようにテスト結果を出力します。具体的には以下のように出力を行います。</para>
  <itemizedlist>
  <listitem>
  <para>問題がない部分はシンプルに</para>
</listitem>
  <listitem>
  <para>問題がある部分は冗長に</para>
</listitem>
</itemizedlist>
  <para>まず、問題がない部分をシンプルに表示する（時には何も表示しない）ことにより大事な情報が埋もれてしまうことを防ぎます。</para>
  <para>また、問題がある部分はどのような問題があるかを判断するために、知っている情報をできるだけ多く表示します。</para>
  <para>例えば、文字列が同じ内容かを比較するテストで文字列が異なって場合を考えます。Cutterは期待値と実測値を並べて表示します。これによりどの部分が異なるかを目視で確認しやすくなります。</para>
  <programlisting>expected: &lt;abc def ghi jkl&gt;
 but was: &lt;abc DEF ghi jkl&gt;</programlisting>
  <para>もし、これがずれて表示されていたり、同じ行に表示されているとどこが異なるかを見つけるのは大変になります。</para>
  <programlisting>expected: &lt;abc def ghi jkl&gt;
but was: &lt;abc DEF ghi jkl&gt;

&lt;abc def ghi jkl&gt; is expected but was &lt;abc DEF ghi jkl&gt;</programlisting>
  <para>また、必要ならば期待値と実測値のdiffを表示して具体的にどこが異なるのかも示します。</para>
  <programlisting>expected: &lt;abc def ghi jkl&gt;
 but was: &lt;abc DEF ghi jkl&gt;

diff:
- abc def ghi jkl
?     ^^^
+ abc DEF ghi jkl
?     ^^^</programlisting>
  <para>このように、Cutterにはテストが失敗した時に迅速に問題を確認するための工夫が施されています。これにより、開発者が迅速に問題を修正することを支援します。</para>
</refsect2>

  <refsect2>
  <title>豊富な検証機能</title>
  <para>xUnit系の単体テストフレームワークではテスト対象が期待する動作をしているかを検証するために、assertionと呼ばれる検証機能を提供します。例えば、一般的には以下のような検証機能があります。</para>
  <itemizedlist>
  <listitem>
  <para>assert: 検証対象が真の値であることを検証</para>
</listitem>
  <listitem>
  <para>assert_equal: 実測値が期待値と等しいことを検証</para>
</listitem>
</itemizedlist>
  <para>Cutterでは、以下の検証機能が上記の検証機能に対応します。</para>
  <itemizedlist>
  <listitem>
  <para>cut_assert()</para>
</listitem>
  <listitem>
  <para>cut_assert_true(): 機能はcut_assert()と同じだが「真の値」であることを明示（自己記述的なためこちらの利用を推奨）</para>
</listitem>
  <listitem>
  <para>cut_assert_equal_int()</para>
</listitem>
  <listitem>
  <para>cut_assert_equal_uint()</para>
</listitem>
  <listitem>
  <para>cut_assert_equal_string()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
  <para>Cutterは上記のような一般的な検証機能以外にも様々な検証機能が組み込みで提供しているので、より簡単にテストを書くことができます。例えば、以下のような検証機能を提供しています。</para>
  <itemizedlist>
  <listitem>
  <para>cut_assert_errno(): errnoが0であることを検証</para>
</listitem>
  <listitem>
  <para>cut_assert_match(): 実測値の文字列が指定した正規表現にマッチすることを検証</para>
</listitem>
  <listitem>
  <para>cut_assert_path_exist(): 指定したパスが存在することを検証</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
  <para>
  検証機能の一覧はリファレンスマニュアルの
  <link linkend="cutter-cut-assertions">検証</link>
  や
  <link linkend="cutter-gcut-assertions">GLibサポート付きの検証</link>
  を見てください。
</para>
</refsect2>

</refsect1>


<refsect1>
  <title>高度な機能</title>
  <para>一部の単体テストフレームワークが提供している機能のCutterでの提供の仕方、および、どの単体テストフレームワークも提供していないCutter独特の機能について提供について説明します。</para>
  <refsect2>
  <title>複数のプラットフォーム対応</title>
  <para>現在、以下のプラットフォームでの動作を確認しています。</para>
  <itemizedlist>
  <listitem>
  <para>GNU/Linux</para>
</listitem>
  <listitem>
  <para>FreeBSD</para>
</listitem>
  <listitem>
  <para>Mac OS X</para>
</listitem>
  <listitem>
  <para>Windows (MinGW)</para>
</listitem>
</itemizedlist>
</refsect2>
  <refsect2>
  <title>データ駆動テストのサポート</title>
  <para>複数のデータに対して同じテストを実行する場合があります。例えば、以下のような場合が考えられます。</para>
  <itemizedlist>
  <listitem>
  <para>複数の入力パターンがあり、それらを網羅的にテストする場合</para>
</listitem>
  <listitem>
  <para>複数のバックエンドを抽象化し、どのバックエンドを利用している場合でも同じインターフェイスで扱えるライブラリをテストする場合。（cairoやDBIなど）</para>
</listitem>
</itemizedlist>
  <para>このような場合、テスト自体は1つだけ定義し、各テストデータに対してそのテストを実行することで効率的にテストを作成することができます。このようなテストの仕方はデータ駆動テストと呼ばれています。</para>
  <para>
  Cutterでのデータ駆動テストの書き方については
  <link linkend="cutter-cutter">cut_add_data()</link>
  を見てください。
</para>
  <para>データ駆動テストの場合はテストは以下のような流れで実行されます。</para>
  <itemizedlist>
  <listitem>
  <para>テストデータ生成関数呼び出し</para>
</listitem>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テストデータ1を使ってテスト実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>cut_setup()</para>
  <itemizedlist>
  <listitem>
  <para>テストデータ2を使ってテスト実行</para>
</listitem>
</itemizedlist>
</listitem>
  <listitem>
  <para>cut_teardown()</para>
</listitem>
  <listitem>
  <para>...</para>
</listitem>
</itemizedlist>
</refsect2>
  <refsect2>
  <title>カバレッジのサポート</title>
  <para>カバレッジ率はどの程度テストを網羅的に行っているかを示す指標になります。</para>
  <para>CutterはGCCを使用したカバレッジ測定を支援するためのM4マクロを提供しています。GNU Autoconf/GNU Automakeを利用している場合はこのM4マクロを利用することにより、カバレッジ測定環境を簡単にビルドシステムに組み込むことができます。</para>
  <para>
  詳しくは
  <link linkend="readme">README.ja</link>
  や
  <link linkend="tutorial">チュートリアル</link>
  のAC_CHECK_COVERAGEについて書かれている部分を見てください。
</para>
</refsect2>
  <refsect2>
  <title>クラッシュ時のバックトレース出力</title>
  <para>C言語・C++言語で実装されたプログラムではSegmentation Faultでプログラムが異常終了することは珍しくありません。この時、CutterはSEGV シグナルが発生した時点でのバックトレースの取得を試みます。取得できた場合はバックトレースを出力してから終了します。もちろん、この時点でテストプロセスがなにかしら破壊されているので、必ずしもバックトレースを取得できるわけではありません。</para>
  <para>問題の詳細を調べるには、GDBなどのデバッガで処理を追いかけていく必要がありますが、バックトレースをデバッグの最初の足がかりとして利用することができます。</para>
</refsect2>
  <refsect2>
  <title>テスト結果の保存・復元</title>
  <para>ソフトウェアの品質を確認する方法として以下のような方法があります。</para>
  <itemizedlist>
  <listitem>
  <para>テスト状況とバグ発見数の推移を測定</para>
</listitem>
  <listitem>
  <para>テスト状況とバグ報告数の推移を測定</para>
</listitem>
  <listitem>
  <para>テスト状況とソース規模の推移を測定</para>
</listitem>
</itemizedlist>
  <para>例えば、テストが増えているのにバグ発見数が少ない場合は、効率の悪いテストを行っている、あるいはもともとテスト対象の品質が高かったということが考えられます。テストが増えているのにバグ報告数が伸びている場合は的外れなテストを行っているかもしれません。ソース規模が大きくなっているのにテストが増えていない場合はテスト不足が考えられます。</para>
  <para>このように、その時点でのテスト状況だけではなく、過去のテスト結果も利用して時系列でソフトウェアの開発状況を分析することにより、ソフトウェアの品質向上に役立てることができる場合があります。</para>
  <para>Cutterはテスト結果をXMLとしてファイルに保存することができます。また、保存したXMLを読み込んでテスト結果を復元することができます。</para>
  <para>まだ実装されていませんが、保存したテスト結果を読み込んで、時系列のグラフとしてレポートを出力する機能の実装を予定しています。</para>
</refsect2>
  <refsect2>
  <title>マルチプロセス・マルチスレッドのサポート</title>
</refsect2>
</refsect1>
</refentry>
