/* -*- Indented-Text -*- */
/* Copyright (C) 2003, 2010, 2013 TSUTSUMI Kikuo.
   This file is part of the CCUnit Library.

   The CCUnit Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public License
   as published by the Free Software Foundation; either version 2.1 of
   the License, or (at your option) any later version.

   The CCUnit Library is distributed in the hope that it will be
   useful, but WITHOUT ANY WARRANTY; without even the implied warranty
   of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the CCUnit Library; see the file COPYING.LESSER.
   If not, see <http://www.gnu.org/licenses/>
*/
/* $Id$ */
/**
@english
@page cookbook CCUnit Cookbook
@japanese
@page cookbook CCUnit クックブック
@endif

@~english
Here is a short cookbook to help you get started.
@~japanese
これは CCUnit を使い始めるにあたって、
理解の助けとなるような短いクックブックです。
@~
@english
[see also <a href="../ja/cookbook.html">Japanese</a> documents]
@japanese
[see also <a href="../../cookbook.html">English</a> documents]
@endif

@english
@section simple_test_case Simple Test Case
@japanese
@section simple_test_case シンプルなテストケース
@endif

@english
Tests in <b>CCUnit</b> can be run automatically.  They are
easy to set up and once you have written them, they are
always there to help you keep confidence in the quality of
your code.
@japanese
<b>CCUnit</b> を使ったテストは自動的に実行することができます。
CCUnit のテストは簡単にセットアップすることができ、
一度テストを書いてしまえば、
いつでもプログラムの品質を信頼できるものに保つことができるでしょう。
@endif

@english
To make a simple test, here is what you do:
@japanese
簡単なテストを作るには、次のようにします。
@endif

<ol>
<li> @english Create a test function
     @japanese テスト関数を作ります。
     @endif
</li>
<li> @english When you want to check a value, call
     @link CCUNIT_ASSERT(bool) @endlink
     and pass a bool that is true if the test succeeds

     ASSERT macro is listed in others as well in
     @link Assertions Assert Macros@endlink.
     @japanese
     値をチェックしたい場合は、
     @link CCUNIT_ASSERT(bool) @endlink
     を呼び出して、
     テストが成功するなら真を返すような真偽値を渡します。

     ASSERT 関係のマクロは他にも
     @link Assertions ASSERT マクロ@endlinkにリストしてあります。
     @endif
</li>
</ol>

@english
For example, see the test of the library of the simple
complex number as an example.
(This sample program is in the @c examples/complex directory)
To test whether the initialization of the complex numeber
and two complex numbers are equal.
@japanese
例えば、簡単な複素数のライブラリのテストを例にとってみましょう。
（ここで使用する@ref sample_programs は
@c examples/complex ディレクトリにあります。）
複素数を初期化することができたかをテストしたり、
二つの複素数が等しいかをテストしたりします。
@endif

@dontinclude complex/testComplex.c

@skip test_complex_new
@until test_complex_equals
@until }

@english
These two test functions are made one test case together,
and we can run it.
@japanese
この二つのテスト関数をまとめてひとつのテストケースにして実行することができます。
@endif

@dontinclude complex/runTestCase.c

@english
Include the necessary header files.
@japanese
必要なヘッダファイルをインクルードします。
@endif

@skip CCUnitTestCase.h
@until CCUnitTestResult.h

@english
First, Allocate the test case memory.
@japanese
まずテストケースにメモリを割り当てます。
@endif

@until main
@until ccunit_newTestCase

@english
Then, register the test functions in the test case.
The assertion should specify the name of the function
and the explanation of the function
to indicate it at the unsuccessful time.
@japanese
そしてテストケースにテスト関数を登録します。
表明 (ASSERT) が失敗した時に表示するための関数名と関数の説明を一緒に指定しています。
@endif

@until test_complex_equals);

@english
Run the test case, and take out the result.
@japanese
テストケースを実行し、
結果を取り出します。
@endif

@until wasSuccessful

@english
Deallocate the memory whitch you assigned, 
and return the result.
@japanese
割り当てたメモリを解放し、
結果を返します。
@endif

@until }

@english
You find the sample code made in the above in the
files <code>testComplex.c</code> and <code>runTestCase.c</code>
in the <code>examples/complex</code> directory.

To compile and run, do the following:
@japanese
ここまでのサンプルコードは、@c examples/complex ディレクトリの
<code>testComplex.c, runTestCase.c</code> にあります。

コンパイルおよび実行するには、次のようにします。
@endif

@code
$ gcc -o runTestCase runTestCase.c testComplex.c complex.c -lccunit
$ ./runTestCase
$ echo $?
0
@endcode

@english
When the test case is run, that specific test functions
will be run.  This is not a useful thing to do, however, as
no diagnostics will be displayed.  One will normally use a
@ref ExecutingTest to display the results.
@japanese
テストケースが実行されると、
指定したテスト関数が呼び出されます。
これはまだあまり便利ではありません、
なぜなら、診断が表示されないからです。
通常は@ref ExecutingTest で結果を表示します。
@endif

@english
@section test_runner TestRunner
@japanese
@section test_runner テストランナー
@endif

@english
How do you run your tests and collect their results?
The TestCase store result of own tests into
the @link CCUnitTestResult TestResult@endlink.
At the same time, the test case informs the
@link CCUnitTestRunner TestRunner@endlink
of the executive conditionsn of the test.
@japanese
テストを実行したときに、どうやってその結果を集めたら良いでしょうか。
テストケースはテスト関数の実行結果
@link CCUnitTestFailure TestFailure @endlink を
@link CCUnitTestResult TestResult @endlink に格納します。
同時にテストの実行状況を @link CCUnitTestRunner TestRunner @endlink
に通知します。
@endif

@dot
digraph TestResult {
  node [ fontsize=9, fontname=Helvetica ]
  edge [ fontsize=9, dir=back ]
  TestRunner [ URL="@ref CCUnitTestRunner" ];
  TestRunner -> TestCase [ label="Notify", fontname=Times, 
  	     		   style=dotted, arrowhead=vee ];
  TestRunner -> TestResult [ arrowtail=none ];
  { rank=same;
    TestCase [ URL="@ref CCUnitTestCase" ];
    TestResult [ URL="@ref CCUnitTestResult" ];
    TestCase -> TestResult [
      label="TestFailure", fontname=Courier,
      dir=forward, style=dotted, arrowhead=vee
    ];
  }
  TestFunc [ label="TestFunc 1..n", URL="@ref CCUnitTestFunc" ];
  TestFailure [ label="TestFailure 0..m", URL="@ref CCUnitTestFailure" ];
  TestCase -> TestFunc;
  TestResult -> TestFailure [ arrowtail=odiamond ];
}
@enddot

@english
Once you have a test suite, you'll want to run it. %CCUnit
provides @link ExecutingTest TestRunner @endlink
to define the suite to be run and to display
its results.
@japanese
一つテストケースを書いたら、
それを実行したいと思うでしょう。
CCUnit の @link ExecutingTest TestRunner @endlink は、
テストケースをテストスーツにまとめて実行し結果を表示します。
@endif

@english
To use the @link CCUnitTestRunner TestRunner@endlink,
include the header files for the tests in <code>runTestCaseRunner.c</code>:
@japanese
@link CCUnitTestRunner TestRunner @endlink を使用するには、
例えば @c runTestCaseRunner.c でテストのためのファイルのヘッダをインクルードします。
@endif

@dontinclude complex/runTestCaseRunner.c

@skipline #include
@until CCUnitTestRunner.h

@english
First, make the @link CCUnitTestSuite TestSuite@endlink,
and register the @link CCUnitTestCase TestCase@endlink.
@japanese
まず @link CCUnitTestSuite TestSuite@endlink を作成し、
それに @link CCUnitTestCase TestCase@endlink を登録します。
@endif

@until ccunit_addTestCase

@english
And call to
@link ccunit_runTestRunner(CCUnitTestRunner*, CCUnitTestSuite *)@endlink:
@japanese
そして @link ccunit_runTestRunner(CCUnitTestRunner*, CCUnitTestSuite *) @endlink
を実行します。
@endif

@until runTestRunner

@english
Deallocate the memories.
@japanese
割り当てたメモリを解放します。
ただし、@c testCase は @c suite に登録してあるので、
@c suite を解放する時に一緒に解放されます。
そのため @c testCase はここで解放する必要がありません。
解放しようとすると Bus error などになりますので注意してください。
@endif

@until }

@english
The sample code made in the above is in the directory <code>examples/complex</code>,
the files <code>testComplex.c, complexTestSuite.c</code> and <code>runTestRunner.c</code>.

To compile and run, do the following:
@japanese
ここまでのサンプルコードは、<code>examples/complex</code> ディレクトリの
<code>runTestCaseRunner.c</code>
にあります。

コンパイルおよび実行するには、次のようにします。
@endif

@code
$ gcc -o runTestCaseRunner runTestCaseRunner.c testComplex.c complex.c -lccunit
$ ./runTestCaseRunner
..
Time: 0.000027 sec

OK (2 tests)
@endcode

@english
The @link ExecutingTest TestRunner @endlink will run the tests.
If all the tests pass, you'll get an informative message.
If any fail, you'll get the following information:
@japanese
@link ExecutingTest TestRunner @endlink はテストを実行します。
もしすべてのテストがパスすれば、その情報のメッセージが表示されます。
上の例では、最初の「<code>..</code>」は実行したテストケースです。
実行する直前に「<code>.</code>」が出力されます。
全てのテストケースの実行が終了すると、
実行にかかった時間と実行したテストケースの数が表示されます。

どれかが失敗すれば、それについて以下のような情報が表示されます。
@endif

<ul>
<li>@english
    The name of the source file that contains the test
    @japanese
    テストを含んでいるソースファイル名
    @endif
</li>
<li>@english
    The line number where the failure occurred
    @japanese
    失敗が起こった行番号
    @endif
</li>
<li>@english
    The name of the test case that failed
    @japanese
    失敗したテストケースの名前
    @endif
</li>
<li>@english
    All of the text inside the call to
    @link CCUNIT_ASSERT(bool)@endlink which detected the failure
    @japanese
    失敗を検知した @link CCUNIT_ASSERT(bool)@endlink が呼び出された時の条件の文字列。
    @endif
</li>
</ul>

@english
For example, try to mistake it in the test case
of @c testComplex.c on purpose.
@japanese
試しに @c testComplex.c のテストケースでわざと間違えてみましょう。
@endif

@code
void test_complex_new ()
{
  ...
  CCUNIT_ASSERT_EQ_DOUBLE (10, c10_1->real);
/*CCUNIT_ASSERT_EQ_DOUBLE (1, c10_1->imaginary);*/
  CCUNIT_ASSERT_EQ_DOUBLE (1.1, c10_1->imaginary);
  ...
}
@endcode

