16. Autotestで一般的なテストスイートを生成する

厳重注意：このセクションでは，この次のリリースのAutoconfの一部と
なっている，実験的な機能を記述しています．我々はAutotestが安定しているこ
とを信じていますが，このドキュメントでは将来変更される可能性があるインター
フェースを記述しています．Autoconfのメーリングリストを購読しないまま
Autotestに依存することはやめてください．

移植性の高いプロジェクトで，テストスイートを実行するために移植性のないツー ルに依存していることは，矛盾しています．Autoconf自身がこの問題の典型です． 2.13までは完全な移植性を目的としていましたが，そのテストスイートは DejaGNUを使用していて，それは高品質で複雑なテストフレームワー クですが，Unixシステムの標準からかけ離れていました．悪いことに，ほとんど の壊れやすいプラットフォームが無いことがよくあり，そのプラットフォームが Autoconfを苦しめ，欠陥を提示していることがほとんどでした．

この問題を回避するために，パッケージ管理者の多くは，その出力が終了ステー タスとなる，つまりテストが成功するまたは失敗するといった，単純なシェルス クリプトをベースに，独自のテストフレームワークを開発してきました．さらに， これらのテストのほとんどは，共通のパターン，重複している大量のコードの結 果，退屈な管理などを共有しています．

以下はAutoconfが生まれた理由と全く同じですが，Autotestは，M4マクロを基本 として移植性の高いシェルスクリプトを構築するテストスイートを生成するフレー ムワークを提供しています．スイート自身は，バグの報告で中断することを限り なく少なくし，自動的なログ生成と追跡機能を備えていて，単純なタイミングで バグは報告されます．

Autoconf自身はAutotestを何年も使用していて，テストスイートとバグの報告の 強さをかなり改善しているattestを実行しています．Autotestの生成物を 使用していることが知られている，Bison，Free Recode，Free Wdiff， GNU Tar といったそれ以外のプロジェクトでは，それぞれ異なるニー ズがあり，一般的なテストフレームワークとしてのAutotestにのんびりと磨きを かけていました．

それにもかかわらず，DejaGNUと比較して，Autotestは対話的なテス トツールとしては不十分で，それがおそらく主な制限事項となっています．

16.1 Autotestテストスイートを使用する

16.1.1 testsuiteスクリプト

Autotestを使用してテストスイートや評価スイートを生成することは簡単です． 評価スイート全体は，autom4teで処理されるファイルに保持されてい て，それ自身は配布物から得られるスタンドアローンのBourneシェルスクリプト を生成するために，GNU M4の環境下で使用されます． autom4teもGNU M4もインストールしているエンドユーザは 不要です．

評価スイートのそれぞれのテストは，テストグループの一部にすべきです． テストグループ(test group)は，通常はグループのテストの一つがデータ ファイルを作成し，それ以降のテストで同じグループのテストがそれを読み込む ために，お互いに実行される必要がある混合テストの，連続した手続きになって います．テストグループごとの数個のテストのみを維持する方がより良く，テス トグループごとに一つのテストのみを維持することが可能な場合，それは理想的 です．

最も単純なパッケージ以外のすべてのものに対して，`testsuite.at'のよ うなファイルは，別々のファイルにした方が管理しやすいことも多いので，すべ てのテストのソースを完全に保持しているわけではありません．これらの個別の ファイルのそれぞれは，単一のテストグループや，パッケージの共通の機能をす べて提示しているテストグループの連続したものを維持しています．そのような 場合は，ファイル`testsuite.at'は評価スイート全体の初期化のみを行な い，他のすべてのテストファイルに対して含める文をリストアップする前に，要 素が健全かどうかを調査するときもあります．特殊なファイル `package.m4'はパッケージの識別子を含んでいて，見つかった場合は自動 的にインクルードされます．

