tcltest

ReferenceTOPKeywords

コマンド名

tcltest - ツールサポートコードとユーティリティをテストします。

構文

package require tcltest ?2.1?
tcltest::test name description ?option value ...?
tcltest::test name description ?constraints? body result
tcltest::loadTestedCommands
tcltest::makeDirectory name ?directory?
tcltest::removeDirectory name ?directory?
tcltest::makeFile contents name ?directory?
tcltest::removeFile name ?directory?
tcltest::viewFile name ?directory?
tcltest::cleanupTests ?runningMultipleTests?
tcltest::runAllTests
tcltest::configure
tcltest::configure option
tcltest::configure option value ?option value ...?
tcltest::customMatch mode command
tcltest::testConstraint constraint ?value?
tcltest::outputChannel ?channelID?
tcltest::errorChannel ?channelID?
tcltest::interpreter ?interp?
tcltest::debug ?level?
tcltest::errorFile ?filename?
tcltest::limitConstraints ?boolean?
tcltest::loadFile ?filename?
tcltest::loadScript ?script?
tcltest::match ?patternList?
tcltest::matchDirectories ?patternList?
tcltest::matchFiles ?patternList?
tcltest::outputFile ?filename?
tcltest::preserveCore ?level?
tcltest::singleProcess ?boolean?
tcltest::skip ?patternList?
tcltest::skipDirectories ?patternList?
tcltest::skipFiles ?patternList?
tcltest::temporaryDirectory ?directory?
tcltest::testsDirectory ?directory?
tcltest::verbose ?level?
tcltest::test name description optionList
tcltest::bytestring string
tcltest::normalizeMsg msg
tcltest::normalizePath pathVar
tcltest::workingDirectory ?dir?

解説

tcltestパッケージはいくつかのユーティリティコマンドを提供します。 これらのコマンドはTclコマンドの評価によって実行されるコードのテストスイーツの構築に役に立ちます。 特にTclライブラリそのものの内部コマンドは、tcltestパッケージを使うテストセットによってテストされます。

上の構文で示されたように、tcltestパッケージに提供された全てのコマンドは::tcltest ネームスペースで定義、及び公開されます。 簡潔に説明するため、次のセクションには全てのコマンドは短縮名によって示されます。

tcltestの主要なコマンドは、テストを定義し、実行させる[test]です。 [test]を使って行うテストは、Tclスクリプトを評価し、その結果を予期された結果 の比較します。 いくつかのオプションによって形成、コントロールされます。 tcltestによって提供された他のコマンドは[test]を形成することと、多くの[test]コマンドをテストスイーツに集合させることを制御します。

Tclで、実行可能にされたコードに対してテストスイーツを生成するために、tcltestのコマンドの使い方についての拡張した例に関する情報は下のTCLTESTでテストスイーツを作成を参照して下さい。

コマンド

コマンド
test name description ?option value ...?
test name description ?constraints? body result
loadTestedCommands
makeFile contents name ?directory?
removeFile name ?directory?
makeDirectory name ?directory?
removeDirectory name ?directory?
viewFile file ?directory?
cleanupTests
runAllTests

構築コマンド

configure
configure option
configure option value ?option value ...?
customMatch mode script
testConstraint constraint ?boolean?
interpreter ?executableName?
outputChannel ?channelID?
errorChannel ?channelID?

ショートカットコマンド

debug ?level?
errorFile ?filename?
limitConstraints ?boolean?
loadFile ?filename?
loadScript ?script?
match ?patternList?
matchDirectories ?patternList?
matchFiles ?patternList?
outputFile ?filename?
preserveCore ?level?
singleProcess ?boolean?
skip ?patternList?
skipDirectories ?patternList?
skipFiles ?patternList?
temporaryDirectory ?directory?
testsDirectory ?directory?
verbose ?level?
他のコマンド
test name description optionList
workingDirectory ?directoryName?
normalizeMsg msg
normalizePath pathVar
bytestring string
test name description ?option value ...?
名前name と記述description を持つテストを定義し、場合によって実行させます。 tcltestのオプションによって定義した通りに、テストの名前と記述はテストの間に報告されたメッセージに使われます。残こりのoption value 引数は [test]のためにテストを定義します。 これは、実行されるスクリプト、実行する条件、期待している結果 、そして期待結果と実際結果の比較方法を含みます。 正当なオプションと、どのようにテストを定義するかに関する完全な解説は下のテストを参照してください。 [test]コマンドは空文字列を返します。

test name description ?constraints? body result 
本フォーマットの[test] はtcltestパッケージのバージョン1に書かれたテストスイーツをサポートするために提供され、また一般 の使用のためのより簡単なインタフェースです。これは[test name description -constraints constraints -body body -result result]と同じです。[test]への全ての他のオプションはデフォルト値になります。constraints が省略され場合、このフォーマットの[test]の全てのoption が”-”で始まるので1番目のと区別ができます。

loadTestedCommands
[configure -load]、又は[configure -loadfile]に指定されたスクリプトを呼び出し側の文脈で評価します。 スクリプトによって発生したあらゆるエラーを含むスクリプトの評価結果を返します。 このコマンドと関連の構築オプションはテストスイーツを実行するインタープリタへテストのためのコマンドを提供します。