@code
$ gcc -o runTestCaseRunner runTestCaseRunner.c testComplex.c complex.c -lccunit
$ ./runTestRunner
.F.
Time: 0.000051 sec

FAILURES!!!
Test Results: 
Run 2, Failures 1
There was 1 failure:
testFailComplex.c:36: complex new test:
	1.1 == c10_1->imaginary
	expect: 1.100000
	actual: 1.000000
@endcode

@english
In this example, two test cases are run.
Then, you will see that the second is unsuccessful.
@japanese
この例ではテストケースを 2 個実行して、
ひとつのテストケースで失敗していることがわかります。
最初の「 <code>.F.</code>」では、
ひとつ目のテストケースが失敗していることをあらわしています。

また上述のように、
失敗したファイル名、行番号、テストケースの名前 (<code>complex new test</code>)、
表明した条件の文字列 (<code>1.1 == c10_1->imaginary</code>) が表示されます。
@endif

@english
That was a very simple test. Ordinarily, you'll have many
little test cases that you'll want to run on the same set of
objects. To do this, use global variables.
@japanese
これは大変単純なテストです。
通常、
たくさんの小さなテスト関数を作って、
同じようなデータの集まりを使ってテストを行うでしょう。
つまり各テスト関数共通のグローバル変数を使うことになります。
@endif