便利な代替品は，すべての大域的な呼び出しをファイルlocal.atに移動 し(ローカルなAutotestマクロは基本的な状態を調査し，AT_INITを呼び 出します)，`testsuite.at'をサブテストスイートをm4_includeす る単純なリストにすることです．そのような状況では，テストスイート全体また は一部を生成すると，autom4teコマンドライン引数の選択が問題にな ります．

Autotestが生成する評価スクリプトは，慣習でtestsuiteから呼び出 されます．実行時には，testsuiteはそれぞれのテストグループを順 番に実行し，テストごとにその特定のテストが成功したか失敗したかを告げる概 要を表示する一行を生成します．すべてのテストの終りに，数を集約して出力し ます．デバッグディレクトリには，それぞれのテストのグループで失敗したもの があれば，それが残ります．そのようなディレクトリは `testsuite.dir/nn'と命名され，nnはテストグループの順番 になり，以下のものが含まれています．

• デバッグスクリプトは`run'と命名され，デバッグモード(debug mode)でテストの結果を返します(see section testsuiteスクリプトの実行)．自動的に生 成されるデバッグスクリプトは，バグの調査を簡単にする目的があります．

• すべてのファイルはAT_DATAで生成されます．

• 実行時のログは，`testsuite.log'と命名されます．

理想的な状況では，失敗するテストがなく，結果として有効なものが残っている デバッグディレクトリはありません．

評価スイートの個別のテストがコンフィグレーションスクリプトからの情報を入 手する必要が生じることも，実験段階ではよくあります．すべての評価スイート で共通なこの情報が，AC_CONFIG_TESTDIRで自動的に生成されるファイル `atconfig'で提供されることもあります．テスト環境で特別に必要となる コンフィグレーションの情報に対し，AC_CONFIG_FILESで実際に作成され るように，`atlocal.in'という名前の追加ファイルを準備してもかまいま せん．コンフィグレーションのプロセスで，`atconfig'と`atlocal' は二つの入力ファイルから作成され，これら二つの生成されたファイルは，自動 的に`testsuite'スクリプトで読み込まれます．

ファイル間の関係を表示する図は以下のようになります．

配布するソフトウェアパッケージの準備に使用されるファイルです．

                [package.m4] -->.
                                 \
subfile-1.at ->.  [local.at] ---->+
    ...         \                  \
subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
    ...         /
subfile-n.at ->'

ソフトウェアパッケージのコンフィグレーションで使用されるファイルです．

                                     .--> atconfig
                                    /
[atlocal.in] -->  config.status* --<
                                    \
                                     `--> [atlocal]

テストスイートを実行中に作成されるファイルです．

atconfig -->.                    .--> testsuite.log
             \                  /
              >-- testsuite* --<
             /                  \
[atlocal] ->'                    `--> [testsuite.dir]

16.1.2 Autotestのログ

実行時に，テストスイートはそれ自身の名前に`.log'が後置されているロ グファイルを作成し，例えば，testsuiteという名前のテストスイー トは`testsuite.log'を作成します．それには多くの情報が含まれ，通常は 管理者が実際に必要とするもの以上ですが，そのためほとんどの場合で必要とさ れるすべてのものが含まれます．

コマンドライン引数

残念なことに広く広がっているUnixの非常に悪い習慣は， `CC=my-home-grown-cc ./testsuite'のように，コマンドの前に環境変数を 設定することです．この結果テストスイートは変更を知ることが無く，そのため， (i)それを報告することが不可能で，(ii)連続する実行に対しCC の値を 保存することができません．Autoconfは全く同じ問題に直面していて，コマンド ライン引数での変数定義を渡すようユーザに依頼することで解決しました． Autotestでもこの規則が要求されますが，強制する意味はありません．ログには ユーザが変更した変数の追跡が含まれています．

`ChangeLog'の抜粋

ソースの階層で見つかるすべての`ChangeLog'の先頭の行です．バグがパッ ケージの開発バージョンで報告されるとき，バージョン文字列はユーザがコンパ イルしたソースの正確な状態を知るための情報としては十分ではないので，これ は特に役に立ちます．もちろんこれは`ChangeLog'の使用方法に依存します．

ビルドマシン