makeFile contents name ?directory?
name というファイルをディレクトリdirectory で相対的に作成します。 そして、エンコーディング[encoding system]を使ってcontents をそのファイルに書き込みます。contents が改行で終わらない場合、そのフィイルに改行を付加します。従って、name と指定されたファイルが確かに改行で終わることになります。 システムエンコーディングが使われるので、このコマンドはテキストだけのファイルを作ることに適しています。 そのファイルは、先に[removeFile]によって除去されない限り、次の[cleanupTests]の評価によって削除されます。directory のデフォルト値はディレクトリ[configure -tmpdir]です。 作成されたファイルのフルパスを返します。このコマンドは、テストに必要な(内容が必要とする時点で)あらゆるテキストファイルを作成するために使用します。

removeFile name ?directory?
name に参照されたファイルを強制的に除去します。 このファイル名はdirectory に相対的です。directory のデフォルト値はディレクトリ[configure -tmpdir]です。 空文字列を返します。 このコマンドを使って[makeFile]で作成されたファイルを削除できます。

makeDirectory name ?directory?
name というディレクトリをディレクトリdirectory に相対的に作成します。 このディレクトリは、先に[removeDirectory]によって除去されない限り、次の[cleanupTests ]の評価によって削除されます。directory のデフォルト値はディレクトリ[configure -tmpdir]です。 作成されたディレクトリのフルパスを返します。テストに必要なあらゆるディレクトリを作成するためにこのコマンドを使用します。

removeDirectory name ?directory?
name に参照されたディレクトリを強制除去します。 このディレクトリはdirectory に相対的です。directory のデフォルト値はディレクトリ[configure -tmpdir]です。空文字列を返します。 このコマンドは[makeDirectory]によって作成されたあらゆるディレクトリを削除するのに使用します。

viewFile file ?directory?
[read -nonewline]からの戻り値と同様に、このコマンドはあらゆる最終の改行を除いたfile の内容を返します。このファイル名はdirectory に相対的です。directory のデフォルト値はディレクトリ[configure -tmpdir]です。 このコマンドはテストによって生成されたファイルの内容を予期された結果 とマッチを行うためのテスト結果に変換する便利な方法として使われます。 ファイルの内容はシステムエンコーディングを用いて読まれるので、適用範囲はテキストファイルに限られます。

cleanupTests
いくらかのテストが行われた後でクリーンアップと統計を行う意図を示します。 一般的、テストファイルごとに1度ずつコールし、全てのテストが完了された後ファイルの終りに呼ばれます。 最も良い効率を保つために、エラーが初期のテストファイル評価で発生した場合も、[cleanupTests]が評価されることを保証します。

テストの実行に関する統計を印刷し、前回の[cleanupTests]以来[makeDirectory]と[makeFile]に作成されたファイルを削除します。 前回の[cleanupTests]以来、ディレクトリ[configure -tmpdir]に[makeDirectory ]と[makeFile]以外のコマンドによって作成されたファイル名とディレクトリ名が[outputChannel]にプリントされます。 ::env配列に示されたように、このコマンドはオリジナルのシェル環境を回復し、空文字列を返します。

runAllTests
これはtcltestの構築可能なオプションによって管理された全体のテストスイーツを実行する主コマンドです。このテストスイーツは多重ファイルかつ(または)ディレクトリを含みます。多数の[runAllTests]の変形の完全な解説は下の全てのテストを行うを参照してください。

構築コマンド

configure
tcltestにサポートされた構築可能なオプションのリストを返します。 オプションのフルリスト、それらの正当な値、そしてtcltest操作への影響に関する情報は下の構築可能オプションを参照してください。

configure option 
サポートされた構築可能なオプションoption の現在の値を返します。option がサポートされた構築可能なオプションではないとエラーを出力します。

configure option value ?option value ...?
順番に各構築可能なオプションoption の値を対応する値value に設定します。option がサポートされた形成可能なオプションでない場合、あるいは、value が対応するoption の正当な値ではない場合、またはvalue が提供されない場合、エラー出力され、[configure]の操作が中止され、後続のoption value 引数は処理されません。

tcltestパッケージが([package require tcltest]に)ロードされたとき、環境変数::env ( TCLTEST_OPTIONS ) が存在するならば、その値は[configure]に渡すための引数のリストとみなされます。 これによって構築オプションのデフォルト値が環境によって設定できるようになります。

customMatch mode script 
[test]への-matchオプションの新しい正当な値としてmode を登録します。-match mode オプションが[test]に渡された場合、テストのボディを評価した実際の結果 を予測される結果と比較するためにスクリプトscript は評価されます。マッチを行うために、そのscript は2つの追加の単語と予測される結果と現実の結果によって完成されます。 そして完成されたスクリプトはグローバルなネームスペースで評価されます。 完成されたスクリプトは結果がマッチするかどうかを示すブール値を返すでしょう。 [test]の固有のマッチングモードはexact, globregexpです。

testConstraint constraint ?boolean ?
指定されたconstraint と関連していたブール値を、設定または参照します。 更に多い情報は下のテスト制約を参照して下さい。

interpreter ?executableName ?
[configure -singleproc]が偽であれば、各テストファイルを実行するために、[runAllTests] によって[ exec]された実行可能なものの名前を設定、または参照します。 [interpreter]のデフォルト値は、[info nameofexecutable]によって返される現在実行しているプログラム名です。

outputChannel ?channelID ?
出力チャネルIDを設定または参照します。デフォルトはstdoutです。 テストはテストに関連する結果 を出力する必要のある場合、出力をstdoutへではなく、[outputChannel]へ送ります。

errorChannel ?channelID ?
エラーチャネルIDを設定または参照します。デフォルトはstderrです。テストはエラーメッセージを出力する場合、その出力をstderrへではなく、[errorChannel]へ送ります。

