ホーム>プログラミング関連>C# ソースコード
ダウンロード

最も正確な Readme

ホーム: https://github.com/mity/acutest

何が最も深刻なのか

Acutest は、開発者の邪魔にならず、外部依存関係を最小限に抑え、可能な限りシンプルにすることを目的とした C/C++ 単体テスト機能です。

これを実現するために、完全な実装は単一の C ヘッダー ファイル内に存在し、そのコアはいくつかの標準 C ライブラリ関数のみに依存します。

概要

主な特徴:

  • C または C++ での単体テストがサポートされています。
  • テスト フレームワークをインストール、セットアップ、構成する必要はありません。 Acutest は、単一のヘッダー ファイルacutest.hだけです。
  • ヘッダーはプログラムのエントリ ポイント (関数main() ) を提供します。
  • 最小限の依存関係: コア機能はいくつかの標準 C ヘッダーにのみ依存し、オプション機能は特定のシステムで利用可能な場合はさらに多くのヘッダーを使用する可能性があります。
  • 単体テストを作成するための簡単なインターフェイス: 以下でさらに説明するいくつかのプリプロセッサ マクロ。
  • Test Anything Protocol の基本的なサポート ( --tapオプションを使用)。
  • xUnit 互換の XML 出力の基本的なサポート ( --xml-output=FILEを使用)。

C++ 固有の機能:

  • Acutest は、単体テスト関数からスローされた C++ 例外をキャッチします。そのような場合、指定されたテストは失敗したと見なされます。
  • 例外がstd::exceptionから派生した場合、 what()がエラー メッセージに書き込まれます。

Unix/Posix 固有の機能:

  • デフォルトでは、すべての単体テストは子プロセスとして実行されます。
  • デフォルトでは、出力が端末に送信される場合、出力は色付けされます。
  • システムが Posix タイマー ( clock_gettime() ) を提供している場合、ユーザーは--time=real ( --timeと同じ) および--time=cpuを使用してテストの実行時間を測定できます。

Linux 固有の機能:

  • デバッガが検出された場合、デバッグを容易にするために、子プロセスとしてのテストのデフォルトの実行が抑制されます。

Windows 固有の機能:

  • デフォルトでは、すべての単体テストは子プロセスとして実行されます。
  • デバッガが検出された場合、デバッグを容易にするために、子プロセスとしてのテストのデフォルトの実行が抑制されます。
  • デフォルトでは、出力が端末に送信される場合、出力は色付けされます。
  • Acutest は、キャッチされなかった SEH 例外を出力するために SEH フィルターをインストールします。
  • ユーザーは--timeを使用してテストの実行時間を測定できます。

macOS 固有の機能:

  • デバッガが検出された場合、デバッグを容易にするために、子プロセスとしてのテストのデフォルトの実行が抑制されます。

1 つ以上の単体テストを実装し、 acutest.hを含む C/C++ モジュールは、スタンドアロン プログラムとして構築できます。このドキュメントでは、結果のバイナリを「テスト スイート」と呼びます。次に、コマンド ライン オプションで指定されたとおりにスイートが実行され、テストが実行されます。

単体テストは次の場合にのみ成功すると言えます。

  1. 実行パス全体で呼び出されるすべての条件チェック (後述)。
  2. テストでは例外がスローされません (C++ のみ)。そして
  3. (Windows または Unix の場合) 単体テストのサブプロセスは中断/終了されません (たとえば、Unix のシグナルや Windows の SEH によって)。

単体テストの作成

基本的な使い方

Acutest を使用するには、1 つ以上の単体テストを実装する C/C++ ソース ファイルの先頭にヘッダー ファイルacutest.hインクルードするだけです。ヘッダーがmain()関数の実装を提供していることに注意してください。 

 #include "acutest.h"

すべてのテストは、次のプロトタイプを使用して関数として実装される必要があります。 

 void test_example ( void );

テストでは、いくつかのプリプロセッサ マクロを使用してテスト条件を検証できます。これらは複数回使用でき、これらの条件のいずれかが失敗すると、特定のテストは失敗したとみなされます。

TEST_CHECKは最も一般的に使用されるテスト マクロで、単にブール条件をテストし、条件が false (または 0) と評価された場合に失敗します。