クロスコンパイル環境でテストスイートを実行するということは，テストスイー トはマシンbuildで実行されますがプログラムはマシンhostで実行 されるという意味があり，簡単な作業ではありません．テストスイートとプログ ラムの両方をhostで実行するのはより簡単ですが，テストスイートの観点 からすると，単一の環境変数host = buildは残ります．ログにはビ ルドマシンに関連する情報が含まれていて，それには重要な環境変数も含まれて います．

テストされたプログラム

テストされたプログラムの絶対バスと`--version'の答えです (`testsuite.at'を書く，AT_TESTEDを参照してください)．

コンフィグレーションのログ

configureで生成される`config.log'の内容が後置されます．そ れにはコンフィグレーションフラグとコンフィグレーション自身の詳細な報告が 含まれます．

16.2 `testsuite.at'を書く

`testsuite.at'はBourneシェルスクリプトで，特殊なAutotest M4マクロを 使用して作成します．それは，最初の方でAT_INITの呼び出しを含んでい て，それにテストのためのソースファイルごとにm4_includeの呼び出し が続きます．それぞれのインクルードファイルや，インクルードファイルが使用 されていない場合は`testsuite.at'の残りは，テストグループの連続した 手続きが含まれています．それぞれのテストグループはAT_SETUPの呼び 出しで始まり，それは任意の数のシェルコマンドやAT_CHECKの呼び出し が含まれていて，AT_CLEANUPの呼び出しで完結します．

Macro: AT_INIT ([name])

Autotestを初期化します．パッケージに複数のテストスイートを含める場合，テ ストスイートにnameを与えることが推奨されます．すべての状況で，テス トスイートは常にパッケージ名とバージョンを表示します．それはパッケージの バグを報告する(メール)アドレスも継承します．

Macro: AT_TESTED (executables)

それぞれのプログラムのパスと`--version'の答を，スペースで分離され ているリストexecutablesにログをとります．複数回呼び出されると新し い実行が登録され，言い替えると，一つのプログラムの複数回の登録を危惧する 必要はありません．

Autotestテストスイートは，テストされるプログラムを見つける際に PATHに依存します．これは様々なツールの絶対パスから生成されるもの から保存され，インストールされているプログラムのテストを可能にします．そ のため，動作しているプログラムを知ることは，テストスイート自身やその偶発 的な誤使用の問題を理解するために重要です．互換性の問題を簡単に診断するた めに，依存している外部のプログラムを登録することも重要です．

Macro: AT_SETUP (test-group-name)

このマクロは関連するテストのグループがすべて同じサブシェルで実行されるよ うに開始します．それは，開始されるテストグループの目的を手短に記述した数 語の単語(30から40文字以下)を保持している，単一の引数を受け入れます．

Macro: AT_KEYWORDS (keywords)

まとまっているテストグループに関連する，スペースで分離されている keywordsのリストです．これでテストスイートの"slices"を実行するこ とが可能になります．例えばテストグループの`foo'の機能を行使している 場合，`AT_KEYWORDS(foo)'を使用することで，これらのテストグループを 排他的に実行するために`./testsuite -k foo'を実行します．テストグルー プのtitleは，AT_KEYWORDSに自動的に保存されます．

テストグループ内で複数回呼び出すことで新しいキーワードを累積します．言い 替えると，テストグループで同じキーワードを複数回登録することを危惧する必 要はありません．

Macro: AT_XFAIL_IF (shell-condition)

テストが，既知のバグで期待されたように失敗するかどうかを決定します(サポー トされていない機能に対してはテストを省略するべきです)． shell-conditionはtestコマンドのようなシェルの式です．同じテ ストグループから，このマクロを何回でも利用することが可能で，テストが期待 した異常終了になるには，条件の一つで十分でしょう．

Macro: AT_CLEANUP

現在のテストグループを終了します．

Macro: AT_DATA (file, contents)

入力データのfileを，与えられたcontentsで初期化します．もちろ ん，カンマが含まれていることや，見せかけのM4の展開から保護するために， contentsは適切に角カッコで囲む必要があります．内容は行末(EOF)で終 える必要があります．

Macro: AT_CHECK (commands, [status = ``0''], [stdout = ``''], [stderr = ``''], [run-if-fail], [run-if-pass])

与えられたシェルコマンドcommandsを実行することでテストを実行します． これらのコマンドは，期待されるstdoutとstderrの内容を生成しな がら，通常のstatusで終えるべきです．commandsが77のステータス で終了する場合，テストグループ全体が省略されます．それ以外で，このテスト が失敗する場合はシェルコマンドrun-if-failを実行し，このテストがパ スした場合はシェルコマンドrun-if-passを実行します．

commandsを標準出力にも標準エラー出力にもリダイレクトしてはい けません．

status，またはstdout，またはstderrが`ignore'の場 合，対応する値は調査されません．