ショートカットコマンド

debug ?level?
[configure -debug ?level?]と同じです。

errorFile ?filename ?
[configure -errfile ?filename?]と同じです。

limitConstraints ?boolean ?
[configure -limitconstraints ?boolean?]と同じです。

loadFile ?filename ?
[ configure -loadfile ?filename?]と同じです。

loadScript ?script ?
[configure -load ?script?]と同じです。

match ?patternList?
[configure  -match ?patternList?]と同じです。

matchDirectories ?patternList ?
[ configure -relateddir ?patternList?]と同じです。

matchFiles ?patternList ?
[ configure -file ?patternList?]と同じです。

outputFile ?filename ?
[configure -outfile ?filename?]と同じです。

preserveCore ?level ?
[configure -preservecore ?level?]と同じです。

singleProcess ?boolean ?
[configure -singleproc ?boolean?]と同じです。

skip ?patternList?
[configure -skip ?patternList?]と同じです。

skipDirectories ?patternList ?
[configure -asidefromdir ?patternList?]と同じです。

skipFiles ?patternList ?
[configure -notfile ?patternList?]と同じです。

temporaryDirectory ?directory ?
[configure -tmpdir ?directory?]と同じです。

testsDirectory ?directory ?
[configure -testdir ?directory?]と同じです。

verbose ?level ?
[configure -verbose ?level?]と同じです。

他のコマンド

tcltestによって提供された残りのコマンドは、tcltestまたはTclそのものによって提供されたより良い代用コマンドです。 現存するテストスイーツをサポートするために保持されただけなので、新しいコードを作成する際の使用は避けましょう。

test name description optionList
このフォーマットの[test]は、複数行に渡る多数のオプションを、[test]引数の間の改行をバックスラッシュ引用ではなく、中括弧 によって引用された1つの引数として、[test]へ渡すことを可能にするために提供されます。optionList 引数は、偶数個の[test]に渡すoption value 引数を表す要素を持つリストでなければなりません。しかしながら、[switch]の代わりのフォーマットと同様に、これらの値は直接、渡りません。 その代りにこの形式は中括弧で囲んだ”ブロック”を”do what I mean”解釈を実行しようとします。 つまりリスト要素上で置き換えを行い、Tclの置き換え規則を覆す”不幸”な試みを行います。 この結果は、明確に証明することは、ほぼ不可能であるため、この形式は推奨されません。 実際バックスラッシュに引用された改行を回避するのは、この形式が必須ではないことを理解するために、下述のTCLTESTでテストスイーツを作成の例を参照して下さい。 どうしても、この形式を使いたい場合、置き換えの詳細を知るため、tcltestのソースコードを調べましょう。 あるいは、[test]の3番目から最後の引数を中括弧で囲んで、ベストな結果 を期待しましょう。

workingDirectory ?directoryName ?
テストスイーツが実行しているとき、現在のワーキングディレクトリを設定または参照します。 workingDirectoryのデフォルト値は、テストスイーツがスタートされるディレクトリです。 Tclの[cd]と[pwd]は理にかなった代替えです。

normalizeMsg msg
msg から”余分の”改行を除去した結果を返します。 ここで”余分の”はあまり正確ではありません。 Tclは望み通りの文字列の修正のため、たくさんの文字列処理コマンドを提供し、[customMatch]は実際の結果 と予期された結果の柔軟なマッチングを可能にします。

normalizePath pathVar
パスのsymlinksを解析して、内部のリダイレクションなしのパスを作成します。pathVar が絶対的であると仮定します。pathVarは適するものに修正されます。Tclコマンド[ file normalzie]は理にかなった代替えです。

bytestring string 
string で提供された値を使って適切にUTF-8文字から形成された文字列とは対照的に、このコマンドは、要求されたバイトのシーケンスから成る文字列を組み立てます。 これによって、テスト者はCプロシージャに渡す非規範な、または不適当な文字列を作成できます。 これはまさにTclコマンド[encoding convertfrom identity]に相当します。

テスト

[test]コマンドはtcltestパッケージの核心です。 その本質的役割はTclスクリプトを評価し、結果を予期された結果と比較することです。 [test]のオプションはテストスクリプト、それらを評価する環境、予測される結果、実際の結果を予測される結果と比較する方法などを定義します。 tcltestのいくらかの構築オプションはtestの動作に影響します。

テスト
-constraints keywordList|expression
-setup script
-body script
-cleanup script
-match mode
-result expectedValue
-output expectedValue
-errorOutput expectedValue
-returnCodes expectedCodeList
テスト制約
singleTestInterp
unix
win
nt
95
98
mac
unixOrWin
macOrWin
macOrUnix
tempNotWin
tempNotMac
unixCrash
winCrash
macCrash
emptyTest
knownBug
nonPortable
userInteraction
interactive
nonBlockFiles
asyncPipeClose
unixExecs
hasIsoLocale
root
notRoot
eformat
stdio
全てのテストを行う
構築可能なオプション
-singleproc boolean
-debug level
0
1
2
3
-verbose level
body (b)
pass (p)
skip (s)
start (t)
error (e)
-preservecore level
0
1
2
-limitconstraints boolean
-constraints list
-tmpdir directory
-testdir directory
-file patternList
-notfile patternList
-relateddir patternList
-asidefromdir patternList
-match patternList
-skip patternList
-load script
-loadfile filename
-outfile filename
-errfile filename

[test]の正当なオプションは以下に要約されます。

