## Assertion writing helper Assertion writing helper — このセクションにあるシンボルは独自検証を作成することを補助します。 |

## Functions

void | cut_test_pass ()
void | cut_test_fail ()
void | cut_test_fail_va_list ()
void | cut_push_backtrace ()
void | cut_pop_backtrace ()
#define | cut_trace()
#define | cut_trace_with_info_expression()
const char * | cut_append_diff ()
#define | cut_set_expected()
#define | cut_set_actual()
const char * | cut_inspect_string_array ()
cut_boolean | cut_equal_string ()
cut_boolean | cut_equal_double ()
#define | cut_equal_sockaddr()
#define | cut_inspect_sockaddr()
const char * | cut_get_test_directory ()
const char * | cut_get_source_directory ()

## Types and Values

#define | CUT_RELATIVE_PATH

## 説明

読みやすいテストを書くために独自の検証を作成する必要があるでしょう。このセクションのシンボルは独自の検証作成を補助します。

例:

検証

    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
    #ifndef __MY_ASSERTIONS_H__
    #define __MY_ASSERTIONS_H__

    #include <cutter.h>

    #ifdef __cplusplus
    extern "C" {
    #endif

    #define my_assert_equal_int(expected, actual)                    \
        cut_trace_with_info_expression(                              \
            my_assert_equal_int_helper((expected), (actual),         \
                                       # expected, # actual),        \
            my_assert_equal_int(expected, actual, __VA_ARGS__))

    void my_assert_equal_int_help (long expected,
                                   long actual,
                                   const char *expression_expected,
                                   const char *expression_actual);

    #ifdef __cplusplus
    }
    #endif

    #endif

検証

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    #include "my-assertions.h"

    void
    my_assert_equal_int_helper (long expected,
                                long actual,
                                const char *expression_expected,
                                const char *expression_actual)
    {
        if (expected == actual) {
            cut_test_pass();
        } else {
            cut_test_fail(cut_take_printf("<%s == %s
    >\n"
                                          "expected: <%ld
    >\n"
                                          "  actual: <%ld
    >",
                                          expression_expected,
                                          expression_actual,
                                          expected, actual));
        }
    }

Makefile.am:

    1
    2
    3
    4
    5
    AM_CFLAGS = $(CUTTER_CFLAGS)
    LIBS = $(CUTTER_LIBS)
    noinst_LTLIBRARIES = libmy-assertions.la
    libmy_assertions_la_SOURCES = my-assertions.c my-assertions.h
    AM_LDFLAGS = -module -rpath $(libdir) -avoid-version -no-undefined

## Functions

### cut_test_pass ()

    void
    cut_test_pass (void);

検証をパスしたら`cut_test_pass()`を呼んでください。`cut_test_pass()`は検証数を増やします。

Since: 1.0.5

### cut_test_fail ()

    void
    cut_test_fail (const char *system_message,
                   ...);

検証が失敗したら`cut_test_fail()`を呼んでください。`cut_test_fail()`は失敗数を増やし、現在のテストを中断します。

#### Parameters

system_message | テストフレームワーク指定の失敗メッセージ。 |
... | 省略可能な整形文字列。以降のパラメータが整形文字列に挿入されます。（`printf()`と同じ。）このパラメータは0.1.6から非推奨となっています。代わりに`cut_set_message()`を使ってください。 |

Since: 1.0.5

### cut_test_fail_va_list ()

    void
    cut_test_fail_va_list (const char *system_message,
                           const char *user_message_format);

`CPPCUT_END_TEST_DECLS`はバージョン1.1.0から非推奨になりました。新しく書くコードでは使わないでください。代わりにnamespaceを使ってください。

`cut_set_actual()`も見てください。

`cut_test_fail_va_list()`の動作については`cut_test_fail()`を見てください。`user_message_format`は可変長引数の1つ前の引数です。

例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    void
    my_assert(cut_boolean result,
              const gchar *user_message_format,
              ...)
    {
        if (result) {
            cut_test_pass();
        } else {
            cut_test_fail_va_list("Fail!", user_message_format);
        }
    }

#### Parameters

system_message | テストフレームワーク指定の失敗メッセージ。 |
user_message_format | ユーザ指定の失敗メッセージ。 |

Since: 1.0.5

### cut_push_backtrace ()

    void
    cut_push_backtrace (const char *expression);

`expression`と現在のソースの場所をバックトレーススタックにプッシュします。

通常は直接使う必要はありません。`cut_trace()`で十分です。

#### Parameters

呼び出されたと記録される式。 | 呼び出されたことを記録される式。 |

Since: 1.0.6

### cut_pop_backtrace ()

    void
    cut_pop_backtrace (void);

バックトレーススタックからバックトレースをポップします。

通常は直接使う必要はありません。`cut_trace()`で十分です。

Since: 1.0.6

### cut_trace()

    #define             cut_trace(expression)

現在のファイル名、行番号、関数名、`expression`を記憶し、`expression`内で検証が失敗した場合に表示します。`expression`の多くは関数呼び出しになるでしょう。

`expression`の戻り値を取得できないことに注意してください。

`cut_trace()`は以下の通りです。もし、cut_assert_not_null(object)が失敗したら、バックトレースには2行含まれます。cut_assert_not_null(object)とcreate_my_object("my-name")です。

例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    static MyObject *object;

    static void
    create_my_object(const char *name)
    {
        object = my_object_new(name);
        cut_assert_not_null(object);
    }

    void
    test_my_object_name(void)
    {
        cut_trace(create_my_object("my-name"));
        cut_assert_equal_string("my-name",
                                my_object_get_name(object));
    }

テストを読みやすくするために`cut_trace()`を使ったマクロを書くかもしれません: <placeholder-1></placeholder-1>

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    static MyObject *object;

    static void
    create_my_object_helper(const char *name)
    {
        object = my_object_new(name);
        cut_assert_not_null(object);
    }

    #define create_my_object(...)                        \
        cut_trace(create_my_object_helper(__VA_ARGS__))

    void
    test_my_object_name(void)
    {
        create_my_object("my-name");
        cut_assert_equal_string("my-name",
                                my_object_get_name(object));
    }

#### Parameters

呼び出されたと記録される式。 | 呼び出されたことを記録される式。 |

Since: 1.0.5

### cut_trace_with_info_expression()

    #define             cut_trace_with_info_expression(expression, info_expression)

`cut_trace()`と`cut_trace_with_info_expression()`の違いは記録される式が`expression`と同じかどうかです。`cut_trace_with_info_expression()`はバックトレースの読みやすさのために`expression`から情報を隠したいときに便利です。

`cut_trace()`は以下の通りです。もし、cut_assert_not_null(object)が失敗したら、バックトレースには2行含まれます。cut_assert_not_null(object)とcreate_my_object("my-name")です。

- cut_assert_not_null(object)

- create_my_object_helper("my-name")ではなくcreate_my_object("my-name")

`cut_trace_with_info_expression()`の例です。cut_assert_not_null(object)が失敗すると以下の2行を含んだバックトレースが得られます:<placeholder-1></placeholder-1>もし、`cut_trace_with_info_expression()`ではなく`cut_trace()`を使った場合はcreate_my_object_helper("my-name")になります。もし、create_my_object_helper("my-name")が得られたら以下のように混乱してしまうかもしれません。「create_my_object_helper("my-name")はどこからきたんだ？`test_my_object_name()`はcreate_my_object("my-name")は使っているけど、create_my_object_helper("my-name")は使っていないぞ。」

例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    static MyObject *object;

    static void
    create_my_object_helper(const char *name)
    {
        object = my_object_new(name);
        cut_assert_not_null(object);
    }

    #define create_my_object(...)                        \
        cut_trace_with_info_expression(                  \
            create_my_object_helper(__VA_ARGS__),        \
            create_my_object(__VA_ARGS__))

    void
    test_my_object_name(void)
    {
        create_my_object("my-name");
        cut_assert_equal_string("my-name",
                                my_object_get_name(object));
    }

#### Parameters

呼び出されたと記録される式。 | 呼び出されたことを記録される式。 |
info_expression | 呼び出されたと記録される式。 |

Since: 1.0.5

### cut_append_diff ()

    const char *
    cut_append_diff (const char *message,
                     const char *from,
                     const char *to);

`CPPCUT_END_TEST_DECLS`はバージョン1.1.0から非推奨になりました。新しく書くコードでは使わないでください。代わりにnamespaceを使ってください。

`cut_append_diff`はバージョン1.0.9から非推奨になりました。新しく書くコードでは使わないでください。代わりに`cut_set_expected()`と`cut_set_actual()`を使ってください。

`from`と`to`のdiffを計算し、そのdiffを`message`に追加します。戻り値の文字列の所有者はCutterです。

#### Parameters

message | diffが追加される文字列。 |
from | 元の文字列。 |
to | 修正された文字列。 |

#### Returns

`from`と`to`間のdiff付きの`message`。必要なさそうなdiffであれば`message`と同じ。開放しないでください。

Since: 1.0.3

### cut_set_expected()

    #define             cut_set_expected(expected)

次の検証で使う詳細化した期待値オブジェクトを設定します。

期待値オブジェクトと実際値オブジェクトの両方が設定され、それらのdiffが必要な場合は自動的にdiffを生成します。

`cut_set_actual()`も見てください。

#### Parameters

期待するリスト。 | 期待値オブジェクトの詳細。 |

Since: 1.0.9

### cut_set_actual()

    #define             cut_set_actual(actual)

次の検証で使う詳細化した実際値オブジェクトを設定します。

期待値オブジェクトと実際値オブジェクトの両方が設定され、それらのdiffが必要な場合は自動的にdiffを生成します。

`cut_set_expected()`も見てください。

#### Parameters

actual | 実測値オブジェクトの詳細。 |

Since: 1.0.9

### cut_inspect_string_array ()

    const char *
    cut_inspect_string_array (const char **strings);

`strings`を人が読みやすい文字列に整形します。整形された文字列の所有者はCutterです。

#### Parameters

文字列。 | 整形される文字列の配列。 |

#### Returns

Cutterが所有する整形された文字列。解放しないで下さい。

### cut_equal_string ()

    cut_boolean
    cut_equal_string (const char *string1,
                      const char *string2);

`string1`と`string2`を比較します。`string1`あるいは`string2`、または両方が`NULL`でもかまいません。

#### Parameters

文字列。 | 文字列。 |
文字列。 | 文字列。 |

#### Returns

`string1`と`string2`が両方`NULL`、あるいは同じ内容の場合は`CUT_TRUE`、そうでない場合は`CUT_FALSE`。

Since: 1.0.5

### cut_equal_double ()

    cut_boolean
    cut_equal_double (double double1,
                      double double2,
                      double error);

`double1`と`double2`を誤差範囲`error`で比較します。

#### Parameters

double1 | 浮動小数点値。 |
double2 | 浮動小数点値。 |
error | 誤差範囲を示す浮動小数点数。 |

#### Returns

|`double1` - `double2`| <= `error`なら`CUT_TRUE`、そうでなければ`CUT_FALSE`。

Since: 1.0.5

### cut_equal_sockaddr()

    #define cut_equal_sockaddr(address1, address2) CUT_FALSE

`address1`と`address2`を比較します。

この関数はCUT_DISABLE_SOCKET_SUPPORTを定義すると無効にできます。

#### Parameters

address1 | ソケットアドレス。 |
address2 | ソケットアドレス。 |

#### Returns

`sub_process`が異常終了したときは`CUT_TRUE`、そうでない場合は`CUT_FALSE`。

Since: 1.1.1

### cut_inspect_sockaddr()

    #define             cut_inspect_sockaddr(address)

`address`を人が読みやすい文字列に整形します。整形された文字列の所有者はCutterです。

この関数はCUT_DISABLE_SOCKET_SUPPORTを定義すると無効にできます。

#### Parameters

address | 詳細化されるソケットアドレス。 |

#### Returns

Cutterが所有する整形されたソケットアドレス。解放しないで下さい。

Since: 1.1.1

### cut_get_test_directory ()

    const char *
    cut_get_test_directory (void);

コマンドラインで指定されたテストディレクトリ名を返します。

#### Returns

Cutterが所有する文字列。解放しないで下さい。

Since: 1.1.4

### cut_get_source_directory ()

    const char *
    cut_get_source_directory (void);

コマンドラインで指定されたソースディレクトリ名を返します。

#### Returns

Cutterが所有する文字列。解放しないで下さい。

Since: 1.1.5

## Types and Values

### CUT_RELATIVE_PATH

    #  define CUT_RELATIVE_PATH NULL

もし、テスト用の補助ライブラリを共有ライブラリとして使っている場合は、補助ライブラリのソースコード中またはビルドオプション（例: -DCUT_RELATIVE_PATH=\""sub/dir/"\"）でこのマクロを定義してください。もし、このパスが設定されていない場合は`cut_trace()`と`cut_trace_with_info_expression()`で正しいパスが得られません。

説明用のディレクト構成例です。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    --- core-lib/ --- XXX.c # Your core library
     |             +- ...
     |             +- YYY.c
     +- util-lib/ --- AAA.c # Your utility library
     |             +- ...
     |             +- BBB.c
     |
     +- test/ --- core/ --- test-XXX.c # Tests for your core library
               |         +- ...
               |         +- test-YYY.c
               +- util/ --- test-AAA.c # Tests for your utility library
               |         +- ...
               |         +- test-BBB.c
               +- lib/  --- my-assertions.c # Your library of tests.
                         +- my-assertions.h # This library will be used
                         |                  # as shared library of your
                         |                  # tests (test/core/test-*.so
                         |                  # and test/util/test-*.so)
                         +- ...

      % cutter --source-directory=test test

上記の構成例では、test/lib/my-assertions.cでは`CUT_RELATIVE_PATH`を"lib"と定義しなければいけません。これは、:source-directoryコマンドラインオプションで指定した"test"ソースディレクトリからみてlib/ディレクトリにmy-assertions.cがあるからです。

コードとビルドオプションの例です。

    1
    2
    3
    4
    5
    6
    test/lib/my-assertions.c:
      #define CUT_RELATIVE_PATH "lib"
      #include <cutter.h>

    build option:
      % gcc -DCUT_RELATIVE_PATH="\"lib\"" ...

Since: 1.0.6