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

## 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

## 説明

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

例:

my-assertions.h:

    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

my-assertions.c:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    #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);

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

Use `cut_test_fail()` instead.

`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

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

Since: 1.0.6

### cut_pop_backtrace ()

    void
    cut_pop_backtrace (void);

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

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

Since: 1.0.6

### cut_trace()

    #define             cut_trace(expression)

Mark the current file, line, function and `expression` and show it when assertion is failed in `expression` . Most of `expression` will be function call.

Note that you can't get return value of `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));
    }

You will use `cut_trace()` with macro for test readability:

    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

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

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`から情報を隠したいときに便利です。

Here is an example of `cut_trace_with_info_expression()`. If cut_assert_not_null(object) is failed, you will get a backtrace that contains two line:

- cut_assert_not_null(object)

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

If you use `cut_trace()` instead of `cut_trace_with_info_expression()`, you will get create_my_object_helper("my-name"). You may be confused about 'Where is create_my_object_helper("my-name") from? `test_my_object_name()` uses create_my_object("my-name") but does not use 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

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

Since: 1.0.5

### cut_append_diff ()

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

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

Use `cut_set_expected()` and `cut_set_actual()` instead.

Computes diff between `from` and `to` and append the diff to `message` . Returned string is owned by 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

expected | 期待値オブジェクトの詳細。 |

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

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

#### Returns

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

### cut_equal_string ()

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

Compare `string1` to `string2` . `string1` and/or `string2` maybe `NULL`.

#### Parameters

string1 | 文字列。 |
string2 | 文字列。 |

#### 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

`CUT_TRUE` if |`double1` - `double2` | <= `error` ; `CUT_FALSE` otherwise.

Since: 1.0.5

### cut_equal_sockaddr()

    #define cut_equal_sockaddr(address1, address2) CUT_FALSE

Compare `address1` to `address2` .

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

#### Parameters

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

#### Returns

`CUT_TRUE` if `address1` == `address2` , `CUT_FALSE` otherwise.

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