test name description
    ?-constraints keywordList|expression?
    ?-setup setupScript?
    ?-body testScript?
    ?-cleanup cleanupScript?
    ?-result expectedAnswer?
    ?-output expectedOutput?
    ?-errorOutput expectedError?
    ?-returnCodes codeList?
    ?-match mode?

name は任意な文字列です。パターンに従ってname を選択することは規約的です。

target-majorNum.minorNum

ホワイトボックス( 回帰 ) テストの場合は、ターゲットはテストされたC関数またはTclプロシージャ名です。 ブラックボックステストの場合、ターゲットはテストされた特徴的な名前です。 ブラックボックステストの名前の末尾に_bbを添える必要がある規約も存在します。 関連テストはメジャーな番号を共有すべきです。 テストスイーツが進化していく中に、同じテストに対して同じ名前を持つことは最適です。 ”テストfoo-1.3が3.4までのすべてリリースに成功したが、リリース3.5に欠陥を始めた”みたいなものを言うのはいいでしょう。

[test]評価時に、name は[configure -match]と[configure -skip]から返されたパターンにマッチする文字列のリストと比較されます。name が[configure -match]からのパターンのいずれにマッチし、かつ[configure -skip]からのパターンのいずれにもマッチしないときのみ、このテストは行われます。

description はテストの短い原文の記述でなければなりません。このdescription はテストに作られた出力(一般的にテストの失敗メッセージ)に含まれます。良いdescription 値はテストの目的をテストスイーツのユーザーに簡潔に説明できるものにすべきです。 テストされたTcl、またはC関数の名前は回帰テストの記述に含まれるべきです。 バグを再現するためのテストケースが存在すれば、記述にはバグIDを記入しましょう。

正当な属性と関連する値は以下です。

-constraintskeywordList|expression
選択可能の-constraints属性は、1つ以上のキーワードや式のリストです。 -constraints値がキーワードのリストなら、各々のキーワードは[testConstraint ]への呼び出しによって定義され、制約された名前でなければなりません。 リストされた制約のうちのどれかが偽(false)であり、存在しないなら、そのテストはスキップされます。 -constraints値が式であれば式は評価されます。 その式が真に評価されればテストは行われます。 注意すべきなのは、式フォーマットの-constraintsが[configure  -constraints]と[configure  -limitconstraints]の操作と干渉することもあるので推奨されません。 常に実行されるべきではない、あらゆるテストに適切な制約を付けるべきです。すなわち、テストの条件付の評価は[test]の評価でなく、-constraintsオプションによって遂行されるべきです。このように、スキップされたジャ回数はテスト環境に基づいて変わるかもしれませんが、テストスイーツに報告されるテストの回数は常に同じです。デフォルト値は空のリストです。独自の制約を追加する方法に関する固有の制約と情報のリストは、下述のテスト制限事項を参照します。

-setup script
省略可能の-setup属性は-body属性によって示されたスクリプトを実行する前に実行されるscript を示します。script の評価がエラーを出力されたなら、そのテストは失敗になります。デフォルト値は空の文字列です。

-body script
-body属性は、テストを実施するために実行するscript を示します。 正確さをチェックできる結果を返さなければならない。script の評価がエラーを出力されたなら、そのテストは失敗になります。デフォルト値は空文字列です。

-cleanup script
任意の-cleanup属性は、-body属性によって示されたスクリプトの後で実行されるscript を示します。script の評価がエラーを出力された場合、そのテストは失敗になります。 デフォルト値は空文字列です。

-match mode
-match属性は、どのように-result-output-errorOutputに提供された予期された応答を比較するかを決定します。mode の正当な値は regexp, globexact、そして[customMatch ]への以前の呼び出しに登録されたあらゆる値です。 デフォルト値はexactです。

-result expectedValue
-result属性はスクリプトからの戻り値に比較するexpectedValueを提供します。 デフォルト値は空文字列です。

-output expectedValue
-output属性は、スクリプトの評価の間にstdoutか[outputChannel]に送られたあらゆる出力に比較するためのexpectedValueをを提供します。 注意事項は、[puts]を使ってプリントされた出力のみが比較に使われることです。 -outputが指定されないと、stdoutか[outputChannel ]に送られた出力は比較されません。

-errorOutput expectedValue
-errorOutput属性は、スクリプトの評価の間にstderrか[errorChannel]に送られたあらゆるエラー出力に比較するためのexpectedValueをを提供します。 注意事項は、[puts]を使ってプリントされた出力のみが比較に使われることです。 -errorOutputが指定されないと、stderrか[errorChannel ]に送られた出力は比較されません。

-returnCodes expectedCodeList
省略可能の-returnCodes属性は、expectedCodeList-bodyスクリプトの評価から受け取るリターンコード のリストを提供します。 -bodyスクリプトの評価がexpectedCodeListにないコードを返すと、このテストは失敗になります。 拡張リターンコードを含めて数値また符号的な形をしており [return ]が理解できるコードの全ては、expectedCodeListが受け入れ可能な要素です。 デフォルト値は{ok return}です。

テストを合格するためには、その-setup-bodyそして-cleanupスクリプトを成功と評価されなければなりません。 -bodyスクリプトからのリターンコードとその結果は期待値にマッチしなければならず、指定されたならば、テストからの出力とエラーデータは予期された-output-errorOutput値にマッチしなければなりません。 これらの条件のうちのいずれかが満たされないと、そのテストは失敗になります。 注意すべきなのは全てのスクリプトがの[test]の呼び出し者の文脈において評価されることです。