例えば： 

 void test_example ( void )
{
    void * mem ;
    int a , b ;

    mem = malloc ( 10 );
    TEST_CHECK ( mem != NULL );

    mem = realloc ( mem , 20 );
    TEST_CHECK ( mem != NULL );
}

テストは互いに完全に独立している必要があることに注意してください。テスト スイートが呼び出されるたびに、ユーザーはスイート内で任意の数のテストを任意の順序で実行できます。さらに、デフォルトでは、サポートされているプラ​​ットフォームでは、各単体テストがスタンドアロン (サブ) プロセスとして実行されます。

最後に、テスト スイートのソース ファイルでは、マクロTEST_LISTを使用して単体テストをリストする必要があります。リストでは、各テストの名前 (一意である必要があります) と、テストを実装する関数へのポインタを指定します。コマンドラインで使いやすい名前をお勧めします。特に、シェルでエスケープが必要になる可能性のあるスペースやその他の特殊文字は避けてください。また、名前の最初の文字としてダッシュ ( - ) を使用することも避けてください。ダッシュ ( - ) は、テスト名ではなくコマンド ライン オプションとして解釈される可能性があります。 

 TEST_LIST = {
   { "example" , test_example },
   ...
   { NULL, NULL }     /* zeroed record marking the end of the list */
};

テストリストはゼロ化されたレコードで終了する必要があることに注意してください。

基本的なテスト スイートの場合、知っておく必要があるのはほぼこれだけです。ただし、Acutest は、特定の状況で役立つマクロをさらにいくつか提供します。これらについては、次のサブセクションで説明します。

チェック失敗時の中止

TEST_CHECKによく似たマクロTEST_ASSERTがありますが、失敗すると現在の単体テストの実行が即座に中止されます。

例えば： 

 void test_example ( void )
{
    void * mem ;
    int a , b ;

    mem = malloc ( 10 );
    TEST_ASSERT ( mem != NULL );

    mem = realloc ( mem , 20 );
    TEST_ASSERT ( mem != NULL );
}

失敗した場合の中止は、 abort() (テストが子プロセスとして実行される場合) を呼び出すか、 longjmp() (そうでない場合) を介して実行されます。

したがって、このような残忍な中絶検査に伴うコストを理解している場合にのみ、この検査を使用する必要があります。単体テストの内容によっては、フラッシュされていないファイル記述子、メモリ リーク、デストラクタが呼び出されずに破棄された C++ オブジェクトなどが含まれる場合があります。

一般に、特定の状況で何を行うのか、およびTEST_ASSERT選択した理由が正確にわかっていない限り、 TEST_ASSERTよりもTEST_CHECKを優先する必要があります。

C++ 例外のテスト

C++ の場合、指定されたコード (通常は単なる関数またはメソッド呼び出し) が予期されるタイプの例外をスローすることを検証するための追加マクロTEST_EXCEPTIONがあります。

関数が例外をスローしないか、互換性のないものをスローした場合、チェックは失敗します。

例えば： 

 void test_example ( void )
{
    TEST_EXCEPTION ( CallSomeFunction (), std:: exception );
}

より充実した故障診断

条件チェックが失敗した場合、問題のデバッグを容易にするために、状況に関する追加情報を提供すると役立つことがよくあります。 Acutest は、この目的のためにマクロTEST_MSGおよびTEST_DUMPを提供します。

前者はprintfのようなメッセージを出力し、もう一方は提供されたメモリ ブロックの 16 進ダンプを出力します。

たとえば、次のようになります。 

 void test_example ( void )
{
    char produced [ 100 ];
    char expected [] = "Hello World!" ;

    SomeSprintfLikeFunction ( produced , "Hello %s!" , "world" );
    TEST_CHECK ( strcmp ( produced , expected ) == 0 );
    TEST_MSG ( "Expected: %s" , expected );
    TEST_MSG ( "Produced: %s" , produced );

    /* Or, if the function could provide some binary stuff, we might rather
     * use TEST_DUMP instead in order to output a hexadecimal dump of the data.
     */
    TEST_DUMP ( "Expected:" , expected , strlen ( expected ));
    TEST_DUMP ( "Produced:" , produced , strlen ( produced ));
}