@english
@section setUp_and_tearDown setUp and tearDown
@japanese
@section setUp_and_tearDown setUp と tearDown
@endif

@english
What if you have two or more tests that operate on the same
similar set of objects?
@japanese
もし複数のテスト関数があるなら、
同じデータの集まりをいくつか使うのではないでしょうか。
@endif

@dot
digraph TestCase {
  node [ fontsize=9, fontname=Helvetica ]
  edge [ fontsize=9, dir=back, arrowtail=vee ]
  gv [ label="Global Variables", shape=box ]
  { rank=same;
    tc1 [ label="Test Case 1" ];
    tc2 [ label="Test Case 2" ];
    tcn [ label="Test Case n" ];
  }
  gv -> tc1;
  gv -> tc2 [ weight=8 ];
  gv -> tcn;
  tc2 -> tcn [ label="...", fontname=Helvetica, dir=none, color=white ];
}
@enddot

@english
Tests need to run against the background of a known set of
data.
you are writing tests you will often find that you spend
more time writing the code to set up the data than you do
in actually testing values.
@japanese
テストは中身のわかっているデータの集まりを前提として実行される必要があります。
テストを書いていると、
実際にテストするコードよりも、
値をセットアップするコードを書く方に、
より時間をかけていることがよくあります。
@endif