[test]は全ての属性に対して、正当な文法と合法的な値によってコールされる限り、エラーを出力されません。 代りに、テストの失敗は[outputChannel]に書かれた出力として報告されます。 デフォルトでは成功のテストは出力を生み出しません。 [test]に作られた出力メッセージは下述の構築可能オプションで示された[configure -verbose]オプションによって規制されます。 テストスクリプトによって生成された全ての出力は、[puts]を使って、[outputChannel ]や[ errorChannel ]へ出力すべきです。 こうすることによって、テストスイーツのユーザーは[configure -outfile]と[configure -errfile]オプションによって出力を容易に獲得することができ、-output-errorOutput属性が適切に機能します。

テスト制約

制約はテストがスキップされるべきかどうかを決定するために使われます。各制約は名前 ( あらゆる文字列及びブール値が使用可能 ) を持っています。各[test]は、制限名のリスト-constraints値を持っています。 制限コントロールは2つのモードがあります。最も頻繁に使われるデフォルト方法は[ configure -limitconstraints]設定によって示されたものです。 リストにおける全ての制限が真に評価されればテストは進みます。 つまり、[test]の-constraintsオプションはテストを可能で有意義なものにするために必要とされるあらゆる条件を定義する便利で象徴的な方法です。 例えば、制限unixが真であれば-constraints unixを持つ[test]だけは実行し、このテストスイーツがUnixプラットホームで実行されるものを示します。

全ての[テスト]に必要とされるときだけ実行させるために適切な-constraintsで定義すべきです。 いくらかの制約はtcltestパッケージにおいてプリ定義されています ( 下でリストされます ) 。ユーザーに定義された制約の登録は[ testConstraint ]コマンドによって行われます。 ユーザーが定義した制限は、テストファイルの中に、もしくは[configure -load]、または[configure -loadfile]オプションによって指定されたスクリプトの中に現れます。

下記は、tcltestパッケージによってプリ定義された制限のリストです。

singleTestInterp
全てのテストファイルが1つのインタープリタにsourceされた場合だけ、テストが行われます。

unix
テストはあらゆるUnixプラットホームでだけ、実行できます。

win
テストはあらゆるWindowsプラットホームでだけ、実行できます。

nt
テストはあらゆるWindowsNTプラットホームでだけ、実行できます。

95
テストはあらゆるWindows95プラットホームでだけ、実行できます。

98
テストはあらゆるWindows98プラットホームでだけ、実行できます。

mac
テストはあらゆるMacプラットホームでだけ、実行できます。

unixOrWin
テストはUnix、もしくはWindowsプラットホームでだけ、実行できます。

macOrWin
テストはMac、もしくはWindowsプラットホームでだけ、実行できます。

macOrUnix
テストはMac、もしくはUnixプラットホームでだけ、実行できます。

tempNotWin
テストはWindows上で行われることができません。 このフラグはテストを一時的に無効にするために使われます。

tempNotMac
テストはMac上で行われることができません。 このフラグはテストを一時的に無効にするために使われます。

unixCrash
テストはUnixで実行すればクラッシュします。 このフラグはテストを一時的に無効にするために使われます。

winCrash
テストはWindows上で実行すればクラッシュします。 このフラグはテストを一時的に無効にするために使われます。

macCrash
テストはMac上で実行すれば、クラッシュします。 このフラグはテストを一時的に無効にするために使われます。

emptyTest
テストは空では実行されません。 将来テストを書き込むための場所取りをしておきます。 この制限値はユーザーは別の方法で指定しない限りテストにスキップするために偽にします。

knownBug
テストが失敗することが知っており、バグはまだ修正されていません。 この制限値はユーザーは別 の方法で指定しない限りテストにスキップするために偽にします。

nonPortable
テストは幾つかの既知の開発環境でだけ、実行されます。 幾つかのテストは本来非移植用です。例えばワードの長さ、ファイルシステム構造、Windowsマネージャ等のようなものに依存する場合などです。 この制限値はユーザーは別の方法で指定しない限りテストにスキップするために偽にします。

userInteraction
テストはユーザーに対話を要求します。 この制限値はユーザーは別の方法で指定しない限りテストにスキップするために偽にします。

対話型
テストはインタープリタが対話型モードでだけ、実行されます(グローバルなtcl_interactive変数が1に設定されるとき ) 。

nonBlockFiles
テストはプラットフォームがファイルを非ブロックモードに設定することをサポートする場合だけ、行われます。

asyncPipeClose
テストはプラットフォームがパイプ上で非同期flush、及び非同期closeをサポートする場合だけ、行われます。

unixExecs
テストはこのマシンが利用可能なUnix-styleコマンドcatechoshwcrmsleepfgreppschmod及びmkdirを持つ場合だけ、行われます。

hasIsoLocale
実テストは、ISOロケールに変えられる場合だけ、行われます。

ルート
テストはUnixユーザーがルートである場合だけ、行われます。

非ルート
テストはUnixユーザーがルートではない場合だけ、行われます。

eformat
テストはアプリが浮動小数点数値の「e」フォーマットをサポートするsprintf作業バージョンを持っている場合だけ、行われます。

stdio
テストはパイプが[インタープリタ]としてopenできる場合だけ、行われます。