どちらのマクロも、最後にチェックしたマクロが失敗した場合にのみ何かを出力することに注意してください。言い換えれば、これら 2 つは同等です。 

 if (! TEST_CHECK ( some_condition != 0 ))
    TEST_MSG ( "some message" );
 TEST_CHECK ( some_condition != 0 );
TEST_MSG ( "some message" );

( TEST_MSG可変個引数マクロをサポートするコンパイラが必要であることに注意してください。)

テストベクトルのループ

場合によっては、テスト ベクトルとそれぞれの期待される出力のコレクションを提供するデータのループとしてテスト関数を設計すると便利です。たとえば、単体テストがある種のハッシュ関数の実装を検証することになっており、そのためのテスト ベクトルのコレクションがハッシュ仕様に含まれていると想像してください。

このような場合、すべてのテスト ベクトルに関連付けられた名前を取得し、その名前を出力ログに出力すると、チェックが失敗した場合に有罪のテスト ベクトルを簡単に特定できるため、非常に便利です。ただし、ループ本体では数十のチェック マクロが実行される可能性があるため、そのような名前を追加してループ内のすべてのチェック メッセージをカスタマイズするのは非現実的かもしれません。

これを解決するために、Acutest はマクロTEST_CASEを提供します。このマクロは、テスト ベクター名として機能する文字列を指定します。 Acutest を使用すると、出力ログ内で、指定された名前が後続の条件チェックのメッセージよりも前に配置されるようになります。

たとえば、あるサイズの指定されたバイト配列に対して、新しくmallocされたバッファ内の別のバイト配列を返すとするSomeFunction()テストしていると仮定します。次に、次のようなことができます。 

 struct TestVector {
    const char * name ;
    const uint8_t * input ;
    size_t input_size ;
    const uint8_t * expected_output ;
    size_t expected_output_size ;
};

struct TestVector test_vectors [] = {
    /* some data */
};

void test_example ( void )
{
    int i ;
    const uint8_t * output ;
    size_t output_size ;

    for ( i = 0 ; i < sizeof ( test_vectors ) / sizeof ( test_vectors [ 0 ]); i ++ ) {
        struct TestVector * vec = & test_vectors [ i ];

        /* Output the name of the tested test vector. */
        TEST_CASE ( vec . name );

        /* Now, we can check the function produces what it should for the
         * current test vector. If any of the following checking macros
         * produces any output (either because the check fails, or because
         * high `--verbose` level is used), Acutest also outputs the  currently
         * tested vector's name. */
        output = SomeFunction ( vec -> input , vec -> input_size , & output_size );
        if ( TEST_CHECK ( output != NULL )) {
            TEST_CHECK ( output_size == vec -> expected_output_size );
            TEST_CHECK ( memcmp ( output , vec -> expected_output , output_size ) == 0 );
            free ( output );
        }
    }
}

指定された名前は、 TEST_CASEの使用後に実行されるすべてのチェックに適用されます。

  • 単体テストが終了するまで。または
  • TEST_CASE再度使用して別の名前を指定するまで。または
  • NULLを引数としてTEST_CASEを使用して名前が明示的にリセットされるまで。

カスタムログメッセージ

前のセクションで説明したマクロの多くには、デフォルトのメッセージの代わりにカスタム メッセージを出力できる対応するマクロがあります。

これらはすべて、前述のマクロと同じ名前ですが、接尾部のアンダースコアが追加されています。接尾辞を使用すると、 printfのような文字列形式と、対応する追加の引数が期待されます。

したがって、たとえば、単純なチェックマクロの代わりに、 

 TEST_CHECK (a == b);
TEST_ASSERT (x < y);
TEST_EXCEPTION (SomeFunction(), std::exception);

それぞれの対応するものをカスタム メッセージで使用できます。 

 TEST_CHECK_ (a == b, " %d is equal to %d " , a, b);
TEST_ASSERT_ (x < y, " %d is lower than %d " , x, y);
TEST_EXCEPTION_ (SomeFunction(), std::exception, "SomeFunction() throws std::exception");

コマンド ライン オプション--verboseを使用すると、それぞれのチェックが正常にパスした場合でもメッセージがログアウトされるため、中立的な表現を使用する必要があります。

(チェックが失敗した場合に備えて診断情報を出力する必要がある場合は、マクロTEST_MSGを使用します。それがまさにその目的です。)