@english
In the sample code of the previous section,
some complex numbers are allocated,
and it is deleted.
@japanese
例えば前節のサンプルコードでは、
いくつかの複素数を割り当てたり解放したりしています。
@endif

@english
Often, you will be able to use the same data for several
different tests. Each case will assign slightly different
values to the data and will check for
different results.
Then, if the test is finished, clean-up the data.
The function @c setUp and @c tearDown are used at such time.
@japanese
多くの場合、いくつかの異なったテストのために同じグローバル変数を使うことができます。
それぞれのテスト関数を実行する前に変数を初期化し、
値を調べることになるでしょう。
そしてテストが終わったら後始末することになります。

@c setUp と @c tearDown 関数はそのような場合に使用することができます。
@endif

@dot
digraph TestFixture {
  node [ fontsize=9, fontname=Helvetica ]
  edge [ fontsize=9, dir=back, arrowtail=vee ]
  rankdir=TB;
  gv [ label="Global Variables", shape=box ]
  { rank=same;
    su [ label="setUp" ];
    tc [ label="TestCase" ];
    td [ label="tearDown" ];
  }
  gv -> su [ label="initialize" ];
  gv -> tc [ label="access" ];
  gv -> td [ label="clean-up" ];
}
@enddot

@english
When you have a common global variables, here is what you do:
@japanese
もし各テストに共通のグローバル変数があれば、
次のようにすることになります。
@endif

@dontinclude complex/testComplexSetup.c

@english
Define the global variable.
@japanese
グローバル変数を定義します。
@endif

@skipline complex.h
@until c10_1;

@english
Write the function @c setUp to allocate the complex.
@japanese
複素数を割り当てる @c setUp 関数を書きます。
@endif

@until }

@english
Write the function @c tearDown to delete the memory of that complex.
@japanese
割り当てたメモリを解放する @c tearDown 関数を書きます。
@endif

@until }

@english
Write the test function.
@japanese
テスト関数を書きます。
@endif

@until test_complex_equals
@until }

@english
Register the function @c setUp and @c tearDown.
At this time, the name of the function must have begun with
@c "setUp" or @c "tearDown".
@japanese
@c setUp と @c tearDown を登録します。
この時、関数の名前が @c setUp/tearDown で始まっていなければなりません。
@endif

@dontinclude complex/runTestCaseSetup.c
@skip int main
@until setUp_test_complex);
@until tearDown_test_complex);

@english
Run the test case, and return the result.
@japanese
テストケースを実行し、
結果を返します。
@endif

@until }

@english
The sample code made in the above is in the directory <code>examples/complex</code>,
the files are @c testComplexSetup.c and <code>runTestCaseSetup.c</code>.

To compile and run, do the following:
@japanese
ここまでのサンプルコードは、@c examples/complex ディレクトリの
<code>testComplexSetup.c, runTestCaseSetup.c</code> にあります。

コンパイルおよび実行するには、次のようにします。
@endif

@code
$ gcc -o runTestCaseSetup runTestCaseSetup.c testComplexSetup.c complex.c -lccunit
$ ./runTestCaseSetup
..
Time: 0.000048 sec

OK (2 tests)
@endcode

@english
@section one_time_setUp_tearDown setUp/tearDown of only one time
@japanese
@section one_time_setUp_tearDown 一回だけの setUp/tearDown
@endif

@english
In the previous section,
the initialization was done in every test every time.
But we do the initialization only once,
and we may run the multiple test.
Then, only when all the tests are finished,
it may seem to carry out the code for the settlement.