制限コントロールの代替モードは[configure  -limitconstraints]をtrueに設定することによって可能にします。 この構築設定はfalseならば[configure  -constraints]から返された制限リストの内容ではなく、全ての現存する制限がfalseにセットされます。[configure  -constraints]はセットされた場合、それら全ての制限はtrueにセットされます。 その結果として、オプション[configure  -constraints]と[configure  -limitconstraints]の両方が設定されたとき、[configure  -constraints]リストに存在する制限を含むテストのみが行われます。全ての他のものはスキップされます。 例えば、下記で構築を開始する場合

configure -constraints knownBug \
          -limitconstraints true \
          -verbose pass

これで実行されるテストは 既知のバグを働かせることでバグを示し、パスできる(バグが修正されてことを意味する)ものが存在するかをチェックします。 

全てのテストを行う

1つのコマンド[ runAllTests ]を評価することで多数のファイル及びディレクトリを検索し、全体のテストセットを実行できます。 tcltestの構築オプションは、正確なオペレーションを制御します。[ runAllTests ]コマンドはその構築の要約を[ outputChannel ]にプリントすることから始めます。

実行用テストファイルは、[config -testdir]ディレクトリから見つかります。 該当ディレクトリにおけるファイルのうち、[configure  -file]パターンのどれにでもマッチし、かつ[configure  -notfile]パターンのいずれにもマッチしないものリストは、生成、分類されます。 そして各ファイルは順番に評価されます。 [configure  -singleproc]は真なら各ファイルは呼び出し側の文脈において[ source]されます。偽ならば、[インタープリタ]のコピーを作成し、[ exec ] で各ファイルを評価します。 テストがプロセスが中止されるような重大なエラーの原因となる場合、マルチプロセスオペレーションは役に立ちます。 エラーが1つのファイルを評価するサブプロセスを中止するかもしれませんが、マスタプロセスはテストセットの残りを継続できます。 マルチプロセスオペレーションにおいてマスタプロセスにおけるtcltestの構築は、[configure   -outfile]を除いてコマンドライン引数としてサブプロセスに渡されます。マスタプロセスにおける[ runAllTests ]コマンドはサブプロセスから全ての出力を集め、それらの結果 を1つのマスタレポートに照合します。全部のテスト故障は報告されます。または、[configure  -verbose]の設定によって要求されたメッセージは、マスタプロセスによって直接[ outputChannel ]に渡ります。

全ての選択されたテストファイルを評価した後で、結果の要約は[ outputChannel ]に出力されます。 その要約は評価された [テスト]のトータル数を、 スキップされたもの、通過されたもの、失敗されたものに分類されて出力します。 同時に要約は評価されたファイルの数、テストの中止を引き起こした全てのファイル、またはエラーの名前を扱います。 テストにスキップされた制約及びその制約によってスキップされたテスト数のリストは、同時に出力されます。 同時にテストファイルの評価により[configure  -tmpdir]に残した全ての一時的なファイルを生成したことを示すメッセージが出力されます。

選択されたテストが、全て完成され、要約された後に、[ runAllTests ]は[configure -testdir]の全てのサブディレクトリで再帰的にファイルを実行します。 全て[configure  -relateddir]パターンの何れかにマッチし、かつ[configure  -asidefromdir]パターンのいずれもマッチしない全てのサブディレクトリは、検索されます。 all.tclと指定されたファイルがディレクトリにおいて発見されれば、呼び出し側の文脈におけて[ source]されます。 調査されたディレクトリがall.tclファイルを含むかどうかに拘らず、そのサブディレクトリは同じく[ -relateddir]、及び[configure  -asidefromdir]パターンに対してスキャンされます。 このようにディレクトリ・ツリーにおける多くのディレクトリは、1つの[ runAllTests ]コマンドによって評価された全てのテストファイルを持つことができます。

構築可能なオプション

[configure ]コマンドは構築可能なtcltestオプションを設定、照会するために使われます。 正当なオプションは以下のものです。

-singleprocboolean
[ runAllTests ]が、各テストファイルのためにサブプロセスを生成するかどうかをコントロールします。booleanは真ならば生成します。デフォルト値は偽です。
-debuglevel
デバッグレベルをlevelに設定し、stdoutにプリントされるべきデバッグ情報の量 を示す整数値です。デバッグメッセージが[configure  -outfile]値と関係なく常にstdoutに出力されることにご注目下さい。デフォルト値は0です。 レベルは以下のように定義されます。
0
デバッグ情報を全く表示しません。
1
テストがスキップされたかどうかに関する情報を表示します。 これは [configure  -match](userSpecifiedNonMatch)によって指定された使用するテストのどれにもマッチしないものか[configure  -skip](userSpecifiedSkip)によって指定されたテストのいずれかにマッチするものです。 同時にクリーンアップ不足またはバランスのよくないテストファイルの存在に関する警告を出力します。
2
コマンドラインプロセッサによって分析されたフラグ配列、::env配列の内容、及び全てのユーザー定義変数 ( 使われている現在のnamespaceに存在する ) を表示します。
3
テスト道具における個々のプロシージャが行っている操作に関する情報を表示します。
-verboselevel
冗長出力タイプをlevelに定義し、ゼロ個以上要素を含むリストを示します。要素はbodypassskipstart及びerrorタイプです。デフォルト値は、bodyです。 レベルは以下と定義されます。
body ( b )
失敗したテストのボディを表示します。
pass ( p )
テストが通過されるときに出力された出力です。
skip ( s )
テストがスキップされるときに出力された出力です。
start ( t )
テストがスタートするときに出力された出力です。
error ( e )
テストリターンコードが期待された戻りコードにマッチしないとき、errorInfo及びerrorCodeが存在するならば出力されます。

