## Cutter Cutter — C言語・C++言語用単体テストフレームワーク |

## Functions

void | setup ()
void | cut_setup ()
void | teardown ()
void | cut_teardown ()
void | cut_startup ()
void | cut_shutdown ()
#define | cut_add_data()
#define | cut_add_data_backward_compatibility()
void | cut_set_attributes ()
CutTestContext * | cut_get_current_test_context ()
void | cut_set_current_test_context ()
void | cut_set_message ()
void | cut_set_message_va_list ()
void | cut_keep_message ()
void | cut_message ()

## Types and Values

#define | CUT_EXPORT

## 説明

Cutter is a Unit Testing Framework for C and C++ and has the following features:

- 簡単に使えます。Cutterではテストプログラム中にCUTTER_DEFINE_TEST_STARTやCUTTER_DEFINE_TEST_ENDなどといった不思議なマクロを使う必要がありません。通常のプログラムと同じようにテストプログラムを書くことができます。ただし、プログラムが期待した通り動作していることを検証するために`cut_assert_XXX()`を使う必要があります。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      #include <cutter.h>
      #include "my-stack.h"

      void
      test_my_stack (void)
      {
          MyStack *stack = my_stack_new();

          cut_assert_not_null(stack);
          cut_assert(my_stack_is_empty(stack));
          cut_assert_equal_int(0, my_stack_get_size(stack));

          my_stack_push(stack, 10);
          cut_assert(!my_stack_is_empty(stack));
          cut_assert_equal_int(1, my_stack_get_size(stack));

          my_stack_push(stack, 20);
          cut_assert_equal_int(2, my_stack_get_size(stack));

          cut_assert_equal(20, my_stack_pop(stack));
          cut_assert(!my_stack_is_empty(stack));
          cut_assert_equal_int(1, my_stack_get_size(stack));

          cut_assert_equal(10, my_stack_pop(stack));
          cut_assert(my_stack_is_empty(stack));
          cut_assert_equal_int(0, my_stack_get_size(stack));
      }