You register the @c setUpBeforeClass and @c tearDownAfterClass
function in the test case for that.
Then, the test functions are run in the following order:
@japanese
前の節ではテストごとに毎回初期化を行っていました。
しかし、
一回だけ初期化を行って、
複数のテストを実行したい場合があります。
そしてテストが全て終わったときだけ後始末のコードを実行するような場合があります。

そのためにはテストケースに
@c setUpBeforeClass, @c tearDownAfterClass 関数を登録します。
すると次のような順序でテスト関数が実行されます。
@endif

@dot
digraph TestCaseCallingSequence {
  node [ fontsize=9, fontname=Helvetica ]
  edge [ fontsize=9 ]
  rankdir = LR;
  { rank=same;
    setUp;
    setUp2 [ label="setUp" ];
  }
  setUpBeforeClass -> setUp [ weight=8 ];
  setUpBeforeClass -> setUp2 [ style=invis ];
  setUp -> "TestFunc 1" [ weight=8 ];
  "TestFunc 1" -> tearDown [ weight=8 ];
  setUp2 -> "TestFunc n" [ weight=8 ];
  tearDown2 [ label="tearDown" ];
  "TestFunc n" -> tearDown2;
  tearDown2 -> tearDownAfterClass;
  tearDown -> setUp2 [ style=dotted ];
}
@enddot


@english
@section suite Suite
@japanese
@section suite スーツ
@endif

@english
How do you set up your tests so that you can run them all at once?
Once you have several tests, organize them into a suite.
@japanese
複数のテストを全部一度に実行することができるように準備するには、
どのようにしたらいいでしょうか？
いくつかのテストを作ったら、
それらをスーツに整理します。
@endif

@dot
digraph StructureCollaboration {
  node [ fontsize=9, fontname=Helvetica ];
  edge [ dir=back, fontsize=9 ];
  subgraph cluster1 {
    fontsize=9;
    fontname=FreeSans
    label="Test Functions"; labelloc=t; labeljust=l;
    style=dashed;
    rank=same;
    setUpBeforeClass;
    setUp;
    TestFunc;
    tearDown;
    tearDownAfterClass;
  }
  TestSuite [ URL="@ref CCUnitTestSuite" ];
  TestCase [ URL="@ref CCUnitTestCase" ];
  TestFunc [ URL="@ref CCUnitTestFunc" ];
  setUpBeforeClass [ URL="@ref CCUnitTestFunc" ];
  setUp [ URL="@ref CCUnitTestFunc" ];
  tearDown [ URL="@ref CCUnitTestFunc" ];
  tearDownAfterClass [ URL="@ref CCUnitTestFunc" ];
  TestSuite -> TestSuite [ label="1..n" ];
  TestSuite -> TestCase [ headlabel="1..n", labeldistance=1, labelangle=-45 ];
  TestCase -> setUpBeforeClass [ headlabel="0..1", labelangle=45 ];
  TestCase -> setUp [ headlabel="0..1", labelangle=45 ];
  TestCase -> TestFunc [ headlabel="1..n", labelangle=-45 ];
  TestCase -> tearDown [ headlabel="0..1", labelangle=-45 ];
  TestCase -> tearDownAfterClass [ headlabel="0..1", labelangle=-45 ];
}
@enddot

@english
CCUnit provides a @link CCUnitTestSuite TestSuite @endlink
module that runs any number of TestFuncs together.
You saw, above, how to run test suite.
@japanese
CCUnit はいくつもの @link CCUnitTestFunc TestFuncs @endlink
を一緒に実行する
@link CCUnitTestSuite TestSuite @endlink モジュールを提供します。
テストスーツを実行する方法はすでに前の方で示してあります。
@endif

@english
To create a suite of two or more tests, you do the following:
@japanese
二つ以上のテストを含む一つのスーツを作るには、次のようにします。
@endif

@dontinclude complex/runTestSuite.c

@english
Create two test cases, and register test functions to each cases.
@japanese
テストケースを二つ生成し、それぞれにテスト関数を登録します。
@endif

@skip main
@until test_complex_div);

@english
Create a test suite,
then register that two test cases to it.
@japanese
テストスーツを生成し、
テストケースを登録します。
@endif

@until testArith);

