Boost logo

Boost Test Library: Test Tools

Introduction
Benefits
Specification

BOOST_CHECKPOINT
BOOST_WARN
BOOST_CHECK
BOOST_CHECK_EQUAL
BOOST_CHECK_CLOSE
BOOST_REQUIRE
BOOST_MESSAGE
BOOST_WARN_MESSAGE
BOOST_CHECK_MESSAGE
BOOST_REQUIRE_MESSAGE
BOOST_CHECK_PREDICATE
BOOST_REQUIRE_PREDICATE
BOOST_ERROR
BOOST_FAIL
BOOST_CHECK_THROW
BOOST_CHECK_EQUAL_COLLECTIONS
BOOST_IS_DEFINED
output_test_stream
Depricated Boost.Test v1 test tools

Example and Test Programs
Design

Introduction

Boost Test Library の Test Tools はテス トプログラムの作成と保守を容易にするためのツール群を提供する。このツー ル群はマクロと関数宣言という形で提供されている。これらの関数を直接呼 び出すこともできるが、Test Toolsを使うには通常、使い易いマクロを介し て行われる。マクロ引数はすべて1回だけ計算され、複雑な式も安全に渡す ことができる。マクロを使用することにより、エラーが発生した場合その ファイル名・行番号を出力する。Boost Test Library のTest Tools はライ ブラリは製品プログラム向けというよりはテストコード用のものであり、エ ラーを検知して報告するには、例外の発生、assert()または BOOST_STATIC_ASSERT()の使用などが適している。reference to the top Test Tools を使用するには、Program Execution Monitor またはUnit Test Frameworkのいずれかとリンクする必要がある。

Benefits

Test Tools を使用することによりテストプロ グラムを簡単に作成でき、その上統一形式でエラーを報告できる。

Specification

BOOST_CHECKPOINT( message )

このテストツールはテストの流れに、チェックポイントで印を付けるときに使用する。チェックポイントを付けることにより、ランタイム例外の起きた場所を探し出す時に便利である。

Example: test.cpp

int test_main( int, char* [] ) {
    BOOST_CHECKPOINT( "Going to throw an exception" );
    throw "some error";

    return 0;
}

Output:

Exception in test_main : C string:some_error
test.cpp(2) : last checkpoint: Going to throw an exception

reference to the top

BOOST_WARN( predicate )

このテストツールは述語の弱い検証を行う場合に使用する。述語が真である場合テストツールは確認メッセージを出力する。それ以外の場合"warning in ...: condition <predicate> is not satisfied"のような形式で警告メッセージを出力する。

Example: test.cpp

int test_main( int, char* [] ) {
    BOOST_WARN( sizeof(int) == sizeof(short) );

    return 0;
}

Output:

test.cpp(2) : warning in test_main: condition sizeof(int) == sizeof(short) is not satisfied reference to the top

BOOST_CHECK( predicate )

このテストツールは述語値を検証する場合に使用する。述語が真である場合テストツールは確認メッセージを出力する(テスト出力ストリームに出力されるメッセージをうまく処理することで、適切なログレベルを設定できる。以降注意すること)。それ以外の場合エラーメッセージを"error in ...: test <predicate> fail" のような形式で出力する。

Example: test.cpp

int test_main( int, char* [] ) {
    int i=2;
    BOOST_CHECK( i == 1 );

    return 0;
}

Output:

test.cpp(3) : error in test_main: test i==1 failed reference to the top

BOOST_CHECK_EQUAL( left, right )

BOOST_CHECK( left == right ) と同じ。このテストツールを使用することにより、2つの値の不一致を検出できる。

Example: test.cpp

int test_main( int, char* [] ) {
    int i = 2;
    int j = 1;
    BOOST_CHECK_EQUAL( i, j );

    return 0;
}

Output:

test.cpp(4) : error in test_main: test i == j failed [2 != 1] reference to the top

BOOST_CHECK_CLOSE( left, right, tolerance_src )

このテストツールは、close_at_tolerance( tolerance_src )記述で定義された、leftとright の強関連性について検証する。弱関連性の検証を行う場合には、 BOOST_CHECK_PREDICATEを使う。 floating_point_comparison.hpp を自分でインクルードする必要があることに注意せよ。テストツールはこのファイルに依存しているが、コード依存度を最小化するため、敢えてインクルードをしていない。