注意、上の1文字省略形は、同等に認識されます。従って、[configure  -verbose pt]と[configure -verbose {pass start}]は同じです。

-preservecorelevel
コア保存レベルをlevelに設定します。 このレベルでコアファイルをチェックする厳しさを決定します。 デフォルト値は0です。レベルは以下と定義されます。

0
チェックなし-各テスト命令の終了時のコアファイルをチェックしません。 しかし、[ runAllTests ]は全てのテストファイルが評価された後で、それらをチェックします。

1
コアファイルのチェックは各[テスト]命令の終りにもします。

2
常に上記で記述したコアファイルをチェックし、生成されたコアファイルを全て1つコピーして[configure  -tmpdir]に保存します。

-limitconstraintsboolean
[テスト]は上のテストで示されたように、制約を優先するモードを示します。 デフォルト値は偽です。

-constraintslist
全てのlistにある制約を真に設定します。[configure -limitconstraints true]との結合使用で上のテストで示されたように、代替制限モードをコントロールします。 デフォルト値は空のリストです。

-tmpdirdirectory
[ makeFile ]、[ viewFile ]、[ removeFile ]そして[ removeDirectory ] に使われる一時的なディレクトリをセットします。このデフォルトディレクトリ にテストによって作成される一時的ファイル及びディレクトリを格納します。 デフォルト値は[ workingDirectory ]です。

-testdirdirectory
テストファイル及びサブディレクトリのために[ runAllTests ]が検索するディレクトリをセットします。 デフォルト値は[ workingDirectory ]です。

-file patternList
[ runAllTests ]が使用する(どのテストファイルを評価するかを決定するための)パターンのリストをセットします。 デフォルト値は*.testです。

-notfile patternList
[ runAllTests ]が使用する(どのテストファイルをスキップするかを決定するための)パターンのリストをセットします。 全てのSCCSロックファイルがスキップされるようにデフォルト値は、l.*.testです。

-relateddir patternList
[ runAllTests ]が使用する(all.tclをどのようなサブディレクトリから検索するかを決定するための)パターンのリストをセットします。 デフォルト値は*です。

-asidefromdir patternList
[ runAllTests ]が使用する(all.tclを検索するとき、そのサブディレクトリをスキップするかを決定するための)パターンのリストをセットします。 デフォルト値は空のリストです。

-match patternList
[テスト]が使用する(テストが行われるべきかどうかを決定するための)パターンのリストがセットされます。 デフォルト値は*です。

-skip patternList
[テスト]が使用する(テストがスキップされるべきかどうかを決定するための)パターンのリストがセットされます。 デフォルト値は空のリストです。

-loadscript
loadTestedCommandsによって評価されるためのスクリプトを示します。 デフォルト値は空のスクリプトです。

-loadfilefilename
そうであるためのスクリプトがどちら[ loadTestedCommands ]評価したことを読むのでファイル名をセットして下さい。 これは-loadに対する代替です。それらは、共に使われることはできません。

-outfilefilename
tcltestによって作られた全て出力の書き込み先ファイルを示します。 filenameと指定されたファイルは書き込みモードでopenされ、その結果チャネルはoutputChannelの値としてセットされます。

-errfilefilename
tcltestによって作られた全てのエラー出力の書き込み先ファイルを示します。 filenameと指定されたファイルは書き込みモードで[ open]され、その結果チャネルは[ errorChannel ]の値としてセットされます。

TCLTESTでテストスイーツを作成

テストスイーツの基本的な要素は個々の[テスト]コマンドです。 ここでいくらかの例から始めましょう。

[1]
通常戻るスクリプトのテスト。
test example-1.0 {normal return} {
    format %s value
} value
[2]
文脈準備、及びクリーンアップを必要とするスクリプトのテスト。 中括弧とインデントスタイルの使用でライン継続符号の必要性を回避している点に注意してください。
test example-1.1 {test file existence} -setup {
    set file [makeFile {} test]
} -body {
    file exists $file
} -cleanup {
    removeFile test
} -result 1
[3]
エラーを上げるスクリプトのテスト。
test example-1.2 {error return} -body {
    error message
} -returnCodes error -result message
[4]
制約によってテストを行います。
test example-1.3 {user owns created files} -constraints {
    unix
} -setup {
    set file [makeFile {} test]
} -body {
    file attributes $file -owner
} -cleanup {
    removeFile test
} -result $::tcl_platform(user)

更に高度の編成として、いくらかの[テスト]コマンドは1つのテストファイルに集められます。 テストファイルは.test拡張名を持つものです。 これは、[ runAllTests ]がテストファイルを発見するために使われるデフォルトパターンであるからです。 良い経験則としてプロジェクトの各ソースコードファイルのために、1つずつのテストファイルを用意するといいでしょう。 テストを常にコード変更と同期させ、テストファイル及びソースコードファイルを共に編集することは良い習慣です。

テストファイルにおける大部分のコードは[テスト]コマンドでなければなりません。 テストをスキップするために条件付の評価を使うより、制約を使うほうがよいです。 下記を参照して下さい。

[5]
testConstraint X [expr $myRequirement]
test goodConditionalTest {} X {
    # body
} result

そして、下記を使わないこと

[6]
if $myRequirement {
    test badConditionalTest {} {
    #body
    } result
}