@english
Create test runner and run the tests.
@japanese
テストランナーを生成しテストを実行します。
@endif

@until }

@english
The sample code made in the above is in the directory <code>examples/complex</code>,
the files are <code>runTestSuite.c</code>, <code>testComplexSetup.c</code>
and <code>testComplexArith.c</code>.

To compile and run, do the following:
@japanese
ここまでのサンプルコードは、<code>examples/complex</code> ディレクトリの
<code>runTestSuite.c, testComplexSetup.c, testComplexArith.c</code>
にあります。

コンパイルおよび実行するには、次のようにします。
@endif

@code
$ gcc -o runTestSuite runTestSuite.c testComplexSetup.c testComplexArith.c complex.c -lccunit
$ ./runTestSuite
......
Time: 0.000061 sec

OK (6 tests)
@endcode

@english
@link CCUnitTestSuite TestSuites @endlink don't only have to
contain @link CCUnitTestCase TestCases @endlink.  They
can also contain @link CCUnitTestSuite TestSuites@endlink.
For example, you can create a
@link CCUnitTestSuite TestSuite @endlink
in your code and I
can create one in mine, and we can run them together by
creating a @link CCUnitTestSuite TestSuite @endlink that
contains both:
@japanese
@link CCUnitTestSuite TestSuites @endlink は
@link CCUnitTestCase TestCases @endlink
を含むだけではありません。
@link CCUnitTestSuite TestSuites @endlink 自身を含むこともできます。
例えば、あなたはあなたのコードに @link CCUnitTestSuite TestSuite @endlink
を作ることができ、
そして私は私のスーツ
を作ることができます、
そして私達は両方ともを含んでいる @link CCUnitTestSuite TestSuite @endlink
を作って、
一緒にそれぞれのスーツを実行することができるのです。
@endif

@code
  CCUnitTestSuite* suite;
  CCUnitTestSuite* suite_a;
  CCUnitTestSuite* suite_b;

  ...

  suite = ccunit_newTestSuite ("complex all test suite");
  suite_a = ccunit_newTestSuite ("complex test suite A");
  suite_b = ccunit_newTestSuite ("complex test suite B");

  ...

  ccunit_addTestSuite (suite, suite_a);
  ccunit_addTestSuite (suite, suite_b);
@endcode

@english
@section helper_tool Helper Tool
@japanese
@section helper_tool ヘルパーツール
@endif

@english
As you might have noticed,
the work to register the test function in the test case
and to register the test case in the test suite is easy
to mistake concerning the repetition.

Actually, though the test function of @c test_complex_to_string() was
defined in @c testComplexSetup.c, it was ignored by the above explanation,
and it didn't register for the test case.

A @ref CreatingTestSuite set of functions and 
command have been created to automatically implements the
creating suite function.
@japanese
お気づきのように、
テストケースにテスト関数を登録したり、
テストスーツにテストケースを登録したりする作業は、
反復的で間違いやすいものです。

例えば @c testComplexSetup.c には
@c test_complex_to_string() というテスト関数が定義されていますが、
今までの説明では無視されていてテストケースには登録されませんでした。

このような登録漏れをなくすために
@ref CreatingTestSuite の関数とコマンドは、
テストケースやテストスーツを登録する関数の実装を、
自動的に作成することができます。
@endif

@english
You make the file which you write the test case in for that as follows.

First, declare the test suite as this in the comment of the javaDoc style.
As for the comment of the javaDoc style, 
the starts of the comment block of the C style are two asterisks "<tt>**</tt>".
@japanese
そのためには、テストケースを書くファイルを次のように作ります。

最初に、テストスーツを宣言します。
これは javaDoc スタイルのコメント内にテストスーツの名前を記述します。
javaDocスタイルのコメントとは C スタイルのコメントブロックの開始が
二つのアスタリスク <tt>**</tt> になっているものです。
@endif

@code
//** test suite: complex test suite *\/
@endcode

@english
Next, define the test cases.
The test case is gathering of the global variables and the functions
that surrounded in the declaration of the end of the test case
with the declaration of the name of the test case written in the comment of the
javaDoc style.

One file can define the multiple test case.
@japanese
次に、
テストケースを定義します。
テストケースは、 javaDoc スタイルのコメントに書かれたテストケースの名前の宣言と
テストケースの終了の宣言で囲まれた、グローバル変数と関数の集まりです。
ひとつのファイルに複数のテストケースを定義できます。
@endif