stdoutに対する特殊な値`expout'は，commandsの出力がファ イル`expout'の内容であることを期待するという意味があります． stdoutが`stdout'の場合，commandsの標準出力はファイル `stdout'のテスト以外でも利用可能です．`expout'と`stderr' を用いているstderrも同様です．

16.3 testsuiteスクリプトの実行

Autotestテストスイートは以下の引数をサポートしています．

` --help'

` -h'

オプションのリストを表示し，正しく終了します．

` --version'

` -V'

テストスイートのバージョンを表示し，正しく終了します．

` --clean'

` -c'

テストスイートが生成したすべてのファイルを削除し終了します．Makefileター ゲットのcleanを意味します．

` --list'

` -l'

すべてのテスト(またはセクションのみ)を，可能なキーワードを含めてリストアッ プします．

デフォルトで，すべてのテストはデフォルトの環境変数で，最初は静かに，その 後で冗長に実行され(または`--list'で記述され)ますが，テストの組の 環境変数と冗長さの度合は調整可能です．

` variable=value'

環境変数variableをvalueに設定します．デバッグスクリプトとし て`FOO=foo ./testsuite'を実行して，その後で異なる環境変数で実行しな いでください．

変数AUTOTEST_PATHはPATHに前置するためにテストするパスを指 定します．それは特別に相対パス(`/'で始まらない)を処理します．それら は，ビルドしているパッケージのトップレベルから相対的なものと考えられます． すべてのディレクトリは絶対的になり，最初はビルドツリーのトップレ ベルで開始され，その後でソースツリーで開始されます．例えば， `/tmp/foo'でビルドされている`/src/foo-1.0'のソースパッケージの `./testsuite AUTOTEST_PATH=tests:bin'は，結果として `/tmp/foo/tests:/tmp/foo/bin'になり，そして `/src/foo-1.0/tests:/src/foo-1.0/bin'がPATHに追加されます．

` number'

` number-number'

` number-'

` -number'

明確な意味を持ち一致するテストグループを選択肢に追加します．

` --keywords=keywords'

` -k keywords'

(AT_SETUPやAT_KEYWORDSへの引数となる)タイトルやキーワード がすべてのカンマで分けられたリストkeywordsのキーワードにマッ チするテストグループの選択に追加します．

`./testsuite -k autoupdate,FUNC'を実行すると，(`AC_CHECK_FUNC' や`AC_FUNC_FNMATCH'などで) `autoupdate'および `FUNC'でタグ付けされているすべてのテストを選択しますが， `./testsuite -k autoupdate -k FUNC'は`autoupdate'あるい は`FUNC'でタグ付けされているすべてのテストを選択します．

` --errexit'

` -e'

テストが失敗した場合，すぐにテストを中断します．それは`--debug' を暗黙に指定します．過去のテストグループをクリーンアップし，デバッグスク リプトを生成し，ログは停止されます．このオプションは，すべてのテストスイー トに対して意味があり，それは生成されるデバッグスクリプトに対しては実際に は意味がありません．

` --verbose'

` -v'

行なっているものの詳細な出力でより冗長なものにします．これはデバッグスク リプトに対してデフォルトです．

` --debug'

` -d'

テストグループを実行した後でファイルを削除しません -- しかし，それらは 実行前には削除され，そのためこのオプションの使用は，複数のテストグループ を実行するとき問題ありません．デバッグスクリプトを作成しません．ログは行 なわれません(おそらく存在している既存の完全なログファイルを保持するため です)．これはデバッグスクリプトに対してデフォルトですが，それはテストス イート自身のデバッグでも役に立つはずです．

` --trace'

` -x'

テストグループのシェルの追跡を開始します．

16.4 testsuiteスクリプトの作成

Autotestを動作に入れるため，コンフィグレーションと`Makefile'のから くりで必要になるものもあります．少なくともパッケージで深いまたは浅い階層 を使用している場合，すべてのテストとその`Makefile'を格納するディレ クトリの名前として，`tests/'を使用することを推奨します．行なうこと の調査リストは以下のようになります．

• -

  パッケージ固有の定義を行なうファイル`package.m4'を必ず作成してくだ さい．それは，パッケージの完全な署名となるAT_PACKAGE_STRINGと，バ グレポートを送るアドレスAT_PACKAGE_BUGREPORTを定義する必要があり ます．完全性の目的で，AT_PACKAGE_NAME，AT_PACKAGE_TARNAME， そしてAT_PACKAGE_VERSIONを定義することも提案します．これらの変数 の記述はSee section configureの初期化. 我々は以下のようなMakefileの断片 を提案します．

  $(srcdir)/package.m4: $(top_srcdir)/configure.ac { \ echo '# Signature of the current package.'; \ echo 'm4_define([AT_PACKAGE_NAME], [@PACKAGE_NAME@])'; \ echo 'm4_define([AT_PACKAGE_TARNAME], [@PACKAGE_TARNAME@])'; \ echo 'm4_define([AT_PACKAGE_VERSION], [@PACKAGE_VERSION@])'; \ echo 'm4_define([AT_PACKAGE_STRING], [@PACKAGE_STRING@])'; \ echo 'm4_define([AT_PACKAGE_BUGREPORT], [@PACKAGE_BUGREPORT@])'; \ } >$(srcdir)/package.m4

  `package.m4'を配布していることと，それをソースの階層に書いているこ とを確かめてください．テストスイートは配布する必要があります！

• -

  AC_CONFIG_TESTDIRの呼び出し．

  Macro: AC_CONFIG_TESTDIR (directory, [test-path = `directory'])

  Autotestテストスイートは，directoryでコンフィグレーションされます． このマクロは，`directory/atconfig.in'からの `directory/atconfig'の実体を必要とし，デフォルトの AUTOTEST_PATHをtest-pathに設定します(see section testsuiteスクリプトの実行)．

• -

  しかし，`configure.ac'に，AC_CONFIG_FILESコマンドが `tests/atlocal'での代入を確実に含むよう，適切に`configure.ac' に書いてください．

• -

  `make check'でパッケージの評価を開始するように， `tests/Makefile.in'を修正すべきです．例は以下で提供しています．

Automakeを用いると，評価スイートで`make check'をリンクする方法の最 小限の例は以下のようになります．

EXTRA_DIST = testsuite.at testsuite
TESTSUITE = $(srcdir)/testsuite
check-local: atconfig atlocal $(TESTSUITE)
        $(SHELL) $(TESTSUITE)

AUTOTEST = $(AUTOM4TE) --language=autotest
$(TESTSUITE): $(srcdir)/testsuite.at
        $(AUTOTEST) -I $(srcdir) $@.at -o $@.tmp
        mv $@.tmp $@

依存性，すなわち`testsuite.at'を含んでいるファイルのリストを，明示 的にリストアップしたいかもしれません．

厳密にAutoconfを用いると，以下のような行を追加する必要があるかもしれま せん．

subdir = tests

atconfig: $(top_builddir)/config.status
        cd $(top_builddir) && \
           $(SHELL) ./config.status $(subdir)/$@

atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
        cd $(top_builddir) && \
           $(SHELL) ./config.status $(subdir)/$@

そして，`atconfig.in'と$(EXTRA_DIST)を配布物されるように管理 する必要があるかもしれません．

This document was generated by Akihiro Sagawa on June, 15 2005 using texi2html 1.70.