同様に、代わりに

 TEST_CASE ( "name" );

もっと豊かに使えるよ

 TEST_CASE_ ( "iteration #%d" , 42 );

ただし、これらはすべて、コンパイラが可変個引数プリプロセッサ マクロをサポートしている場合にのみ使用できることに注意してください。可変引数マクロは、C99 で C 言語の標準部分になりました。

テストスイートの構築

テストの実装が完了したら、単純な C/C++ プログラムとしてコンパイルするだけです。たとえば、 cc C コンパイラであると仮定します。 

$ cc test_example.c -o test_example

単体テストの実行

テスト スイートがコンパイルされると、結果のテスト バイナリを使用してテストを実行できます。

テスト スイートの終了コードは、実行されたすべての単体テストが成功した場合は 0、いずれかが失敗した場合は 1、内部エラーが発生した場合はその他の数値になります。

デフォルトでは (コマンド ライン オプションなし)、実装されたすべての単体テストが実行されます。コマンドラインで指定された単体テストのサブセットのみを実行することもできます。 

$ ./test_example                  # Runs all tests in the suite
$ ./test_example test1 test2      # Runs only tests specified
$ ./test_example --exclude test3  # Runs all tests but those specified

Acutest は複数のレベルの単体テスト選択を実装しているため (少なくとも 1 つのテスト ユニットに一致する最初のものが使用される)、単一のコマンド ライン引数でテスト ユニットのグループ全体を選択できることに注意してください。

  1. 完全一致: 引数が単体テストの名前全体と完全に一致する場合、指定されたテストのみが選択されます。

  2. 単語一致: 引数が完全なテスト名に一致しないが、1 つ以上のテスト名の単語全体には一致する場合、そのようなテストがすべて選択されます。

    次の文字は単語の区切り文字として認識されます: スペース 、タブレータt 、ダッシュ- 、アンダースコア_ 、スラッシュ/ 、ドット. 、カンマ,コロン: 、セミコロン; 。

  3. 部分文字列一致: 単語一致でもテストを選択できなかった場合、引数を部分文字列として含む名前を持つすべてのテストが選択されます。

適切なテスト命名戦略を採用することで、ユーザーは 1 つのコマンド ライン引数で関連するテスト ファミリ全体を簡単に実行 ( --excludeが使用されている場合はスキップ) できるようになります。

たとえば、テストfoo-1 、 foo-2 、 foomatic 、 bar-1 、およびbar-10を実装するテスト スイートtest_example考えてみましょう。 

$ ./test_example bar-1   # Runs only the test 'bar-1' (exact match)
$ ./test_example foo     # Runs 'foo-1' and 'foo-2' (word match)
$ ./test_example oo      # Runs 'foo-1', 'foo-2' and 'foomatic' (substring match)
$ ./test_example 1       # Runs 'foo-1' and 'bar-1' (word match)

--listまたは-l使用すると、指定されたテスト スイートによって実装されたすべての単体テストを一覧表示できます。 

$ ./test_example --list

サポートされているすべてのコマンド ライン オプションの説明を表示するには、オプション--helpを指定してバイナリを実行します。 

$ ./test_example --help

よくある質問

Q：このプロジェクトは「CUTest」という名前ではなかったですか？

A:はい。元の名前では過負荷が多すぎることが判明したため、名前が変更されました。

Q: ファイルREADME.mdおよび/またはLICENSE.mdを配布する必要がありますか?

A:いいえ。ヘッダーacutest.hは、リポジトリへの URL、著作権表記、MIT ライセンス条項が含まれています。これらをそのまま残しておく限り、プロジェクトにヘッダーのみを追加してもまったく問題ありません。結局のところ、その簡単な使用とオールインワンヘッダーの性質が私たちの主な目的です。

ライセンス

Acutest には MIT ライセンスが適用されます。全文については、ファイルLICENSE.mdまたはacutest.hの冒頭を参照してください。

詳細情報

プロジェクトは github にあります。

  • https://github.com/mity/acutest

そこで Acutest の最新バージョンを見つけたり、機能強化に貢献したり、バグを報告したりできます。

拡大する
追加情報
関連アプリ
おすすめ
関連情報 すべて