@code
//** test case: complex test case *\/

static complex_t* c10_1;

//** complex new test *\/
void test_complex_new ()
{
  ...
}

...

//** end test case *\/
//** test case: complex arith test case *\/
...
//** end test case *\/
//** end test suite *\/
//** test suite: ... *\/
...
//** end test suite *\/
@endcode

@english
As for the test function, the name must have begun with test.
You can write the explanation of the test function in the
comment of the javaDoc style before each test function.
If the comment isn't being written, the name of the test
function is registered as an explanation of the function.

There are @c setUp, @c tearDown, @c setUpBeforeClass and
@c tearDownAfterClass as a special test function.
Their works as a functional function of the test case that
Those function as a functional function of the test case which 
I explained before so that you may know it from that name.
Define as the function to begin respectively with such a name.
@japanese
テスト関数は名前が @c test で始まっていなければなりません。
また各テスト関数の前には
javaDoc スタイルのコメントの中にテスト関数の説明を書くことができます。
コメントが書かれていなければ、
テスト関数の名前が関数の説明として登録されます。

特別なテスト関数として @c setUp, @c tearDown, @c setUpBeforeClass,
@c tearDownAfterClass があります。
その名前からわかるように、
以前に説明したテストケースの機能の関数として働きます。
それぞれそのような名前で定義してください。
@endif

@english
To generate creating suite function code, run
<code>ccunit_makeSuite</code> tool.
@japanese
スーツ作成関数のコードを生成するには、
<code>ccunit_makeSuite</code>ツールを実行します。
@endif

@english
The function to make @link CCUnitTestSuite TestSuite
@endlink is <code>ccunit_suite</code>.
But, it can be changed to another
name by the <code>-f</code> option of the
<code>ccunit_makeSuite</code> command, too.
@japanese
自動的に作成される
@link CCUnitTestSuite TestSuite @endlink
を作成する関数は、
デフォルトでは <code>ccunit_suite</code> です、
しかし <code>ccunit_makeSuite</code> コマンドの
<code>-f</code> オプションで別の名前に変えることもできます。
@endif

@code
$ ccunit_makeSuite -f suite_test_complex -o suiteTestComplex.c testComplexSetup.c testComplexArith.c
@endcode

@english
The next is taken to use the code which you generated automatically.
@japanese
自動生成したコードを利用するには次のようにします。
@endif

@dontinclude complex/runTestSuiteAuto.c

@english
Declare the prototype of the function which you generated.
Try not to forget <code>char* name</code> of the argument.
@japanese
生成した関数のプロトタイプを宣言します。
引数の <code>char* name</code> を忘れないようにしてください。
@endif

@skip include
@until extern

@english
Call the function which you generated, and take out the test suite.
@japanese
生成した関数を呼び出してテストスーツを取り出します。
@endif

@skip main
@until suite_test_complex

@english
Run it by the test runner.
@japanese
テストランナーで実行します。
@endif

@until }


@english
The sample code here will be found with 
<code>runTestSuite.c</code>, <code>testComplex.c</code>
and <code>testComplexArith.c</code> of the <code>examples/complex</code>
dhirectory.

To compile and run, do the following:
@japanese
ここまでのサンプルコードは、<code>examples/complex</code> ディレクトリの
<code>runTestSuiteAuto.c</code>, <code>testComplexSetup.c</code>
にあります。

コンパイルおよび実行するには、次のようにします。
@endif

@code
$ ccunit_makeSuite -f suite_test_complex -o suiteTestComplex.c testComplexSetup.c testComplexArith.c
$ gcc -o runTestSuiteAuto runTestSuiteAuto.c testComplexSetup.c testComplexArith.c suiteTestComplex.c complex.c -lccunit
$ ./runTestSuiteAuto
.......
Time: 0.000060 sec

OK (7 tests)
@endcode

@copydetails CCUnitMakeSuite

@english
@section sample_programs Sample Programs
@japanese
@section sample_programs サンプルプログラム
@endif

@english
The sample program made in the above is in the @c examples/complex directory.
@japanese
以上で作成したサンプルプログラムは @c examples/complex ディレクトリにあります。
@endif

@copydetails examples

*/