Example: test.cpp

int test_main( int, char* [] ) {
    double v1 = 1.23456e-10;
    double v2 = 1.23457e-10;

    BOOST_CHECK_CLOSE( v1, v2, 1e-6 ); // 与えられた許容範囲を越えた場合、失敗

    return 0;
}

Output:

test.cpp(4) : error in test_main: test v1 (==) v2 failed [1.23456e-10 != 1.23457e-10 (1e-06)]

Example: test.cpp

int test_main( int, char* [] ) {
    double v1 = 4.1;

    v1 = v1 * v1;
    BOOST_CHECK_CLOSE( v1, 16.81, 1+2 );
    // 1(算術演算) + 
    // 2(10進数から2進数への変換) - 
    // 丸め誤差数; 成功するはず

    return 0;
}

Output: reference to the top

BOOST_REQUIRE( predicate )

このテストツールは述語値を検証する場合に使用する。述語がである場合、テストツールは確認メッセージを出力する。それ以外の場合、エラーメッセージを" fatal error in ...: test <predicate> fail" とう形式で出力し、そのテストケースプロセスを中断する。

Example: test.cpp

int test_main( int, char* [] ) {
    int i = 3;
    BOOST_REQUIRE( i > 5 );
    BOOST_CHECK( i == 6 ); // ここには到達しない

    return 0;
}

Output:

test.cpp(3) : fatal error in test_main: test i>5 failed reference to the top

BOOST_MESSAGE( message )

このテストツールは、テスト出力ストリームにメッセージを出力する場合に使用する。メッセージ引数としては、あらゆる型、またはそれらを<<を使って連結したものが有効である。

Example: test.cpp

struct A {
    friend std::ostream& operator<<( std::ostream& str, A const& a ) {
        str << "struct A";
        
        return str;
    }
};

int test_main( int, char* [] ) {
    BOOST_MESSAGE( "Starting test" );

    int i = 2;
    BOOST_MESSAGE( "i=" << i );

    BOOST_MESSAGE( "still testing..." );

    struct A a;
    BOOST_MESSAGE( a << '.' );

    return 0;
}

Output:

Starting test
i=2
still testing...
struct A.

reference to the top

BOOST_WARN_MESSAGE( predicate, message )
BOOST_CHECK_MESSAGE( predicate, message )
BOOST_REQUIRE_MESSAGE( predicate, message )

これらのテストツールはそれぞれ、_MESSAGE がないものと同じ働きをする。唯一の違いは、エラーまたは確認メッセージを生成するの代わりに、与えられたメッセージを使用する点である。

Example: test.cpp

int test.cpp( int, char* [] ) {
    double res = sin( 45 );

    BOOST_CHECK_MESSAGE( res > 3, "Why not?!?!" );

    return 0;
}

Output:

test.cpp(3) : error in test_main: Why not?!?! reference to the top

BOOST_CHECK_PREDICATE( prediate, number_of_arguments, arguments_list )

このテストツールは与えられた述語を検証する場合に使用する。述語がである場合、テストツールは確認メッセージを出力する。それ以外の場合、"error in ...: test <predicate>( arguments_list ) fail for (arguments values)" という形式でエラーメッセージを出力する。現時点では単項または2項記述のみサポートされている。

Example: test.cpp

bool is_even( int i ) {
    return i%2 == 0;
}

int test.cpp( int, char* [] ) {
    int i = 17;
    BOOST_CHECK_PREDICATE( &is_even, 1, (i) );

    return 0;
}

Output:

test.cpp(3) : error in test_main: test &is_even(i) failed for 17

Example: test.cpp

int test.cpp( int, char* [] ) {
    int i = 17;

    BOOST_CHECK_PREDICATE( std::not_equal_to<int>(), 2, (i,17) );

    return 0;
}

Output:

test.cpp(3) : error in test_main: test std::not_equal_to<int>()(i, 17) failed for (17, 17) reference to the top

BOOST_REQUIRE_PREDICATE( prediate, number_of_arguments, arguments_list )