- 簡素ですが有用な情報を出力をします。Cutterはデフォルトではテストが問題なく動いているときは静かに動きます。以下は、Cutter自身のテストの出力です。

      1
      2
      3
      4
      5
      ...........................................................

      Finished in 0.213021 seconds

      59 test(s), 246 assertion(s), 0 failure(s), 0 error(s), 0 pending(s), 0 notification(s)

  Cutterはテストが1つパスしたことを示すためには「.」だけを出力し、最後にテスト結果の要約を出力します。Cutterは各テストの名前や何個検証したかなどの情報は表示しません。これは、テスト成功時にはこれらの情報は必要ないからです。

  Cutterは失敗時にはたくさんの情報を出力します。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      .....................F.....................................

      1) Failure: test_error
      <"Strange" == cut_test_result_get_test_name(result)>
      expected: <Strange!!!>
       but was: <dummy-error-test>
      test/test-cut-assertions.c:240: cut_assert_test_result()

      Finished in 0.223657 seconds

      59 test(s), 242 assertion(s), 1 failure(s), 0 error(s), 0 pending(s), 0 notification(s)

  上記の結果はCutterの自己テストにおかしな期待値を追加したために起きています。

      1
      cut_assert_equal_string("Strange!!!", cut_test_result_get_test_name(result));

  おかしな検証はtest/test-cut-assertions.cの240行目に書かれていて、その行は`cut_assert_test_result()`関数内にあります。この関数はtest_errorテストから呼び出されています。cut_test_result_get_test_name(result)が"Strange!!!"を返すことを期待していますが、実際は"dummy-error-name"が返ってきています。このような情報を上記のCutterの出力から得ることができます。これはデバッグの手助けになるでしょう。

  Cutterの出力形式は実用的です。' but was:'はその上の'expected:'と並ぶようにインデントされています。これは期待値と実測値をパッと見て簡単に比較できるようにするためです。問題のあった行は「ファイル名:行: 関数」というように整形されています。これはEmacsと連携するためです。Emacsのcompilation-modeではこの形式が*compilation*バッファに表れると、next-errorコマンド(C-x `)で「ファイル名」の「行」へジャンプすることができます。これは問題行を素早く見つける手助けをします。

  Cutterは簡単にテストを書くことを支援するだけではなく、簡単にデバッグをできることも支援します。

## Functions

### setup ()

    void
    setup (void);

`setup` has been deprecated since version 1.0.7 and should not be used in newly-written code.

Use `cut_setup()` instead.

テストプログラム中で`setup()`を定義していたら、cutterは各テストが実行される前に定義された`setup()`を呼びだします。`cut_setup()`が定義されていた場合は、`setup()`は無視されます。

### cut_setup ()

    void
    cut_setup (void);

テストプログラム中で`cut_setup()`を定義していたら、cutterは各テストが実行される前に定義された`cut_setup()`を呼びだします。`cut_setup()`と`setup()`が定義されていた場合は`cut_setup()`だけが使われます。

Since: 1.0.6

### teardown ()

    void
    teardown (void);

`teardown` has been deprecated since version 1.0.7 and should not be used in newly-written code.

Use `cut_teardown()` instead.

テストプログラム中で`teardown()`を定義していたら、cutterは各テストの後に、たとえテストが失敗していた時でも、`teardown()`を呼びだします。`cut_teardown()`が定義されていた場合は、`teardown()`は無視されます。

### cut_teardown ()

    void
    cut_teardown (void);

テストプログラム中で`cut_teardown()`を定義していたら、cutterは各テストの後に、たとえテストが失敗していた時でも、`cut_teardown()`を呼びだします。`cut_teardown()`と`teardown()`が定義されていた場合は`cut_teardown()`だけが使われます。

Since: 1.0.6

### cut_startup ()

    void
    cut_startup (void);

テストプログラム中で`cut_startup()`を定義していたら、cutterは各テストケースが実行される前に定義された`cut_startup()`を呼びだします。`cut_startup()`と`startup()`が定義されていた場合は`cut_startup()`だけが使われます。

Since: 1.0.6

### cut_shutdown ()

    void
    cut_shutdown (void);

テストプログラム中で`shutdown()`を定義していたら、cutterは各テストケースが実行された後に定義された`shutdown()`を呼びだします。`cut_shutdown()`と`shutdown()`が定義されていた場合は`cut_shutdown()`だけが使われます。

Since: 1.0.6

### cut_add_data()

    #define             cut_add_data(first_data_name, ...)

データ駆動テストで使うデータを追加します。

例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    #include <cutter.h>

    void data_translate (void);
    void test_translate (const void *data);

    static const char*
    translate (int input)
    {
       switch(input) {
       case 1:
           return "first";
       case 111:
           return "a hundred eleven";
       default:
           return "unsupported";
       }
    }

    typedef struct _TranslateTestData
    {
        char *translated;
        int input;
    } TranslateTestData;

    static TranslateTestData *
    translate_test_data_new (char *translated, int input)
    {
        TranslateTestData *data;

        data = malloc(sizeof(TranslateTestData));
        data->translated = strdup(translated);
        data->input = input;

        return data;
    }

    static void
    translate_test_data_free (TranslateTestData *data)
    {
        free(data->translated);
        free(data);
    }

    void
    data_translate(void)
    {
        cut_add_data("simple data",
                     translate_test_data_new("first", 1),
                     translate_test_data_free,
                     "complex data",
                     translate_test_data_new("a hundred eleven", 111),
                     translate_test_data_free,
                     NULL);
    }

    void
    test_translate(const void *data)
    {
         const TranslateTestData *test_data = data;

         cut_assert_equal_string(test_data->translated,
                                 translate(test_data->input));
    }

#### Parameters

first_data_name | 最初のデータ名。 |
... | 最初のデータとデータ破棄関数。続けて任意の数の「名前・データ・データ破棄関数(CutDestroyFunction)」の三つ組を指定します。1.0.6から可変長の引数は`NULL`終端しなければいけなくなりました。 |

Since: 1.0.3

### cut_add_data_backward_compatibility()

    #define             cut_add_data_backward_compatibility(context, ...)

`cut_add_data_backward_compatibility`は非推奨です。新しいコードでは使わないでください。

### cut_set_attributes ()

    void
    cut_set_attributes (const char *first_attribute_name,
                        ...);

テストの属性を設定します。

例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    #include <cutter.h>

    void attributes_repeat (void);
    void test_repeat (void);

    void
    attributes_repeat(void)
    {
        cut_set_attributes("description", "a test for repeat function",
                           "bug", "111",
                           "priority", "high",
                           NULL);
    }

    void
    test_repeat(void)
    {
         cut_assert_equal_string_with_free("XXX", repeat("X", 3));
    }

#### Parameters

first_attribute_name | 最初の属性名。 |
... | 最初の属性値です。その後に任意個数の名前と値のペアが続きます。1.0.7から`NULL`終端が必須になりました。 |

Since: 1.0.4

### cut_get_current_test_context ()

    CutTestContext *
    cut_get_current_test_context (void);

現在のテストコンテキストを返します。「現在のテストコンテキスト」はスレッドローカルなオブジェクトです。もしテストの中で新しいスレッドを作らない場合はテストコンテキストを気にする必要はありません。新しいスレッドを作る場合だけ必要になります。テストのスレッドが持っている「現在のテストコンテキスト」を新しく作ったスレッドに渡す必要がありません。

例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    int
    your_thread_function(void *data)
    {
        CutTestContext *test_context = data;
        cut_set_current_test_context(test_context);
        ...
    }

    void
    run_your_thread(void)
    {
        int result;
        pthread_t your_thread;

        result = pthread_create(&your_thread, NULL,
                                your_thread_function,
                                cut_get_current_test_context());
        ...
    }

#### Returns

CutTestContextオブジェクト。

Since: 1.0.4

### cut_set_current_test_context ()

    void
    cut_set_current_test_context (CutTestContext *test_context);

現在のテストコンテキストを`test_context`にします。詳細は`cut_get_current_test_context()`を見てください。

#### Parameters

test_context | 現在のテストコンテキストになるCutTestContext。 |

Since: 1.0.4

### cut_set_message ()

    void
    cut_set_message (const char *format,
                     ...);

`cut_set_message` has been deprecated since version 1.1.0 and should not be used in newly-written code.

Use `cut_message()` instead.

次の検証で使われるメッセージです。

#### Parameters

format | 整形文字列。`printf()`のドキュメントを見てください。 |
... | 整形文字列に挿入されるパラメータ。 |

Since: 1.0.6

### cut_set_message_va_list ()

    void
    cut_set_message_va_list (const char *format,
                             va_list args);

`cut_set_message_va_list` has been deprecated since version 1.1.0 and should not be used in newly-written code.

Use `cut_message()` instead.

次の検証で使われるメッセージです。

#### Parameters

format | 整形文字列。`printf()`のドキュメントを見てください。 |
args | 整形文字列に挿入されるパラメータ。 |

Since: 1.0.6

### cut_keep_message ()

    void
    cut_keep_message (void);

`cut_keep_message` has been deprecated since version 1.1.0 and should not be used in newly-written code.

Use `cut_message()` instead.

`cut_set_message()`または`cut_set_message_va_list()`で設定した現在のメッセージを次の検証の後でも維持します。

Since: 1.0.6

### cut_message ()

    void
    cut_message (const char *format,
                 ...);

追加の検証メッセージを指定します。

例:

    1
    2
    cut_assert_equal_string("abc", "def",
                            cut_message("should fail!"));

#### Parameters

format | 整形文字列。`printf()`のドキュメントを見てください。 |
... | 整形文字列に挿入されるパラメータ。 |

Since: 1.1.0

## Types and Values

### CUT_EXPORT

    #  define CUT_EXPORT __declspec(dllexport)

公開関数であるというしるしをつけます。このしるしはWindows環境上でだけ必要です。Windows上でもテストを実行したい場合はこのマクロを使う必要があります。そうでなければ使う必要はありません。

例:

    1
    2
    3
    4
    5
    CUT_EXPORT void
    test_add (void)
    {
      ...
    }

Since: 1.1.2

## 参考

検証