1 /* -*- Indented-Text -*- */
2 /* Copyright (C) 2003, 2010, 2013 TSUTSUMI Kikuo.
3 This file is part of the CCUnit Library.
5 The CCUnit Library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public License
7 as published by the Free Software Foundation; either version 2.1 of
8 the License, or (at your option) any later version.
10 The CCUnit Library is distributed in the hope that it will be
11 useful, but WITHOUT ANY WARRANTY; without even the implied warranty
12 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public
16 License along with the CCUnit Library; see the file COPYING.LESSER.
17 If not, see <http://www.gnu.org/licenses/>
22 @page cookbook CCUnit Cookbook
24 @page cookbook CCUnit クックブック
28 Here is a short cookbook to help you get started.
30 これは CCUnit を使い始めるにあたって、
31 理解の助けとなるような短いクックブックです。
34 [see also <a href="../ja/cookbook.html">Japanese</a> documents]
36 [see also <a href="../../cookbook.html">English</a> documents]
40 @section simple_test_case Simple Test Case
42 @section simple_test_case シンプルなテストケース
46 Tests in <b>CCUnit</b> can be run automatically. They are
47 easy to set up and once you have written them, they are
48 always there to help you keep confidence in the quality of
51 <b>CCUnit</b> を使ったテストは自動的に実行することができます。
52 CCUnit のテストは簡単にセットアップすることができ、
54 いつでもプログラムの品質を信頼できるものに保つことができるでしょう。
58 To make a simple test, here is what you do:
64 <li> @english Create a test function
68 <li> @english When you want to check a value, call
69 @link CCUNIT_ASSERT(bool) @endlink
70 and pass a bool that is true if the test succeeds
72 ASSERT macro is listed in others as well in
73 @link Assertions Assert Macros@endlink.
76 @link CCUNIT_ASSERT(bool) @endlink
78 テストが成功するなら真を返すような真偽値を渡します。
81 @link Assertions ASSERT マクロ@endlinkにリストしてあります。
87 For example, see the test of the library of the simple
88 complex number as an example.
89 (This sample program is in the @c examples/complex directory)
90 To test whether the initialization of the complex numeber
91 and two complex numbers are equal.
93 例えば、簡単な複素数のライブラリのテストを例にとってみましょう。
94 (ここで使用する@ref sample_programs は
95 @c examples/complex ディレクトリにあります。)
96 複素数を初期化することができたかをテストしたり、
97 二つの複素数が等しいかをテストしたりします。
100 @dontinclude complex/testComplex.c
102 @skip test_complex_new
103 @until test_complex_equals
107 These two test functions are made one test case together,
110 この二つのテスト関数をまとめてひとつのテストケースにして実行することができます。
113 @dontinclude complex/runTestCase.c
116 Include the necessary header files.
118 必要なヘッダファイルをインクルードします。
121 @skip CCUnitTestCase.h
122 @until CCUnitTestResult.h
125 First, Allocate the test case memory.
131 @until ccunit_newTestCase
134 Then, register the test functions in the test case.
135 The assertion should specify the name of the function
136 and the explanation of the function
137 to indicate it at the unsuccessful time.
139 そしてテストケースにテスト関数を登録します。
140 表明 (ASSERT) が失敗した時に表示するための関数名と関数の説明を一緒に指定しています。
143 @until test_complex_equals);
146 Run the test case, and take out the result.
155 Deallocate the memory whitch you assigned,
156 and return the result.
165 You find the sample code made in the above in the
166 files <code>testComplex.c</code> and <code>runTestCase.c</code>
167 in the <code>examples/complex</code> directory.
169 To compile and run, do the following:
171 ここまでのサンプルコードは、@c examples/complex ディレクトリの
172 <code>testComplex.c, runTestCase.c</code> にあります。
174 コンパイルおよび実行するには、次のようにします。
178 $ gcc -o runTestCase runTestCase.c testComplex.c complex.c -lccunit
185 When the test case is run, that specific test functions
186 will be run. This is not a useful thing to do, however, as
187 no diagnostics will be displayed. One will normally use a
188 @ref ExecutingTest to display the results.
194 通常は@ref ExecutingTest で結果を表示します。
198 @section test_runner TestRunner
200 @section test_runner テストランナー
204 How do you run your tests and collect their results?
205 The TestCase store result of own tests into
206 the @link CCUnitTestResult TestResult@endlink.
207 At the same time, the test case informs the
208 @link CCUnitTestRunner TestRunner@endlink
209 of the executive conditionsn of the test.
211 テストを実行したときに、どうやってその結果を集めたら良いでしょうか。
213 @link CCUnitTestFailure TestFailure @endlink を
214 @link CCUnitTestResult TestResult @endlink に格納します。
215 同時にテストの実行状況を @link CCUnitTestRunner TestRunner @endlink
221 node [ fontsize=9, fontname=Helvetica ]
222 edge [ fontsize=9, dir=back ]
223 TestRunner [ URL="@ref CCUnitTestRunner" ];
224 TestRunner -> TestCase [ label="Notify", fontname=Times,
225 style=dotted, arrowhead=vee ];
226 TestRunner -> TestResult [ arrowtail=none ];
228 TestCase [ URL="@ref CCUnitTestCase" ];
229 TestResult [ URL="@ref CCUnitTestResult" ];
230 TestCase -> TestResult [
231 label="TestFailure", fontname=Courier,
232 dir=forward, style=dotted, arrowhead=vee
235 TestFunc [ label="TestFunc 1..n", URL="@ref CCUnitTestFunc" ];
236 TestFailure [ label="TestFailure 0..m", URL="@ref CCUnitTestFailure" ];
237 TestCase -> TestFunc;
238 TestResult -> TestFailure [ arrowtail=odiamond ];
243 Once you have a test suite, you'll want to run it. %CCUnit
244 provides @link ExecutingTest TestRunner @endlink
245 to define the suite to be run and to display
250 CCUnit の @link ExecutingTest TestRunner @endlink は、
251 テストケースをテストスーツにまとめて実行し結果を表示します。
255 To use the @link CCUnitTestRunner TestRunner@endlink,
256 include the header files for the tests in <code>runTestCaseRunner.c</code>:
258 @link CCUnitTestRunner TestRunner @endlink を使用するには、
259 例えば @c runTestCaseRunner.c でテストのためのファイルのヘッダをインクルードします。
262 @dontinclude complex/runTestCaseRunner.c
265 @until CCUnitTestRunner.h
268 First, make the @link CCUnitTestSuite TestSuite@endlink,
269 and register the @link CCUnitTestCase TestCase@endlink.
271 まず @link CCUnitTestSuite TestSuite@endlink を作成し、
272 それに @link CCUnitTestCase TestCase@endlink を登録します。
275 @until ccunit_addTestCase
279 @link ccunit_runTestRunner(CCUnitTestRunner*, CCUnitTestSuite *)@endlink:
281 そして @link ccunit_runTestRunner(CCUnitTestRunner*, CCUnitTestSuite *) @endlink
288 Deallocate the memories.
291 ただし、@c testCase は @c suite に登録してあるので、
292 @c suite を解放する時に一緒に解放されます。
293 そのため @c testCase はここで解放する必要がありません。
294 解放しようとすると Bus error などになりますので注意してください。
300 The sample code made in the above is in the directory <code>examples/complex</code>,
301 the files <code>testComplex.c, complexTestSuite.c</code> and <code>runTestRunner.c</code>.
303 To compile and run, do the following:
305 ここまでのサンプルコードは、<code>examples/complex</code> ディレクトリの
306 <code>runTestCaseRunner.c</code>
309 コンパイルおよび実行するには、次のようにします。
313 $ gcc -o runTestCaseRunner runTestCaseRunner.c testComplex.c complex.c -lccunit
314 $ ./runTestCaseRunner
322 The @link ExecutingTest TestRunner @endlink will run the tests.
323 If all the tests pass, you'll get an informative message.
324 If any fail, you'll get the following information:
326 @link ExecutingTest TestRunner @endlink はテストを実行します。
327 もしすべてのテストがパスすれば、その情報のメッセージが表示されます。
328 上の例では、最初の「<code>..</code>」は実行したテストケースです。
329 実行する直前に「<code>.</code>」が出力されます。
331 実行にかかった時間と実行したテストケースの数が表示されます。
333 どれかが失敗すれば、それについて以下のような情報が表示されます。
338 The name of the source file that contains the test
344 The line number where the failure occurred
350 The name of the test case that failed
356 All of the text inside the call to
357 @link CCUNIT_ASSERT(bool)@endlink which detected the failure
359 失敗を検知した @link CCUNIT_ASSERT(bool)@endlink が呼び出された時の条件の文字列。
365 For example, try to mistake it in the test case
366 of @c testComplex.c on purpose.
368 試しに @c testComplex.c のテストケースでわざと間違えてみましょう。
372 void test_complex_new ()
375 CCUNIT_ASSERT_EQ_DOUBLE (10, c10_1->real);
376 /*CCUNIT_ASSERT_EQ_DOUBLE (1, c10_1->imaginary);*/
377 CCUNIT_ASSERT_EQ_DOUBLE (1.1, c10_1->imaginary);
383 $ gcc -o runTestCaseRunner runTestCaseRunner.c testComplex.c complex.c -lccunit
392 testFailComplex.c:36: complex new test:
393 1.1 == c10_1->imaginary
399 In this example, two test cases are run.
400 Then, you will see that the second is unsuccessful.
402 この例ではテストケースを 2 個実行して、
403 ひとつのテストケースで失敗していることがわかります。
404 最初の「 <code>.F.</code>」では、
405 ひとつ目のテストケースが失敗していることをあらわしています。
408 失敗したファイル名、行番号、テストケースの名前 (<code>complex new test</code>)、
409 表明した条件の文字列 (<code>1.1 == c10_1->imaginary</code>) が表示されます。
413 That was a very simple test. Ordinarily, you'll have many
414 little test cases that you'll want to run on the same set of
415 objects. To do this, use global variables.
420 同じようなデータの集まりを使ってテストを行うでしょう。
421 つまり各テスト関数共通のグローバル変数を使うことになります。
425 @section setUp_and_tearDown setUp and tearDown
427 @section setUp_and_tearDown setUp と tearDown
431 What if you have two or more tests that operate on the same
432 similar set of objects?
435 同じデータの集まりをいくつか使うのではないでしょうか。
440 node [ fontsize=9, fontname=Helvetica ]
441 edge [ fontsize=9, dir=back, arrowtail=vee ]
442 gv [ label="Global Variables", shape=box ]
444 tc1 [ label="Test Case 1" ];
445 tc2 [ label="Test Case 2" ];
446 tcn [ label="Test Case n" ];
449 gv -> tc2 [ weight=8 ];
451 tc2 -> tcn [ label="...", fontname=Helvetica, dir=none, color=white ];
456 Tests need to run against the background of a known set of
458 you are writing tests you will often find that you spend
459 more time writing the code to set up the data than you do
460 in actually testing values.
462 テストは中身のわかっているデータの集まりを前提として実行される必要があります。
470 In the sample code of the previous section,
471 some complex numbers are allocated,
475 いくつかの複素数を割り当てたり解放したりしています。
479 Often, you will be able to use the same data for several
480 different tests. Each case will assign slightly different
481 values to the data and will check for
483 Then, if the test is finished, clean-up the data.
484 The function @c setUp and @c tearDown are used at such time.
486 多くの場合、いくつかの異なったテストのために同じグローバル変数を使うことができます。
487 それぞれのテスト関数を実行する前に変数を初期化し、
489 そしてテストが終わったら後始末することになります。
491 @c setUp と @c tearDown 関数はそのような場合に使用することができます。
495 digraph TestFixture {
496 node [ fontsize=9, fontname=Helvetica ]
497 edge [ fontsize=9, dir=back, arrowtail=vee ]
499 gv [ label="Global Variables", shape=box ]
501 su [ label="setUp" ];
502 tc [ label="TestCase" ];
503 td [ label="tearDown" ];
505 gv -> su [ label="initialize" ];
506 gv -> tc [ label="access" ];
507 gv -> td [ label="clean-up" ];
512 When you have a common global variables, here is what you do:
514 もし各テストに共通のグローバル変数があれば、
518 @dontinclude complex/testComplexSetup.c
521 Define the global variable.
530 Write the function @c setUp to allocate the complex.
532 複素数を割り当てる @c setUp 関数を書きます。
538 Write the function @c tearDown to delete the memory of that complex.
540 割り当てたメモリを解放する @c tearDown 関数を書きます。
546 Write the test function.
551 @until test_complex_equals
555 Register the function @c setUp and @c tearDown.
556 At this time, the name of the function must have begun with
557 @c "setUp" or @c "tearDown".
559 @c setUp と @c tearDown を登録します。
560 この時、関数の名前が @c setUp/tearDown で始まっていなければなりません。
563 @dontinclude complex/runTestCaseSetup.c
565 @until setUp_test_complex);
566 @until tearDown_test_complex);
569 Run the test case, and return the result.
578 The sample code made in the above is in the directory <code>examples/complex</code>,
579 the files are @c testComplexSetup.c and <code>runTestCaseSetup.c</code>.
581 To compile and run, do the following:
583 ここまでのサンプルコードは、@c examples/complex ディレクトリの
584 <code>testComplexSetup.c, runTestCaseSetup.c</code> にあります。
586 コンパイルおよび実行するには、次のようにします。
590 $ gcc -o runTestCaseSetup runTestCaseSetup.c testComplexSetup.c complex.c -lccunit
599 @section one_time_setUp_tearDown setUp/tearDown of only one time
601 @section one_time_setUp_tearDown 一回だけの setUp/tearDown
605 In the previous section,
606 the initialization was done in every test every time.
607 But we do the initialization only once,
608 and we may run the multiple test.
609 Then, only when all the tests are finished,
610 it may seem to carry out the code for the settlement.
612 You register the @c setUpBeforeClass and @c tearDownAfterClass
613 function in the test case for that.
614 Then, the test functions are run in the following order:
616 前の節ではテストごとに毎回初期化を行っていました。
620 そしてテストが全て終わったときだけ後始末のコードを実行するような場合があります。
623 @c setUpBeforeClass, @c tearDownAfterClass 関数を登録します。
624 すると次のような順序でテスト関数が実行されます。
628 digraph TestCaseCallingSequence {
629 node [ fontsize=9, fontname=Helvetica ]
634 setUp2 [ label="setUp" ];
636 setUpBeforeClass -> setUp [ weight=8 ];
637 setUpBeforeClass -> setUp2 [ style=invis ];
638 setUp -> "TestFunc 1" [ weight=8 ];
639 "TestFunc 1" -> tearDown [ weight=8 ];
640 setUp2 -> "TestFunc n" [ weight=8 ];
641 tearDown2 [ label="tearDown" ];
642 "TestFunc n" -> tearDown2;
643 tearDown2 -> tearDownAfterClass;
644 tearDown -> setUp2 [ style=dotted ];
656 How do you set up your tests so that you can run them all at once?
657 Once you have several tests, organize them into a suite.
659 複数のテストを全部一度に実行することができるように準備するには、
666 digraph StructureCollaboration {
667 node [ fontsize=9, fontname=Helvetica ];
668 edge [ dir=back, fontsize=9 ];
672 label="Test Functions"; labelloc=t; labeljust=l;
681 TestSuite [ URL="@ref CCUnitTestSuite" ];
682 TestCase [ URL="@ref CCUnitTestCase" ];
683 TestFunc [ URL="@ref CCUnitTestFunc" ];
684 setUpBeforeClass [ URL="@ref CCUnitTestFunc" ];
685 setUp [ URL="@ref CCUnitTestFunc" ];
686 tearDown [ URL="@ref CCUnitTestFunc" ];
687 tearDownAfterClass [ URL="@ref CCUnitTestFunc" ];
688 TestSuite -> TestSuite [ label="1..n" ];
689 TestSuite -> TestCase [ headlabel="1..n", labeldistance=1, labelangle=-45 ];
690 TestCase -> setUpBeforeClass [ headlabel="0..1", labelangle=45 ];
691 TestCase -> setUp [ headlabel="0..1", labelangle=45 ];
692 TestCase -> TestFunc [ headlabel="1..n", labelangle=-45 ];
693 TestCase -> tearDown [ headlabel="0..1", labelangle=-45 ];
694 TestCase -> tearDownAfterClass [ headlabel="0..1", labelangle=-45 ];
699 CCUnit provides a @link CCUnitTestSuite TestSuite @endlink
700 module that runs any number of TestFuncs together.
701 You saw, above, how to run test suite.
703 CCUnit はいくつもの @link CCUnitTestFunc TestFuncs @endlink
705 @link CCUnitTestSuite TestSuite @endlink モジュールを提供します。
706 テストスーツを実行する方法はすでに前の方で示してあります。
710 To create a suite of two or more tests, you do the following:
712 二つ以上のテストを含む一つのスーツを作るには、次のようにします。
715 @dontinclude complex/runTestSuite.c
718 Create two test cases, and register test functions to each cases.
720 テストケースを二つ生成し、それぞれにテスト関数を登録します。
724 @until test_complex_div);
728 then register that two test cases to it.
737 Create test runner and run the tests.
739 テストランナーを生成しテストを実行します。
745 The sample code made in the above is in the directory <code>examples/complex</code>,
746 the files are <code>runTestSuite.c</code>, <code>testComplexSetup.c</code>
747 and <code>testComplexArith.c</code>.
749 To compile and run, do the following:
751 ここまでのサンプルコードは、<code>examples/complex</code> ディレクトリの
752 <code>runTestSuite.c, testComplexSetup.c, testComplexArith.c</code>
755 コンパイルおよび実行するには、次のようにします。
759 $ gcc -o runTestSuite runTestSuite.c testComplexSetup.c testComplexArith.c complex.c -lccunit
768 @link CCUnitTestSuite TestSuites @endlink don't only have to
769 contain @link CCUnitTestCase TestCases @endlink. They
770 can also contain @link CCUnitTestSuite TestSuites@endlink.
771 For example, you can create a
772 @link CCUnitTestSuite TestSuite @endlink
774 can create one in mine, and we can run them together by
775 creating a @link CCUnitTestSuite TestSuite @endlink that
778 @link CCUnitTestSuite TestSuites @endlink は
779 @link CCUnitTestCase TestCases @endlink
781 @link CCUnitTestSuite TestSuites @endlink 自身を含むこともできます。
782 例えば、あなたはあなたのコードに @link CCUnitTestSuite TestSuite @endlink
786 そして私達は両方ともを含んでいる @link CCUnitTestSuite TestSuite @endlink
788 一緒にそれぞれのスーツを実行することができるのです。
792 CCUnitTestSuite* suite;
793 CCUnitTestSuite* suite_a;
794 CCUnitTestSuite* suite_b;
798 suite = ccunit_newTestSuite ("complex all test suite");
799 suite_a = ccunit_newTestSuite ("complex test suite A");
800 suite_b = ccunit_newTestSuite ("complex test suite B");
804 ccunit_addTestSuite (suite, suite_a);
805 ccunit_addTestSuite (suite, suite_b);
809 @section helper_tool Helper Tool
811 @section helper_tool ヘルパーツール
815 As you might have noticed,
816 the work to register the test function in the test case
817 and to register the test case in the test suite is easy
818 to mistake concerning the repetition.
820 Actually, though the test function of @c test_complex_to_string() was
821 defined in @c testComplexSetup.c, it was ignored by the above explanation,
822 and it didn't register for the test case.
824 A @ref CreatingTestSuite set of functions and
825 command have been created to automatically implements the
826 creating suite function.
830 テストスーツにテストケースを登録したりする作業は、
833 例えば @c testComplexSetup.c には
834 @c test_complex_to_string() というテスト関数が定義されていますが、
835 今までの説明では無視されていてテストケースには登録されませんでした。
838 @ref CreatingTestSuite の関数とコマンドは、
839 テストケースやテストスーツを登録する関数の実装を、
844 You make the file which you write the test case in for that as follows.
846 First, declare the test suite as this in the comment of the javaDoc style.
847 As for the comment of the javaDoc style,
848 the starts of the comment block of the C style are two asterisks "<tt>**</tt>".
850 そのためには、テストケースを書くファイルを次のように作ります。
853 これは javaDoc スタイルのコメント内にテストスーツの名前を記述します。
854 javaDocスタイルのコメントとは C スタイルのコメントブロックの開始が
855 二つのアスタリスク <tt>**</tt> になっているものです。
859 //** test suite: complex test suite *\/
863 Next, define the test cases.
864 The test case is gathering of the global variables and the functions
865 that surrounded in the declaration of the end of the test case
866 with the declaration of the name of the test case written in the comment of the
869 One file can define the multiple test case.
873 テストケースは、 javaDoc スタイルのコメントに書かれたテストケースの名前の宣言と
874 テストケースの終了の宣言で囲まれた、グローバル変数と関数の集まりです。
875 ひとつのファイルに複数のテストケースを定義できます。
879 //** test case: complex test case *\/
881 static complex_t* c10_1;
883 //** complex new test *\/
884 void test_complex_new ()
891 //** end test case *\/
892 //** test case: complex arith test case *\/
894 //** end test case *\/
895 //** end test suite *\/
896 //** test suite: ... *\/
898 //** end test suite *\/
902 As for the test function, the name must have begun with test.
903 You can write the explanation of the test function in the
904 comment of the javaDoc style before each test function.
905 If the comment isn't being written, the name of the test
906 function is registered as an explanation of the function.
908 There are @c setUp, @c tearDown, @c setUpBeforeClass and
909 @c tearDownAfterClass as a special test function.
910 Their works as a functional function of the test case that
911 Those function as a functional function of the test case which
912 I explained before so that you may know it from that name.
913 Define as the function to begin respectively with such a name.
915 テスト関数は名前が @c test で始まっていなければなりません。
917 javaDoc スタイルのコメントの中にテスト関数の説明を書くことができます。
919 テスト関数の名前が関数の説明として登録されます。
921 特別なテスト関数として @c setUp, @c tearDown, @c setUpBeforeClass,
922 @c tearDownAfterClass があります。
924 以前に説明したテストケースの機能の関数として働きます。
925 それぞれそのような名前で定義してください。
929 To generate creating suite function code, run
930 <code>ccunit_makeSuite</code> tool.
933 <code>ccunit_makeSuite</code>ツールを実行します。
937 The function to make @link CCUnitTestSuite TestSuite
938 @endlink is <code>ccunit_suite</code>.
939 But, it can be changed to another
940 name by the <code>-f</code> option of the
941 <code>ccunit_makeSuite</code> command, too.
944 @link CCUnitTestSuite TestSuite @endlink
946 デフォルトでは <code>ccunit_suite</code> です、
947 しかし <code>ccunit_makeSuite</code> コマンドの
948 <code>-f</code> オプションで別の名前に変えることもできます。
952 $ ccunit_makeSuite -f suite_test_complex -o suiteTestComplex.c testComplexSetup.c testComplexArith.c
956 The next is taken to use the code which you generated automatically.
958 自動生成したコードを利用するには次のようにします。
961 @dontinclude complex/runTestSuiteAuto.c
964 Declare the prototype of the function which you generated.
965 Try not to forget <code>char* name</code> of the argument.
968 引数の <code>char* name</code> を忘れないようにしてください。
975 Call the function which you generated, and take out the test suite.
977 生成した関数を呼び出してテストスーツを取り出します。
981 @until suite_test_complex
984 Run it by the test runner.
993 The sample code here will be found with
994 <code>runTestSuite.c</code>, <code>testComplex.c</code>
995 and <code>testComplexArith.c</code> of the <code>examples/complex</code>
998 To compile and run, do the following:
1000 ここまでのサンプルコードは、<code>examples/complex</code> ディレクトリの
1001 <code>runTestSuiteAuto.c</code>, <code>testComplexSetup.c</code>
1004 コンパイルおよび実行するには、次のようにします。
1008 $ ccunit_makeSuite -f suite_test_complex -o suiteTestComplex.c testComplexSetup.c testComplexArith.c
1009 $ gcc -o runTestSuiteAuto runTestSuiteAuto.c testComplexSetup.c testComplexArith.c suiteTestComplex.c complex.c -lccunit
1010 $ ./runTestSuiteAuto
1017 @copydetails CCUnitMakeSuite
1020 @section sample_programs Sample Programs
1022 @section sample_programs サンプルプログラム
1026 The sample program made in the above is in the @c examples/complex directory.
1028 以上で作成したサンプルプログラムは @c examples/complex ディレクトリにあります。
1031 @copydetails examples