このテストツールは与えられた述語を検証する場合に使用する。述語がである場合、テストツールは確認メッセージを出力する。それ以外の場合、 it produces an error message in a form "error in ...: test <predicate>( arguments_list ) fail for (arguments values)"という形式でエラーメッセージを出力し、現在実行しえいるテストケースプロセスを中断する。現時点では単項または2項記述のみサポートされている。

Example: test.cpp

int test.cpp( int, char* [] ) {
    double fp1     = 1.23456e-10;
    double fp2     = 1.23457e-10;
    double epsilon = 8.1e-6;

    // check weak closeness 
    BOOST_CHECK_PREDICATE( close_at_tolerance<double>( epsilon, false ),
                           2, ( fp1, fp2 ) ); // 成功するはず

    return 0;
}
reference to the top

Output:

BOOST_ERROR( message )
BOOST_FAIL( message )

BOOST_ERRORはBOOST_CHECK_MESSAGE( false, message ) と同じである。このテストツールは、無条件にエラーメッセージを出力する場合に使用する。 BOOST_FAIL は BOOST_REQUIRE_MESSAGE( false, message )と同じである。このテストツールは、無条件にエラーメッセージを出力し、そのテストケースプロセスを中断する場合に使用する。

Example: test.cpp

int test_main( int, char* [] ) {
     BOOST_ERROR( "Nothing to test" );
     BOOST_FAIL( "Test is not ready yet" );

    return 0;
}

Output:

test.cpp(3) : error in test_main: Nothing to test

test.cpp(4) : fatal error in test_main: Test is not ready yet

reference to the top

BOOST_CHECK_THROW( statement, exception )

このテストツールはエラー検知を行う場合に使用する。

Example: test.cpp

class my_exception{};
int test_main( int, char* [] ) {
    int i =  0;
    BOOST_CHECK_THROW( i++, my_exception );
  
    return 0;
}

Output:

test.cpp(4) : error in test_main: exception my_exception expected

reference to the top

BOOST_CHECK_EQUAL_COLLECTIONS( left_begin, left_end, right_begin )

このテストツールは2つのコレクションの要素を比較する場合に使用する。

Example: test.cpp

int test_main( int, char* [] ) {
    int col1 [] = { 1, 2, 3, 4, 5, 6, 7 };
    int col2 [] = { 1, 2, 4, 4, 5, 7, 7 };

    BOOST_CHECK_EQUAL_COLLECTIONS( col1, col1+7, col2);
    
    return 0;
}

Output:

test.cpp(4) : error in test_main: test {col1, col1+7} == {col2,...} failed [3 != 4]
test.cpp(4) : error in test_main: test {col1, col1+7} == {col2,...} failed [6 != 7] reference to the top

BOOST_IS_DEFINED( symbol )

このテストツールは与えられたシンボルが定義されているかを検査する。

Example: test.cpp

int test_main( int, char* [] ) {
    BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL1) );
    BOOST_CHECK( BOOST_IS_DEFINED(SYMBOL2(arg)) );
    
    return 0;
}

Output:

test.cpp(2) : error in test_main: test BOOST_IS_DEFINED(SYMBOL1) failed
test.cpp(3) : error in test_main: test BOOST_IS_DEFINED(SYMBOL2(arg)) failed reference to the top

Depricated Boost.Test v1 test tools

以下のものは、Boost.Test バージョン1で使用されているが推奨しないテストツールと、その代替となるツールのリストである。

古いツール 代わりとなるツール
BOOST_TEST( predicate ) BOOST_CHECK( predicate )
BOOST_CRITICAL_TEST( predicate ) BOOST_REQUIRE( predicate )
BOOST_CRITICAL_ERROR( message ) BOOST_FAIL( message )

これらの変更の主な理由は、記述の簡潔性と統一性のためである。古い推奨されない名前でもかまわないが、将来のリリースで削除されることがある。新しい名前を提案してくれたUllrich Koetheに感謝する。

Examples and Test Programs

test_exec_example.cpp
test_exec_fail2.cpp
test_exec_fail3.cpp
test_tools_test.cpp

Design

Boost Test Library Design ドキュメントはBoost Test Library コンポーネント間の関係について記述している。 reference to the top