テストボディの文脈全体に必要な条件を制定、解除するには、-setup-cleanupオプションを使ってください。 テストを同じファイルの前に出現するテストに依存させなければなりません。 前のテストはスキップされる可能性があるからです。 いくらかの連続したテストが同じ文脈を必要とする場合、適切なセットアップとクリーンアップスクリプトを各テストの-setup、そして-cleanupオプションに渡す変数に格納される事によって実現できます。 これは[テスト]コマンド外でセットアップを行うより更に良い解決策です。 こうするメリットはセットアップが必要なときだけ実行され、セットアップの間のあらゆるエラーが報告され、テストファイルが中止されることがありません。

テストファイルは他のテストファイルと結合できると同時に、それらを妨害しないようにすべきです。 [configure   -singleproc 1]を使っても全てのファイルが通 常のインタープリタにおいて評価されます。 これを達成する簡単の方法は、テストの全てのコマンド及び変数をテストファイル評価が終了した時点で削除されるnamespaceで定義することです。 適当なものとしてnamespaceはテストしているモジュールのnamespaceの子供namespace(名test)です。

テストファイルは持ち主[ runAllTests ]によって呼ばれず、直接スクリプトとしても評価できるようにすべきです。 これはtcltestが提供した全ての構築コントロールをテスタで作用させるために、各テストファイルがコマンドライン引数を処理できるようにさせることを意味します。

テストファイルにおける全ての[テスト]の後でコマンド[ cleanupTests ]を呼ばなければなりません。

[7]
下記は、それらのポイントを例証する見本のテストファイルのスケッチです。
package require tcltest 2.2
eval tcltest::configure $argv
package require example
namespace eval ::example::test {
    namespace import ::tcltest::*
    testConstraint X [expr {...}]
    variable SETUP {#common setup code}
    variable CLEANUP {#common cleanup code}
    test example-1 {} -setup $SETUP {
    # First test
    } -cleanup $CLEANUP -result {...}
    test example-2 {} -constraints X -setup $SETUP {
    # Second test; constrained
    } -cleanup $CLEANUP -result {...}
    test example-3 {} {
    # Third test; no context required
    } {...}
    cleanupTests
}
namespace delete ::example::test

次のレベルの編成はいくらかのテストファイルで構築された十分なテストスイーツです。 1つのスクリプトはスイーツ全体をコントロールするために使われます。 このスクリプトの基本機能はあらゆる必要なセットアップをした後で[ runAllTests ]を呼ぶことです。 このスクリプトは通常all.tclと命名されます。 なぜなら、多重テストスイーツを結合することで1つのテスト動作を形成する際、[ runAllTests ]によって使われるデフォルト名です。

[8]
下記は見本のテストスイーツマスタスクリプトのスケッチです。
package require Tcl 8.4
package require tcltest 2.2
package require example
tcltest::configure -testdir 
        [file dir [file normalize [info script]]]
eval tcltest::configure $argv
tcltest::runAllTests

互換性

tcltestの初期のリリースによって供給された::tcltest namespaceにあるいくつかのコマンド及び変数は、ここで記述されませんでした。 それらはtcltestのサポートする公式インタフェースの一部ではないので、新しいテストスイーツに使わないほうがいいものです。 しかし、古いインタフェース仕様に従って書かれた現存する古いテストスイーツ組をサポートし続けるために多数のお勧めではないコマンド、及び変数は、同様にまだ機能します。 例えば、多数の環境で[configure]は[package require tcltest 2.1]のすぐ後に自動的に呼ばれ、変数::argvからの引数を処理します。 これはtcltestがコマンドライン引数から自動的に形成された動作をする時代の名残りでテストスイーツをサポートするためです。 新規のテストファイルはこれに依存してはいけません。ですが、明白に下記を含みます。

eval tcltest::configure $::argv

コマンドライン引数から構築を制定するためです。

既知の問題

[テスト]のネストした評価について2つの既知の問題があります。 最初の問題はテストスクリプトが実行されるスタックレベルに関係します。 他のテストの中でネストしたテストは最も外側のテストと同じスタックレベルで実行される可能性があります。 例えば以下のコードにおいて

test level-1.1 {level 1} {
    -body {
        test level-2.1 {level 2} {
        }
    }
}

レベル‐2.1において実行された全てスクリプトは、レベル‐1.1のために定義されたスクリプトと同じスタックレベルで実行される可能性があります。

更に2つの [テスト] が実行されたとき、結果はテストレベル‐1.1と同じレベルのテストだけが[ cleanupTests ]によって報告されるでしょう。 しかし、テストレベル‐2.1が実行されるとき、レベル‐1.1の前に実行された全てのテストの結果 は利用可能です。 意味はテストレベルの‐2.1テスト結果をアクセスしたい場合、'm'テストのライン'n'テストはスキップさて、'o'テストは通 過され、'p'テストは失敗した、です。'm' 'n' 'o'そして'p'が参照するテストは同じテストレベル‐1.1です。

テストコマンドにおける出力及びエラー比較インプリメントは、アプリケーションコードにおけるputsの使用に依存します。 定義されたテストスクリプトが実行される際、putsコマンドを再定義することによって出力は遮されます。 C言語のプロシージャによってputされたエラー、及び直接Cアプリケーションから出力されたエラーは、テストコマンドによって捕えられないことになります。従って[テスト]での-output及び-errorOuputオプションの使用は、出力するためにputsを使用する純粋なTclアプリケーションのみに役に立ちます。

キーワード

test, test harness, test suite


Copyright © 1990-1994 The Regents of the University of California Copyright © 1994-1997 Sun Microsystems, Inc. Copyright © 1998-1999 Scriptics Corporation Copyright © 2000 Ajuba Solutions Copyright © 1995-1997 Roger E. Critchlow Jr.