## Tcl8.6.17/Tk8.6.17 Documentation > Tcl Commands > tcltest

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    tcltest — 運用している命令と便益を利用した試験　　　 Test harness support code and utilities
  SYNOPSIS
  説明 DESCRIPTION
  諸命令　COMMANDS
    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
  構成設定命令　　CONFIGURATION COMMANDS
    configure
    configure option
    configure option value ?-option value ...?
    customMatch mode script
    testConstraint constraint ?boolean?
    interpreter ?executableName?
    outputChannel ?channelID?
    errorChannel ?channelID?
  構成設定命令の短縮　　SHORTCUT CONFIGURATION COMMANDS
    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?
  他の命令　　OTHER COMMANDS
    test name description optionList
    workingDirectory ?directoryName?
    normalizeMsg msg
    normalizePath pathVar
    bytestring string
  TESTS
    -constraints keywordList|expression
    -setup script
    -body script
    -cleanup script
    -match mode
    -result expectedValue
    -output expectedValue
    -errorOutput expectedValue
    -returnCodes expectedCodeList
    -errorCode expectedErrorCode
  TEST CONSTRAINTS
    singleTestInterp
    unix
    win
    nt
    mac
    unixOrWin
    macOrWin
    macOrUnix
    tempNotWin
    tempNotMac
    unixCrash
    winCrash
    macCrash
    emptyTest
    knownBug
    nonPortable
    userInteraction
    interactive
    nonBlockFiles
    asyncPipeClose
    unixExecs
    hasIsoLocale
    root
    notRoot
    eformat
    stdio
  RUNNING ALL TESTS
  CONFIGURABLE OPTIONS
    -singleproc boolean
    -debug level
      0
      1
      2
      3
    -verbose level
      body (b)
      pass (p)
      skip (s)
      start (t)
      error (e)
      line (l)
      msec (m)
      usec (u)
    -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
  CREATING TEST SUITES WITH TCLTEST
  互換性　　COMPATIBILITY
  未解決の問題点　　KNOWN ISSUES
  KEYWORDS

### NAME

tcltest — 運用している命令と便益を利用した試験　　　 Test harness support code and utilities

### SYNOPSIS

package require tcltest ?2.5?
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?

### 説明 DESCRIPTION

この tcltest 梱包は､Tcl 命令の評価によって実行される機械語命令の為の組み試験を構築するに役立つ幾つかの命令を提供する｡取分けTcl 外部函数群の組込み命令そのものはtcltest梱包を使った組試験により試験される｡ 　　　　　　 The tcltest package provides several utility commands useful in the construction of test suites for code instrumented to be run by evaluation of Tcl commands. Notably the built-in commands of the Tcl library itself are tested by a test suite using the tcltest package.

この tcltest により提供される全ての命令は上述の 使用構文SYNOPSIS の中で指し示した様に ::tcltest 名前空間中で定義されたか其処から移入されたかである｡次の節では､簡潔さの為に全ての命令はその単純な名前を使って記述する｡ 　　　　　　　 All the commands provided by the tcltest package are defined in and exported from the ::tcltest namespace, as indicated in the SYNOPSIS above. In the following sections, all commands will be described by their simple names, in the interest of brevity.

tcltest の中心となる命令は test であってそれが試験を定義し実行する｡ test を使う試験はTcl 記述譜の評価と､指示項目の数による構成設定と制御に従った､結果と予想の結果との比較を含む｡ tcltest により提供される幾つかの他の命令は test の構成設定と､組試験に入れる多くの test 命令の集まりを管理する｡ 　　　　　 The central command of tcltest is test that defines and runs a test. Testing with test involves evaluation of a Tcl script and comparing the result to an expected result, as configured and controlled by a number of options. Several other commands provided by tcltest govern the configuration of test and the collection of many test commands into test suites.

読者のTcl を動作させる命令の為の組試験を作成する為に､如何にtcltest の命令を使用するかの拡張された用例については下の CREATING TEST SUITES WITH TCLTEST を参照されたい｡　　　　　 See CREATING TEST SUITES WITH TCLTEST below for an extended example of how to use the commands of tcltest to produce test suites for your Tcl-enabled code.

### 諸命令　COMMANDS

test name description ?-option value ...?
  名前 name と記述譜 description によって試験を定義し可能なら試験する｡試験の名称と記述譜は tcltest の指示項目によって構成設定されて､試験の間に test によって報告される伝達文に使用される｡残っている test の option value 引数は試験を定義する､それには､実行すべき記述譜､試験する条件､予想される結果､予想される結果と実際の結果を比較する手段､が含まれる｡適正な指示項目と如何に試験を定義するかとの完全な記述はしたの TESTS を参照されたい｡この test 命令は空文字列を返す｡　　　　　　 Defines and possibly runs a test with the name name and description description. The name and description of a test are used in messages reported by test during the test, as configured by the options of tcltest. The remaining option value arguments to test define the test, including the scripts to run, the conditions under which to run them, the expected result, and the means by which the expected and actual results should be compared. See TESTS below for a complete description of the valid options and how they define a test. The test command returns an empty string.

test name description ?constraints? body result
  この形式の test は tcltest 試験梱包の第１版の為に書かれた組試験を運用する為に提供され､又､共通の使用の為の単純な相互作用機能を提供する｡これは “test name description -constraints constraints -body body -result result” と同じである｡ test に対する他の全ての指示項目は無為設定の値をとる｡ constraints が省略された時､この形式の test は冒頭のものとは区別される､理由は､あちらは全ての option が “-” で始まるから｡ 　　　　　 This form of test is provided to support test suites written for version 1 of the tcltest package, and also a simpler interface for a common usage. It is the same as “test name description -constraints constraints -body body -result result”. All other options to test take their default values. When constraints is omitted, this form of test can be distinguished from the first because all options begin with “-”.

loadTestedCommands
  呼出し側の文脈中で configure -load か configure -loadfile により定義された記述譜を評価する｡その記述譜の評価結果を返す､なんであれ記述譜によって生じた不都合も返り値に含む｡組試験を実行する解釈実行機能に試験される命令を提供するために､この命令と関連した指示項目の構成設定を使用しなさい｡ 　　　　　　 Evaluates in the caller's context the script specified by configure -load or configure -loadfile. Returns the result of that script evaluation, including any error raised by the script. Use this command and the related configuration options to provide the commands to be tested to the interpreter running the test suite.

makeFile contents name ?directory?
  相対的な名前が name のファイルをディレクトリー directory に作成し､そのファイルに文字番号体系 encoding system を使って contents を書込む｡もし､ contents が改行記号で終ってないときは改行を追加し､名前が name のファイルを改行で終るファイルにする｡系の文字番号体系を使用するので､この命令は文章ファイルを作成する場合にのみ適している｡そのファイルは始めに removeFile で取除かない限り､次の cleanupTests による評価で取除かれる｡ directory の無為設定はディレクトリー configure -tmpdir である｡作成されたファイルの全経路を返す｡内容を伴う試験によって何か文書ファイルを作成するには､必要に応じてこのこの命令を使用されたい｡ 　　　　　 Creates a file named name relative to directory directory and write contents to that file using the encoding encoding system. If contents does not end with a newline, a newline will be appended so that the file named name does end with a newline. Because the system encoding is used, this command is only suitable for making text files. The file will be removed by the next evaluation of cleanupTests, unless it is removed by removeFile first. The default value of directory is the directory configure -tmpdir. Returns the full path of the file created. Use this command to create any text file required by a test with contents as needed.

removeFile name ?directory?
  name によって参照されるファイルの除去を強制する｡このファイル名は directory に相対的であることが望ましい｡ directory の無為設定はディレクトリー configure-tmpdir である｡空文字列を返す｡ makeFile によって作成したファイルの消去に使用しなさい｡　　　　　　 Forces the file referenced by name to be removed. This file name should be relative to directory. The default value of directory is the directory configure -tmpdir. Returns an empty string. Use this command to delete files created by makeFile.

makeDirectory name ?directory?
  ディレクトリー directory に相対的で名前が name のディレクトリーを作成する｡そのディレクトリーは始めに removeDirectory で取除かない限り､次の cleanupTests による評価で取除かれる｡ directory の無為設定はディレクトリー configure-tmpdir である｡作成されたディレクトリーの全経路を返す｡この命令を何であれ試験によって実在が要求されるディレクトリーの生成に使用しなさい｡ 　　　　　　 Creates a directory named name relative to directory directory. The directory will be removed by the next evaluation of cleanupTests, unless it is removed by removeDirectory first. The default value of directory is the directory configure -tmpdir. Returns the full path of the directory created. Use this command to create any directories that are required to exist by a test.

removeDirectory name ?directory?
  name によって参照されるディレクトリーの除去を強制する｡このディレクトリーは directory に相対的であることが望ましい｡ directory の無為設定はディレクトリー configure-tmpdir である｡空文字列を返す｡ makeDirectory によって作成したディレクトリーの消去に使用しなさい｡　　　　　　 Forces the directory referenced by name to be removed. This directory should be relative to directory. The default value of directory is the directory configure -tmpdir. Returns an empty string. Use this command to delete any directories created by makeDirectory.

viewFile file ?directory?
  file の内容を返す､但し恰も read-nonewline が返すであろう様に､末尾のどの改行記号も返さない｡このファイル名は directory に相対的であることが望ましい｡ directory の無為設定はディレクトリー configure-tmpdir である｡この命令を､試験によって作成されたファイルの内容を､予想された結果に対する合致の為の試験の結果､に変換する便利な方法として使用されたい｡ファイルの内容は系の文字番号体系を使用して読むのでその便利さは文章ファイルに限定される｡　　　　　　　 Returns the contents of file, except for any final newline, just as read -nonewline would return. This file name should be relative to directory. The default value of directory is the directory configure -tmpdir. Use this command as a convenient way to turn the contents of a file generated by a test into the result of that test for matching against an expected result. The contents of the file are read using the system encoding, so its usefulness is limited to text files.

cleanupTests
  幾つかの試験が実行された後の刷新とまとめが意図されている｡典型的には､試験ファイル毎に､全ての試験が完了した後にファイルの終わりの時点で､一度呼ばれる｡最善の効果の為には､cleanupTests はたとえ以前の試験ファイル評価で不都合が生じても実施することを確認すべきです｡　　　　　　 Intended to clean up and summarize after several tests have been run. Typically called once per test file, at the end of the file after all tests have been completed. For best effectiveness, be sure that the cleanupTests is evaluated even if an error occurs earlier in the test file evaluation.

  試験に関する統計を印刷し､前回の cleanupTests 以降に makeDirectory と makeFile によって作成されたファイルを取除く｡前回の cleanupTests 以降にディレクトリー configure-tmpdir 中に作成されはしたが､ makeDirectory と makeFile によって作成されたのではないファイルは outputChannel に印刷される｡この命令は､又､もとのシェルの環境を ::env 配列によって記述されたように再保存する｡空文字列を返す｡ 　　　　　 Prints statistics about the tests run and removes files that were created by makeDirectory and makeFile since the last cleanupTests. Names of files and directories in the directory configure -tmpdir created since the last cleanupTests, but not created by makeFile or makeDirectory are printed to outputChannel. This command also restores the original shell environment, as described by the global env array. Returns an empty string.

runAllTests
  この命令は親の命令で､その意味は､ tcltest の構成設定可能な指示項目により管理されつつ多ファイル 又は/且つ ディレクトリーに広がった全体の組試験を走らせる｡ runAllTests に関する可能多くの変種の完全な記述については下のRUNNING ALL TESTS を参照されたい｡ This is a main command meant to run an entire suite of tests, spanning multiple files and/or directories, as governed by the configurable options of tcltest. See RUNNING ALL TESTS below for a complete description of the many variations possible with runAllTests.

#### 構成設定命令　　CONFIGURATION COMMANDS

configure
  tcltest に対応されている構成設定可能な指示項目のリストを返す｡全ての指示項目のリストと､その適正な値と､ tcltest 操作への効果､については下の CONFIGURABLE OPTIONS を参照されたい｡　　　　　 Returns the list of configurable options supported by tcltest. See CONFIGURABLE OPTIONS below for the full list of options, their valid values, and their effect on tcltest operations.

configure option
  対応している構成設定可能な指示項目 option の現在の値を返す｡もし option が運用されている構成設定可能な指示項目ではない場合は不都合を返す｡　　　　　　 Returns the current value of the supported configurable option option. Raises an error if option is not a supported configurable option.

configure option value ?-option value ...?
  それぞれの構成設定可能な指示項目 option に対応する値 value をその順に設定する｡もし option が運用されている構成設定可能な指示項目ではないか､値がそれぞれの対応する option に対して適当でないか､ value が提供されない場合は不都合を掲げる｡不都合が掲げられた時は､ configure の操作は停止され､それに続く option value 引数は処理されない｡ 　　　　　 Sets the value of each configurable option option to the corresponding value value, in order. Raises an error if an option is not a supported configurable option, or if value is not a valid value for the corresponding option, or if a value is not provided. When an error is raised, the operation of configure is halted, and subsequent option value arguments are not processed.

  tcltest 梱包が積込まれる時に(package require tcltestによって)､環境変数 ::env(TCLTEST_OPTIONS) が実在すると､その値は configure に渡す引数のリストとして扱う｡これにより構成設定可能が指示項目の無為設定の値を環境によって設定されることを許容する｡　　　　　　 If the environment variable ::env(TCLTEST_OPTIONS) exists when the tcltest package is loaded (by package require tcltest) then its value is taken as a list of arguments to pass to configure. This allows the default values of the configuration options to be set by the environment.

customMatch mode script
  test に対する -match 指示項目の新しい適正な値として mode を登録する｡ -match mode 指示項目が test に渡される時､試験の本体を評価した実際の結果を予想する値と比較する為に記述譜 script が評価される｡合致を遂行する為に､script は二つの追加的な語の､予想値と､実際の結果と一緒に完成され､完成した記述譜が大域名前空間の中で評価される｡完成した記述譜は結果は合致するか否かを指し示す論理値を持ち返ると期待される｡組み込まれたtest の合致方法は exact と glob と regexp である｡　　　　　　 Registers mode as a new legal value of the -match option to test. When the -match mode option is passed to test, the script script will be evaluated to compare the actual result of evaluating the body of the test to the expected result. To perform the match, the script is completed with two additional words, the expected result, and the actual result, and the completed script is evaluated in the global namespace. The completed script is expected to return a boolean value indicating whether or not the results match. The built-in matching modes of test are exact, glob, and regexp.

testConstraint constraint ?boolean?
  指名された constraint と関連する論理値を設定又は返す｡更なる情報は下の TEST CONSTRAINTS を参照されたい｡　　　　　　 Sets or returns the boolean value associated with the named constraint. See TEST CONSTRAINTS below for more information.

interpreter ?executableName?
  configure -singleproc が偽値の時､それぞれの試験ファイルを実行execする為に runAllTests によって実行された実行可能の名前を設定又は返す｡ interpreter の為の無為設定は info nameofexecutable から返ったとして現在に実行されている算譜の名前である｡　　　　　　 Sets or returns the name of the executable to be execed by runAllTests to run each test file when configure -singleproc is false. The default value for interpreter is the name of the currently running program as returned by info nameofexecutable.

outputChannel ?channelID?
  出力用の通信路識別子を設定又は返す｡この無為設定は標準出力stdoutである｡出力に関る試験を印刷するどの試験でもその出力を無為設定の標準出力stdoutに行かせるのではなくその出力を outputChannel に送ろうとする｡　　　　　 Sets or returns the output channel ID. This defaults to stdout. Any test that prints test related output should send that output to outputChannel rather than letting that output default to stdout.

errorChannel ?channelID?
  不都合出力用の通信路識別子を設定又は返す｡この無為設定は標準不都合出力stderrである｡不都合伝言文を印刷するどの試験でも直接に標準不都合出力stderrに印刷するのではなくその出力を errorChannel に送ろうとする｡　　　　　　 Sets or returns the error channel ID. This defaults to stderr. Any test that prints error messages should send that output to errorChannel rather than printing directly to stderr.

#### 構成設定命令の短縮　　SHORTCUT CONFIGURATION COMMANDS

debug ?level?
  configure -debug ?level? と同一である｡　　　　　　　 Same as “configure -debug ?level?”.

errorFile ?filename?
  Same as “configure -errfile ?filename?”.

limitConstraints ?boolean?
  Same as “configure -limitconstraints ?boolean?”.

loadFile ?filename?
  Same as “configure -loadfile ?filename?”.

loadScript ?script?
  Same as “configure -load ?script?”.

match ?patternList?
  Same as “configure -match ?patternList?”.

matchDirectories ?patternList?
  Same as “configure -relateddir ?patternList?”.

matchFiles ?patternList?
  Same as “configure -file ?patternList?”.

outputFile ?filename?
  Same as “configure -outfile ?filename?”.

preserveCore ?level?
  Same as “configure -preservecore ?level?”.

singleProcess ?boolean?
  Same as “configure -singleproc ?boolean?”.

skip ?patternList?
  Same as “configure -skip ?patternList?”.

skipDirectories ?patternList?
  Same as “configure -asidefromdir ?patternList?”.

skipFiles ?patternList?
  Same as “configure -notfile ?patternList?”.

temporaryDirectory ?directory?
  Same as “configure -tmpdir ?directory?”.

testsDirectory ?directory?
  Same as “configure -testdir ?directory?”.

verbose ?level?
  Same as “configure -verbose ?level?”.

#### 他の命令　　OTHER COMMANDS

tcltest によって提供される残りの命令は tcltest や Tcl 自身に提供されるものよりも好ましい代用命令である｡それらは既存の組試験を運営する為に残してあるが､新しい命令には避ける方が好ましい｡　　　　　　 The remaining commands provided by tcltest have better alternatives provided by tcltest or Tcl itself. They are retained to support existing test suites, but should be avoided in new code.

test name description optionList
  この形式の test は､ test の引数の間にある改行を逆斜線引用化する必要のある方法よりも､幾つかの行に跨った多くの指示項目を波括弧で括って一つの引数として test に渡す事を可能にすることを提供する｡この optionList 引数は option と value を表す偶数の要素があるリストであって引数として test に渡すと期待される｡しかし､これらの値は別の switch の中の形式と同じく直接には渡されない｡代りにこの形式は､Tcl の置換規則を波括弧で括った “団塊” の “良きに計らへ” 式解釈を実現する試みとして幾つかのリスト要素に置換を遂行することにより挿げ替えるとの不幸な試みをさせる｡結果は､明快に文書化することは殆ど不可能で､この理由によりこの形式は推奨されない｡この形式が本当には逆斜線引用の行替えを避ける為に必要ではないことを見る為に､下の CREATING TEST SUITES WITH TCLTEST 中の例を参照されたい｡もし､この形式の利用を計画しているなら､ tcltest の源譜を調べ､詳細な置換を知りたいのか､単に test の第３番目から最後までの引数を波括弧で括りたいだけなのかを調べ､最善を期されたい｡　　　　　 This form of test was provided to enable passing many options spanning several lines to test as a single argument quoted by braces, rather than needing to backslash quote the newlines between arguments to test. The optionList argument is expected to be a list with an even number of elements representing option and value arguments to pass to test. However, these values are not passed directly, as in the alternate forms of switch. Instead, this form makes an unfortunate attempt to overthrow Tcl's substitution rules by performing substitutions on some of the list elements as an attempt to implement a “do what I mean” interpretation of a brace-enclosed “block”. The result is nearly impossible to document clearly, and for that reason this form is not recommended. See the examples in CREATING TEST SUITES WITH TCLTEST below to see that this form is really not necessary to avoid backslash-quoted newlines. If you insist on using this form, examine the source code of tcltest if you want to know the substitution details, or just enclose the third through last argument to test in braces and hope for the best.

workingDirectory ?directoryName?
  現在の活動ディレクトリーを設定するか返すか｡活動ディレクトリーの無為設定は､その中に組み試験が起動するディレクトリーである｡ Tcl 命令の cd と pwd は使うと取換えを行いうる｡　　　　　　 Sets or returns the current working directory when the test suite is running. The default value for workingDirectory is the directory in which the test suite was launched. The Tcl commands cd and pwd are sufficient replacements.

normalizeMsg msg
  msg から “余分” の改行を取除いて返す､ここで “余分” は幾分不正確である｡Tcl は文字列を好みに修正する為に多くの文字列操作命令を提供する､そして customMatch が､実際の期待する結果との柔軟な合致をもたらす｡　　　　　　 Returns the result of removing the “extra” newlines from msg, where “extra” is rather imprecise. Tcl offers plenty of string processing commands to modify strings as you wish, and customMatch allows flexible matching of actual and expected results.

normalizePath pathVar
  内部の再方向変更なしに経路中の象徴的連結を決定する｡pathVar は絶対表示であることを仮定している｡ pathVar は適切に修正されている｡ Tcl 命令の file normalize を使うと取換えを行い得る｡　　　　　　 Resolves symlinks in a path, thus creating a path without internal redirection. It is assumed that pathVar is absolute. pathVar is modified in place. The Tcl command file normalize is a sufficient replacement.

bytestring string
  要求されたバイトの並びからなる文字列を構築する､ string 中に供給された値を使ってUTF-8 文字を適正な文字列に形成することの反対のように｡これにより､試験者に非正規化又は不適切な形式の文字列をC言語手続函数に渡す為に作成することを許容し､それがヌル文字を埋め込んだ型の文字列を受取り､そして文字列の結果はバイトの特定の模様を有していることを確信することを許容する｡これは厳密に Tcl 命令の encoding convertfrom identity と等価である｡ この函数は非推奨である｡ 　　　　　　　　 Construct a string that consists of the requested sequence of bytes, as opposed to a string of properly formed UTF-8 characters using the value supplied in string. This allows the tester to create denormalized or improperly formed strings to pass to C procedures that are supposed to accept strings with embedded NULL types and confirm that a string result has a certain pattern of bytes. This is exactly equivalent to the Tcl command encoding convertfrom identity. This function is deprecated.

### TESTS

この test 命令は tcltest 梱包の心臓部である｡その本質的機能は Tcl 記述譜を評価し､その結果と予想される結果とを比較することである｡ test の指示項目は､記述譜と､評価する環境と､予想結果と､如何にして実際の結果と予想結果とを比較するか､とを定義する｡幾つかの tcltest の構成設定指示項目も如何に test 操作を行うかに影響を及ぼす｡ 　　　　　　　 The test command is the heart of the tcltest package. Its essential function is to evaluate a Tcl script and compare the result with an expected result. The options of test define the test script, the environment in which to evaluate it, the expected result, and how the compare the actual result to the expected result. Some configuration options of tcltest also influence how test operates.

test の為の適正な指示項目をまとめる:　　　　　　 The valid options for test are summarized:

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

name はどの様な文字列でもよい｡これは､模様に従って name を選ぶために便利である: 　　　　　　 The name may be any string. It is conventional to choose a name according to the pattern:

    target-majorNum.minorNum

既知構造用試験(再確認)では､目標は､試験される C言語函数か Tcl 手続函数である｡未知構造用試験では目標は試験される特性の名前である｡幾つかの慣習では未知構造用試験の名前を接尾辞 _bb (black-boxの略称)を付けて呼ばれる｡関連する試験は主要番号を共有するべきであろう｡組試験を発展するには､同じ試験名は対応する同じ試験を継続させることがよい､そこで意味を有するように残して､この様に､ “試験foo-1.3 は3.4版迄の全ての版に成功したが3.5版で失敗し始めた(Test foo-1.3 passed in all releases up to 3.4, but began failing in release 3.5.)” ｡　　　　　　　　 For white-box (regression) tests, the target should be the name of the C function or Tcl procedure being tested. For black-box tests, the target should be the name of the feature being tested. Some conventions call for the names of black-box tests to have the suffix _bb. Related tests should share a major number. As a test suite evolves, it is best to have the same test name continue to correspond to the same test, so that it remains meaningful to say things like “Test foo-1.3 passed in all releases up to 3.4, but began failing in release 3.5.”

test の評価中 name は configure-match と configure-skip とから返った文字列合致模様のリストと比較される｡もし name が configure-match から返った模様のどれかと合致し､ configure-skip から返ったどの模様とも合致しなかった場合にのみ試験が実行される｡　　　　　　　　 During evaluation of test, the name will be compared to the lists of string matching patterns returned by configure -match, and configure -skip. The test will be run only if name matches any of the patterns from configure -match and matches none of the patterns from configure -skip.

この description は簡潔な試験の本文の記述であるべきである｡その description は試験によって生産される出力､典型的には､試験の失敗の伝言文に含まれる｡良好な description の値は､簡潔に組試験使用者に試験の目的を説明するべきである｡試験される Tcl や C の函数の名前は､回帰試験の為の記述中に含まれるべきである｡もし試験の結果が不具合を再生産する場合､不具合番号を記述に含むべきである｡　　　　　　　　 The description should be a short textual description of the test. The description is included in output produced by the test, typically test failure messages. Good description values should briefly explain the purpose of the test to users of a test suite. The name of a Tcl or C function being tested should be included in the description for regression tests. If the test case exists to reproduce a bug, include the bug ID in the description.

適正な属性と対応する値は:　　　　　　 Valid attributes and associated values are:

-constraints keywordList|expression
  追加的な -constraints 属性は一つ或はそれ以上の鍵語や表現のリストです｡もし､ -constraints の値が鍵語のリストであると､それぞれの鍵語は testConstraint の呼出しによって定義した拘束子の名前であろう｡どれであれ､列挙した拘束子が偽値であるか､または実在しない場合は､試験は飛越される｡もし､ -constraints 値が式であると､その式は評価される｡もし式の評価が真値になると､その試験は実施される｡註意すべきは､ -constraints の式は configure-constraints や configure-limitconstraints の操作との相互作用機能であるかもしれず､それは推奨できない｡適切な拘束子がどの試験にも付加されるべきであるが常には実行すべきではない｡即ち､試験の条件の評価は -constraints 指示項目によって成し遂げられるべきで､ test の条件付きの評価によるべきではない｡そのように､試験の同じ番号は常に組試験により報告され､飛越した番号は試験の環境の基本の変更であるかもしれない｡無為設定は空リストである｡組み込まれた拘束子のリストと如何に使用者自身の拘束子を付加するかについては下の TEST CONSTRAINTS を参照されたい｡　　　　　　 The optional -constraints attribute can be list of one or more keywords or an expression. If the -constraints value is a list of keywords, each of these keywords should be the name of a constraint defined by a call to testConstraint. If any of the listed constraints is false or does not exist, the test is skipped. If the -constraints value is an expression, that expression is evaluated. If the expression evaluates to true, then the test is run. Note that the expression form of -constraints may interfere with the operation of configure -constraints and configure -limitconstraints, and is not recommended. Appropriate constraints should be added to any tests that should not always be run. That is, conditional evaluation of a test should be accomplished by the -constraints option, not by conditional evaluation of test. In that way, the same number of tests are always reported by the test suite, though the number skipped may change based on the testing environment. The default value is an empty list. See TEST CONSTRAINTS below for a list of built-in constraints and information on how to add your own constraints.

-setup script
  追加的な -setup 属性は script が -body 属性が指し示す記述譜より前に実行されることを指し示す｡もし script の評価が不都合を掲げると､試験は失敗する｡無為設定の値は空文字列である｡　　　　　　 The optional -setup attribute indicates a script that will be run before the script indicated by the -body attribute. If evaluation of script raises an error, the test will fail. The default value is an empty script.

-body script
  -body 属性は script が試験を遂行する為に実行されることを指し示す､それは､正しさを確認することが可能な結果を必ず返す｡もし script の評価が不都合を生じた場合､結果は十敗する(不都合を期待することを宣言する -returnCodes 指示項目が使われない限り)｡無為設定の値は空文字列である｡ The -body attribute indicates the script to run to carry out the test, which must return a result that can be checked for correctness. If evaluation of script raises an error, the test will fail (unless the -returnCodes option is used to state that an error is expected). The default value is an empty script.

-cleanup script
  追加指示的な -cleanup 属性は script が -body 属性が指し示す記述譜の後に実行されることを指し示す｡もし script の評価が不都合を掲げると､試験は失敗する｡無為設定の値は空文字列である｡　　　　　　 The optional -cleanup attribute indicates a script that will be run after the script indicated by the -body attribute. If evaluation of script raises an error, the test will fail. The default value is an empty script.

-match mode
  -match 属性は -result と -output と -errorOutput により与えられる予想された応答を如何に比較するかを決定する｡mode の為の適正な値は regexp と glob と exact と予め呼出した customMatch により登録されたどの様な値でもよい｡無為設定の値は exact である｡　　　　　 The -match attribute determines how expected answers supplied by -result, -output, and -errorOutput are compared. Valid values for mode are regexp, glob, exact, and any value registered by a prior call to customMatch. The default value is exact.

-result expectedValue
  この -result 属性は､記述譜からの値が比較される expectedValue を与える｡無為設定の値は空文字列である｡　　　　　　　　 The -result attribute supplies the expectedValue against which the return value from script will be compared. The default value is an empty string.

-output expectedValue
  この -output 属性は､記述譜の評価中に stdout か outputChannel に送られたどの様な出力とも値が比較される expectedValue を与える｡註意すべきは大域的 puts 命令を使用して印刷された出力のみが比較に使われる｡もし -output が指定されていないと stdout と outputChannel に送られた出力は比較の為には処理されない｡　　　　　　 The -output attribute supplies the expectedValue against which any output sent to stdout or outputChannel during evaluation of the script(s) will be compared. Note that only output printed using the global puts command is used for comparison. If -output is not specified, output sent to stdout and outputChannel is not processed for comparison.

-errorOutput expectedValue
  この -errorOutput 属性は､記述譜の評価中に stderr か errorOutput に送られたどの様な出力とも値が比較される expectedValue を与える｡註意すべきは大域 puts 命令を使用して印刷された出力のみが比較に使われる｡もし -errorOutput が指定されていないと stderr と errorChannel に送られた出力は比較の為には保持されない｡ 　　　　　　 The -errorOutput attribute supplies the expectedValue against which any output sent to stderr or errorChannel during evaluation of the script(s) will be compared. Note that only output printed using the global puts command is used for comparison. If -errorOutput is not specified, output sent to stderr and errorChannel is not processed for comparison.

-returnCodes expectedCodeList
  この追加指示的な -returnCodes 属性は､ -body 記述譜の評価からの返りが受付けられるであろう返り記号のリスト expectedValue を与える｡もし -body 記述譜の評価が expectedCodeList の中にない記号を返すと､試験は失敗する｡無為設定の値は空文字列である｡全ての戻り記号は return に知られている､数字番号と象徴的記号の両方と､拡張返り記号を含む､それらはexpectedCodeList の要素に受入れられる｡無為設定の値は “ok return” である｡　　　　　　 The optional -returnCodes attribute supplies expectedCodeList, a list of return codes that may be accepted from evaluation of the -body script. If evaluation of the -body script returns a code not in the expectedCodeList, the test fails. All return codes known to return, in both numeric and symbolic form, including extended return codes, are acceptable elements in the expectedCodeList. Default value is “ok return”.

-errorCode expectedErrorCode
  追加的 -errorCode 属性は expectedErrorCode を提供する､それは､展開文様であって -body 記述譜の評価から報告された不都合番号に合致する筈である｡もし､ -body 記述譜の評価が返す符号が expectedErrorCode に合致しない場合､試験は失敗する｡無為設定の値は “*” である｡もし -returnCodes が不都合を含まない場合､不都合が設定される｡　　　　　　 The optional -errorCode attribute supplies expectedErrorCode, a glob pattern that should match the error code reported from evaluation of the -body script. If evaluation of the -body script returns a code not matching expectedErrorCode, the test fails. Default value is “*”. If -returnCodes does not include error it is set to error.

通過する為に試験は成功裡にその -setup と -body と -cleanup の記述譜を評価する必要がある｡ -body 記述譜の戻り記号とその結果は予想値に合致しなくてはならない､そしてもし指定されると試験の出力と不都合データは予想される -output と -errorOutput の値と合致しなくてはならない｡もし何であれこれらの条件が合致しない場合､試験は失敗する｡註意すべきは､全ての記述譜は test の呼出し側の文脈中で評価される｡　　　　　 To pass, a test must successfully evaluate its -setup, -body, and -cleanup scripts. The return code of the -body script and its result must match expected values, and if specified, output and error data from the test must match expected -output and -errorOutput values. If any of these conditions are not met, then the test fails. Note that all scripts are evaluated in the context of the caller of test.

適切な文脈と共に､それと全ての属性に対する適正な値とともに test が呼出されている限り不都合が生じることはない｡試験の失敗はoutputChannel に対する書かれた出力として代りに報告される｡無為設定の操作では成功した試験は出力を何も生成しない｡ test によって生成された出力伝言文は下の CONFIGURABLE OPTIONS の中で記述したように configure-verbose 指示項目によって制御されている｡試験記述譜そのものによって生成されたどの様な出力もoutputChannel 又は errorChannel 向けに puts を使って生成するべきで､そうすると､組試験の使用者は容易に configure-outfile や configure-errfile 指示項目による出力を捕捉でき､それにより -output と -errorOutput 属性は適正に稼動する｡　　　　　　 As long as test is called with valid syntax and legal values for all attributes, it will not raise an error. Test failures are instead reported as output written to outputChannel. In default operation, a successful test produces no output. The output messages produced by test are controlled by the configure -verbose option as described in CONFIGURABLE OPTIONS below. Any output produced by the test scripts themselves should be produced using puts to outputChannel or errorChannel, so that users of the test suite may easily capture output with the configure -outfile and configure -errfile options, and so that the -output and -errorOutput attributes work properly.

#### TEST CONSTRAINTS

拘束子は試験を飛越すべきか否かの決定に使われる｡それぞれの拘束子は､何かの文字列の名前を有し､又論理値を有す｡それぞれの test は -constraints 値を有し､それは拘束の名前のリストである｡拘束子の制御には二つの方法がある｡最も頻繁には､ configure-limitconstraints の設定を偽値にすることにより指定される無為設定が使用される｡この試験はリスト中の全ての拘束が真値であるときのみ実施される｡従って､ test の -constraints 指示項目は可能であるか､または意味があるために､試験に必要なすべての条件を定義するのに便利な､象徴的な方法である｡譬えば､ -constraints unix を伴った test は拘束子 unix が真値の時にのみ実行される､それは､組試験が Unix のOS上で実行されることを指し示す｡　　　　　 Constraints are used to determine whether or not a test should be skipped. Each constraint has a name, which may be any string, and a boolean value. Each test has a -constraints value which is a list of constraint names. There are two modes of constraint control. Most frequently, the default mode is used, indicated by a setting of configure -limitconstraints to false. The test will run only if all constraints in the list are true-valued. Thus, the -constraints option of test is a convenient, symbolic way to define any conditions required for the test to be possible or meaningful. For example, a test with -constraints unix will only be run if the constraint unix is true, which indicates the test suite is being run on a Unix platform.

それぞれの test は､何であれ､それが適切な処でのみ実行する様に拘束することを要求される -constraints が含まれるべきである｡幾つかの拘束子は tcltest 梱包の中で下に列挙した様に予備的に定義されている｡使用者定義の拘束子の登録は testConstraint 命令によって実行される｡使用者定義の拘束子は､試験ファイルの内部､又は､または configure-load か configure-loadfile 指示項目によって指定された記述譜の内部にある｡　　　　　 Each test should include whatever -constraints are required to constrain it to run only where appropriate. Several constraints are predefined in the tcltest package, listed below. The registration of user-defined constraints is performed by the testConstraint command. User-defined constraints may appear within a test file, or within the script specified by the configure -load or configure -loadfile options.

以下のものは tcltest 梱包そのものに予備定義された拘束子のリストである: 　　　　　　 The following is a list of constraints predefined by the tcltest package itself:

singleTestInterp
  この試験は全ての試験ファイルが一つの解釈実行機能の中に源譜ファイル指定されている時のみ実行される｡　　　　　　 This test can only be run if all test files are sourced into a single interpreter.

unix
  この試験はどれかのUnix のOSでのみ実行され得る｡　　　　　　 This test can only be run on any Unix platform.

win
  この試験はどれかの Windows のOSでのみ実行され得る｡　　　　　　 This test can only be run on any Windows platform.

nt
  この試験はどれかの Windows NT のOSでのみ実行され得る｡　　　　　　 This test can only be run on any Windows NT platform.

mac
  この試験はどれかの Mac のOSでのみ実行され得る｡　　　　　 This test can only be run on any Mac platform.

unixOrWin
  この試験は Unix か Windows のOSでのみ実行される｡　　　　　　 This test can only be run on a Unix or Windows platform.

macOrWin
  この試験は Mac か Windows のOSでのみ実行される｡　　　　　 This test can only be run on a Mac or Windows platform.

macOrUnix
  この試験は Mac か Unix のOSでのみ実行される｡　　　　　 This test can only be run on a Mac or Unix platform.

tempNotWin
  この試験は Windows 上では実行されない｡この旗標は一時的に試験を無効にするために使われる｡ 　　　　 This test can not be run on Windows. This flag is used to temporarily disable a test.

tempNotMac
  この試験はMac上では実行されない｡この旗標は一時的に試験を無効にするために使われる｡　　　　　　 　 This test can not be run on a Mac. This flag is used to temporarily disable a test.

unixCrash
  この試験はUnix 上で実行された場合は砕ける｡この旗印は臨時的に試験不能の為に使用される｡　　　　　　 This test crashes if it is run on Unix. This flag is used to temporarily disable a test.

winCrash
  この試験は Windows 上で実行された場合は砕ける｡この旗印は臨時的に試験不能の為に使用される｡　　　　　　 This test crashes if it is run on Windows. This flag is used to temporarily disable a test.

macCrash
  この試験は Mac 上で実行された場合は砕ける｡この旗印は臨時的に試験不能の為に使用される｡　　　　　 This test crashes if it is run on a Mac. This flag is used to temporarily disable a test.

emptyTest
  この試験は空であり､従って実行する価値がない､しかし､将来試験が書かれる位置を保有する為に残している｡この拘束子は値偽値を有し､使用者が別途指定しない限り試験が飛越されることになる｡　　　　　　　 This test is empty, and so not worth running, but it remains as a place-holder for a test to be written in the future. This constraint has value false to cause tests to be skipped unless the user specifies otherwise.

knownBug
  この試験は失敗し､不具合が未だ修理されていないことが知られている｡この拘束子は値偽値を有し､使用者が別途指定しない限り試験が飛越されることになる｡ 　　　　　 This test is known to fail and the bug is not yet fixed. This constraint has value false to cause tests to be skipped unless the user specifies otherwise.

nonPortable
  この試験は知られた開発環境でのみ実行できる｡ある試験が本来非互換性であり､理由は語の長さ､ファイルの構成設定､窓管理譜､等のようなことに依存しているため｡この拘束子は値偽値を有し､使用者が別途指定しない限り試験が飛越されることになる｡　　　　　　 This test can only be run in some known development environment. Some tests are inherently non-portable because they depend on things like word length, file system configuration, window manager, etc. This constraint has value false to cause tests to be skipped unless the user specifies otherwise.

userInteraction
  この試験は使用者の介入を要す｡この拘束子は値偽値を有し､使用者が別途指定しない限り試験が飛越されることになる｡　　　　 This test requires interaction from the user. This constraint has value false to causes tests to be skipped unless the user specifies otherwise.

interactive
  この試験は解釈実行機能が対話方法になっている時にのみ実行される(大域tcl_interactive 変数が1に設定されている) 　　　　　　 This test can only be run in if the interpreter is in interactive mode (when the global tcl_interactive variable is set to 1).

nonBlockFiles
  このファイルが非同期方法に入る設定をOSが運用しているときのみ試験は実行される｡　　　　　　 This test can only be run if platform supports setting files into nonblocking mode.

asyncPipeClose
  パイプ上の非同期払出しと非同期閉鎖をOSが運用しているときのみこの試験は実行される｡　　　　　　 This test can only be run if platform supports async flush and async close on a pipe.

unixExecs
  Unix-方式の命令のcat, echo, sh, wc, rm, sleep, fgrep, ps, chmod, and mkdir が利用できるときのみこの試験は実行される｡　　　　　　 This test can only be run if this machine has Unix-style commands cat, echo, sh, wc, rm, sleep, fgrep, ps, chmod, and mkdir available.

hasIsoLocale
  ISO 地域化情報への切替が可能であるときのみこの試験は実行される｡　　　　　　 This test can only be run if can switch to an ISO locale.

root
  この試験はUnix 使用者が根元であるときのみ実行できる｡　　　　　　 This test can only run if Unix user is root.

notRoot
  この試験はUnix 使用者が根元でないときのみ実行できる｡　　　　　　 This test can only run if Unix user is not root.

eformat
  この試験は､応用譜が浮動小数書式の “e” 形式を考慮したsprintf が動く版を有している時のみ実行できる｡　　　　　 This test can only run if app has a working version of sprintf with respect to the “e” format of floating-point numbers.

stdio
  この試験は解釈実行機能がパイプとして開けられる時にのみ実行される｡　　　　　 This test can only be run if interpreter can be opened as a pipe.

拘束子の制御のもう一つの方法は configure -limitconstraints を真値に設定することで可能になる｡この構成設定の設定で､ configure -constraints によって返って来るリスト以外の全ての実在する拘束は偽値に設定される｡ configure -constraints 値が設定される時､これらの値は全て真値に設定される｡指示項目の configure -constraints と configure -limitconstraints との両方が使用されると､ configure -constraints リスト由来の拘束子のみを含む試験のみが実行される; それ以外全て飛越される｡譬えば､ここで構成設定を次の様に設定する｡　　　　　 The alternative mode of constraint control is enabled by setting configure -limitconstraints to true. With that configuration setting, all existing constraints other than those in the constraint list returned by configure -constraints are set to false. When the value of configure -constraints is set, all those constraints are set to true. The effect is that when both options configure -constraints and configure -limitconstraints are in use, only those tests including only constraints from the configure -constraints list are run; all others are skipped. For example, one might set up a configuration with

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

既知の不具合を行使するような試験を正確に実行し､そしてそれらのどれかに合格するかが判ると､その不具合が修理されている事を指し示す｡ 　　　　　　 to run exactly those tests that exercise known bugs, and discover whether any of them pass, indicating the bug had been fixed.

#### RUNNING ALL TESTS

単一命令 runAllTests は多くのファイルとディレクトリーに跨っている組試験全体の実行を評価する｡ tcltest の構成設定選択肢は正確な操作を制御する｡ runAllTests 命令はその outputChannel への構成設定の要約の印刷によって始まる｡　　　　　 The single command runAllTests is evaluated to run an entire test suite, spanning many files and directories. The configuration options of tcltest control the precise operations. The runAllTests command begins by printing a summary of its configuration to outputChannel.

評価されるべき試験ファイルはディレクトリー configure -testdir の中から見付かる｡そのディレクトリーの中の configure -file の中のどれかの模様に合致し且つconfigure -notfile の中の模様のどれにも合致しないファイルのリストが生成され､整列される｡次にそれぞれのファイルが順次評価される｡もし､ configure -singleproc が真値であれば､それぞれのファイルは呼出側の文脈の中で源譜ファイルに指定される｡もし､偽値であれば､それぞれのファイルを評価する為に解釈実行機能の複写が実行される｡処理課程が終了するかもしれない程過酷な不都合を引起す試験をする時は､多重処理の操作が便利である｡その様な不都合が子供の処理課程を試験している一つのファイルを終了させても､親の処理課程は残りの組試験を続行することが可能である｡多重処理の操作内では､親の処理課程内のtcltest の構成設定は子供の処理課程に命令行引数として､ configure -outfile によるものを除いて渡される｡親の処理課程内の runAllTests 命令は全ての子供の処理課程からの出力を集め､その結果の順番を揃えて一つの親の報告にする｡個別の失敗のどの報告も､ configure -verbose の設定に要求された伝言文も親の処理課程によって直接に outputChannel に渡される｡ 　　　　　　　 Test files to be evaluated are sought in the directory configure -testdir. The list of files in that directory that match any of the patterns in configure -file and match none of the patterns in configure -notfile is generated and sorted. Then each file will be evaluated in turn. If configure -singleproc is true, then each file will be sourced in the caller's context. If it is false, then a copy of interpreter will be exec'd to evaluate each file. The multi-process operation is useful when testing can cause errors so severe that a process terminates. Although such an error may terminate a child process evaluating one file, the main process can continue with the rest of the test suite. In multi-process operation, the configuration of tcltest in the main process is passed to the child processes as command line arguments, with the exception of configure -outfile. The runAllTests command in the main process collects all output from the child processes and collates their results into one main report. Any reports of individual test failures, or messages requested by a configure -verbose setting are passed directly on to outputChannel by the main process.

全ての選択された試験ファイルの評価の後､結果の要約が outputChannel に印刷される｡その要約は､評価されたファイルの数と､試験に失敗したか不都合になったファイルの名前とを書留めている｡又､飛越される試験を引起した拘束子のリストと､それぞれの飛越した試験の数も印刷される｡又､もし､試験ファイルの評価により何かの臨時ファイルが configure -tmpdir 内の後に留められることが引起されることが出現すると伝言文が印刷される｡　　　　　　 After evaluating all selected test files, a summary of the results is printed to outputChannel. The summary includes the total number of tests evaluated, broken down into those skipped, those passed, and those failed. The summary also notes the number of files evaluated, and the names of any files with failing tests or errors. A list of the constraints that caused tests to be skipped, and the number of tests skipped for each is also printed. Also, messages are printed if it appears that evaluation of a test file has caused any temporary files to be left behind in configure -tmpdir.

全ての選択されたファイルが完了し､要約されると､runAllTests は､次に､configure -relateddir に該当する子供のディレクトリー上に､再帰的に作動する｡configure -relateddir の中のどれかの模様に合致し且つconfigure -asidefromdir の中の模様のどれにも合致しない全ての子供のディレクトリーが調べられる｡その様なディレクトリーの中に all.tcl と言う名前のファイルが見付ると呼出し側の文脈の中で源譜に指定される｡調査しているディレクトリーが all.tcl を含んでいるか否かによらず､その子供のディレクトリーも configure -relateddir と configure -asidefromdir の模様に対して調べられる｡このようにしてディレクトリー樹枝中の多くのディレクトリーは､その全ての試験ファイルを一個の runAllTests 命令によって評価させることができる｡　　　　　　 Having completed and summarized all selected test files, runAllTests then recursively acts on subdirectories of configure -testdir. All subdirectories that match any of the patterns in configure -relateddir and do not match any of the patterns in configure -asidefromdir are examined. If a file named all.tcl is found in such a directory, it will be sourced in the caller's context. Whether or not an examined directory contains an all.tcl file, its subdirectories are also scanned against the configure -relateddir and configure -asidefromdir patterns. In this way, many directories in a directory tree can have all their test files evaluated by a single runAllTests command.

### CONFIGURABLE OPTIONS

この configure 命令は tcltest の構成設定可能な指示項目の設定と問合せに使われる｡適正な指示項目は:　　　　 The configure command is used to set and query the configurable options of tcltest. The valid options are:

-singleproc boolean
  runAllTests が子供の処理課程を再生産するか否かを制御する｡論理値が真値の時は再生産は行われない｡無為設定は偽値｡　　　　　　　 Controls whether or not runAllTests spawns a child process for each test file. No spawning when boolean is true. Default value is false.

-debug level
  不具合修理水準を level に､即ち､整数であって､不具合情報が標準出力に如何に沢山印刷されるかに設定する｡註意すべきは､不具合伝達文は configure -outfile の値とは無関係に､常に標準出力に出される｡無為設定は0｡各水準は次のように定義されている: 　　　　　　 Sets the debug level to level, an integer value indicating how much debugging information should be printed to stdout. Note that debug messages always go to stdout, independent of the value of configure -outfile. Default value is 0. Levels are defined as:

  0
    どの様な不具合情報も表示されない｡　　　 Do not display any debug information.

  1
    configure -match (使用者が指定した非合致)を使って指定したどの試験にも合致しないか､或は configure -skip (使用者が指定した飛越し)によって指定されたどれかの試験に合致したかの理由により試験が飛越されたか否かを考慮して情報を表示する｡又､試験ファイル内の刷新やバランスの不足の可能性についての警告を印刷する｡又､試験の名前のどれかの再使用に関する警告を印刷する｡　　　　　　　 Display information regarding whether a test is skipped because it does not match any of the tests that were specified using by configure -match (userSpecifiedNonMatch) or matches any of the tests specified by configure -skip (userSpecifiedSkip). Also print warnings about possible lack of cleanup or balance in test files. Also print warnings about any re-use of test names.

  2
    命令行処理機能による旗標配列､大域 env 配列､現在の名前空間に存在する全ての使用者定義変数をそれが使用されている様に表示する｡　　　　　 Display the flag array parsed by the command line processor, the contents of the global env array, and all user-defined variables that exist in the current namespace as they are used.

  3
    試験装備内の個々の手続函数が何をしているかに関する情報が表示される｡　　　　 Display information regarding what individual procs in the test harness are doing.

-verbose level
  出力の冗長性を､ body, pass, skip, start, error line の内の零或はそれ以上の要素のリストで level に設定する｡無為設定は {body error} である｡諸水準は次のように定義されている :　　　　　　 Sets the type of output verbosity desired to level, a list of zero or more of the elements body, pass, skip, start, error, line, msec and usec. Default value is “body error”. Levels are defined as:

  body (b)
    失敗した試験の本体を表示する　　　　　 Display the body of failed tests

  pass (p)
    試験が合格した時出力を印刷する　　　　　 Print output when a test passes

  skip (s)
    試験が省略された時出力を印刷する　　　　　 Print output when a test is skipped

  start (t)
    何時であれ試験が開始と出力を印刷する　　　　　 Print output whenever a test starts

  error (e)
    試験の返り値がその予想された返り値と合致しない時に､もしあるなら､不都合情報と不都合番号を印刷する｡　　　　　 Print errorInfo and errorCode, if they exist, when a test return code does not match its expected return code

  line (l)
    失敗した試験の源譜情報を印刷する　　　　 Print source file line information of failed tests

  msec (m)
    実行時間を千分の一秒単位で印刷する　　　　 Print each test's execution time in milliseconds

  usec (u)
    実行時間を百万分の一秒単位で印刷する　　　　　　 Print each test's execution time in microseconds

    注意すべきは､ msec と usec の冗漫さの狙いは表示用の計測結果の提供だけである｡出来栄え試験や規範的水準に考慮すべき再現性の問題には取組まない｡これらの冗漫さの使用は､time 命令による使用者の試験本体の包み込みを考慮している場合は､全体的な軌道性能の毀損を目指すことになる｡　　　　　 Note that the msec and usec verbosity levels are provided as indicative measures only. They do not tackle the problem of repeatibility which should be considered in performance tests or benchmarks. To use these verbosity levels to thoroughly track performance degradations, consider wrapping your test bodies with time commands.

    上に註記した一文字の短縮記号も認識されるので､ “configure -verbose pt” は “configure -verbose {pass start}” と同じである｡　　　　　　 The single letter abbreviations noted above are also recognized so that “configure -verbose pt” is the same as “configure -verbose {pass start}”.

-preservecore level
  核芯の保存水準を level に設定する｡この水準は核芯のファイルが如何に厳しく検査されるかを決定する｡無為設定は0｡諸水準は次のように定義されている:　　　　　 Sets the core preservation level to level. This level determines how stringent checks for core files are. Default value is 0. Levels are defined as:

  0
    検査なし — それぞれの試験命令の終わりに核芯のファイルの検査はしないが､全ての試験が評価された後､それを runAllTests 内で試験する｡　　　　　 No checking — do not check for core files at the end of each test command, but do check for them in runAllTests after all test files have been evaluated.

  1
    更に､それぞれの test 命令の終わりに核芯のファイルを検査する｡ 　　　　　 Also check for core files at the end of each test command.

  2
    上に述べた全ての機会に核芯のファイルを検査し､ configure -tmpdir 内で作成されたそれぞれの核芯のファイルの複写を保存する｡　　　　　　 Check for core files at all times described above, and save a copy of each core file produced in configure -tmpdir.

-limitconstraints boolean
  上の TESTS 内で記述した様に test が受取る拘束子の方法を設定する｡無為設定の値は偽値｡　　　　 Sets the mode by which test honors constraints as described in TESTS above. Default value is false.

-constraints list
  list 中の拘束子を全て真値に設定する｡又､上の TESTS 内で記述した様に configure -limitconstraints true と一緒にして別の拘束子の方法を制御するにも使う｡無為設定の値は空リスト｡　　　　　　 Sets all the constraints in list to true. Also used in combination with configure -limitconstraints true to control an alternative constraint mode as described in TESTS above. Default value is an empty list.

-tmpdir directory
  makeFile, makeDirectory, viewFile, removeFile, removeDirectory に使用される臨時ディレクトリーを無為設定ディレクトリーとして設定する､そこは､試験ファイルによって作成される臨時のファイルとディレクトリーが作成されるべき場所である｡無為設定の値はworkingDirectory ｡　　　　　　 Sets the temporary directory to be used by makeFile, makeDirectory, viewFile, removeFile, and removeDirectory as the default directory where temporary files and directories created by test files should be created. Default value is workingDirectory.

-testdir directory
  試験ファイルと子供のディレクトリーの為に runAllTests によって捜されるディレクトリーを設定する｡無為設定の値はworkingDirectory ｡　　　　　　 Sets the directory searched by runAllTests for test files and subdirectories. Default value is workingDirectory.

-file patternList
  どの試験ファイルが評価されるかを決定するために runAllTests によって使われる模様のリストを設定する｡無為設定の値は “*.test” ｡　　　　　 Sets the list of patterns used by runAllTests to determine what test files to evaluate. Default value is “*.test”.

-notfile patternList
  どの試験ファイルが飛越しされるかを決定するために runAllTests によって使われる模様のリストを設定する｡無為設定の値は “l.*.test” ､それでどのSCCS(版番号管理ファイルの一つ) 連結 ファイルも飛越される ｡　　　　　 Sets the list of patterns used by runAllTests to determine what test files to skip. Default value is “l.*.test”, so that any SCCS lock files are skipped.

-relateddir patternList
  どの子供のディレクトリーを all.tcl によって捜索するかを決定するために runAllTests によって使われる模様のリストを設定する｡無為設定の値は “*” ｡　　　　　 Sets the list of patterns used by runAllTests to determine what subdirectories to search for an all.tcl file. Default value is “*”.

-asidefromdir patternList
  どの子供のディレクトリーを all.tcl によって捜索する時に飛越すかを決定するために runAllTests によって使われる模様のリストを設定する｡無為設定の値は空リスト｡　　　　　 Sets the list of patterns used by runAllTests to determine what subdirectories to skip when searching for an all.tcl file. Default value is an empty list.

-match patternList
  試験を実行すべきか否かを決定するために test によって使われる模様のリストを設定する｡無為設定の値は “*” ｡　　　　　　 Set the list of patterns used by test to determine whether a test should be run. Default value is “*”.

-skip patternList
  試験を省略すべきか否かを決定するために test によって使われる模様のリストを設定する｡無為設定の値は空リスト｡　　　　　 Set the list of patterns used by test to determine whether a test should be skipped. Default value is an empty list.

-load script
  loadTestedCommands によって評価される記述譜を設定する｡無為設定の値は空の記述譜｡　　　　　 Sets a script to be evaluated by loadTestedCommands. Default value is an empty script.

-loadfile filename
  loadTestedCommands によって評価される記述譜をそこから読込むファイル名を設定する｡これは -load. の代わりである｡両方一緒には使用できない｡　　　　　　 Sets the filename from which to read a script to be evaluated by loadTestedCommands. This is an alternative to -load. They cannot be used together.

-outfile filename
  tcltest によって生成されたすべての出力が書き込まれるファイルを設定する｡ filename という名前のファイルは書込み用に開かれ､その結果の通信路は outputChannel の値として設定される｡　　　　　　 Sets the file to which all output produced by tcltest should be written. A file named filename will be opened for writing, and the resulting channel will be set as the value of outputChannel.

-errfile filename
  tcltest によって生成されたすべての不都合出力が書き込まれるファイルを設定する｡ filename という名前のファイルは書込み用に開かれ､その結果の通信路は errorChannel の値として設定される｡　　　　　　 Sets the file to which all error output produced by tcltest should be written. A file named filename will be opened for writing, and the resulting channel will be set as the value of errorChannel.

### CREATING TEST SUITES WITH TCLTEST

組試験の基本的要素は個別の test 命令である｡幾つかの例を始める｡　　　　　　 The fundamental element of a test suite is the individual test command. We begin with several examples.

1. 正常に帰る記述譜の試験｡　　　 Test of a script that returns normally.

       test example-1.0 {normal return} {
           format %s value
       } value

2. 文脈の立上げと刷新を要求する試験｡註意すべきは､波括弧の括りと段落揃えの書式によって､行の継続の必要性を回避している｡　　　　 Test of a script that requires context setup and cleanup. Note the bracing and indenting style that avoids any need for line continuation.

       test example-1.1 {test file existence} -setup {
           set file [makeFile {} test]
       } -body {
           file exists $file
       } -cleanup {
           removeFile test
       } -result 1

3. 不都合を掲げる記述譜の試験｡　　　　　 Test of a script that raises an error.

       test example-1.2 {error return} -body {
           error message
       } -returnCodes error -result message

4. 拘束子と共に試験する｡　　　　 Test with a constraint.

       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)

次に高い階層の編成では､幾つかの試験命令が一つの試験ファイルの中に互いに集められる｡試験ファイルは拡張子 “.test” を伴う名前を有すべきであり､理由は runAllTests により試験ファイルの発見の為に使われる無為設定の模様にそれが使用されるから｡使用者の企画のそれぞれの源譜命令ファイル毎に一つの試験ファイルを有することは良き常識である｡その試験ファイルと源譜命令ファイルを一緒に校正し､試験を命令の変更に同期させて維持することは良き習慣である｡　　　　　　 At the next higher layer of organization, several test commands are gathered together into a single test file. Test files should have names with the “.test” extension, because that is the default pattern used by runAllTests to find test files. It is a good rule of thumb to have one test file for each source code file of your project. It is good practice to edit the test file and the source code file together, keeping tests synchronized with code changes.

試験ファイルの殆どの命令は test 命令であろう｡test の条件付き評価よりも､試験を省略するために拘束子を使用されたい｡　　　　　　 Most of the code in the test file should be the test commands. Use constraints to skip tests, rather than conditional evaluation of test.

1. 監視する為に拘束子を使用した､条件下の試験の推奨できる体系の書き方:　　　　　 Recommended system for writing conditional tests, using constraints to guard:

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

2. 監視する為に if を使用した､条件下の試験の推奨できない体系の書き方:　　　　　 Discouraged system for writing conditional tests, using if to guard:

       if $myRequirement {
           test badConditionalTest {} {
               #body
           } result
       }

試験本体の要求する全ての文脈を確立し公開する為に -setup と -cleanup 指示項目を使用されたい｡ファイル中の先行する試験に依存する試験を作成してはならない｡この様な先行する試験は飛越されるかもしれない｡もし､幾つかの連続した試験が同じ文脈を要求する場合は､適切な立上げと刷新の記述譜は､それぞれの試験の -setup と -cleanup 指示項目に渡す為の変数を保存できるかもしれない｡これは試験命令の外で立上げを遂行するよりもより良い方法であろう､理由はもしその立ち上げが必要なら､それだけが実行され､立上げ中のどの不都合も報告され､試験ファイルの中断を引起さないので｡　　　　　　 Use the -setup and -cleanup options to establish and release all context requirements of the test body. Do not make tests depend on prior tests in the file. Those prior tests might be skipped. If several consecutive tests require the same context, the appropriate setup and cleanup scripts may be stored in variable for passing to each tests -setup and -cleanup options. This is a better solution than performing setup outside of test commands, because the setup will only be done if necessary, and any errors during setup will be reported, and not cause the test file to abort.

縦えconfigure -singleproc 1 が全てのファイルを同じ解釈実行機能中で評価する時でも､試験ファイルは他の試験ファイルと結合できるべきで､それと干渉してはならない｡これを達成する簡単な方法は､試験ファイルが完了した時に削除する名前空間内で､その試験が全ての命令と変数を定義することである｡使用するべき良き名前空間は試験している機能部品の名前空間の子供の名前空間test である｡　　　　　　 A test file should be able to be combined with other test files and not interfere with them, even when configure -singleproc 1 causes all files to be evaluated in a common interpreter. A simple way to achieve this is to have your tests define all their commands and variables in a namespace that is deleted when the test file evaluation is complete. A good namespace to use is a child namespace test of the namespace of the module you are testing.

試験ファイルは記述譜として直接に評価されることができるべきであり､親の runAllTests による呼出しに依存すべきではない｡こらは tcltest が供給する全ての構成設定制御を試験者に与える為にそれぞれの試験ファイルが命令行引数を処理すべきであることを意味する｡　　　　 A test file should also be able to be evaluated directly as a script, not depending on being called by a main runAllTests. This means that each test file should process command line arguments to give the tester all the configuration control that tcltest provides.

試験ファイルの中の全ての tests の後に､命令 cleanupTests が呼出されるべきである｡　　　　　　 After all tests in a test file, the command cleanupTests should be called.

1. これはこれらの点を図示する試験ファイルの見本の骨組みである: 　　　　　　 Here is a sketch of a sample test file illustrating those points:

       package require tcltest 2.5
       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 -body {
               # 第１の試験
               # First test
           } -cleanup $CLEANUP -result {...}
           test example-2 {} -constraints X -setup $SETUP -body {
               # 第２の試験; 拘束されている
               # Second test; constrained
           } -cleanup $CLEANUP -result {...}
           test example-3 {} {
               # 第３の試験; 文脈の要求なし
               # Third test; no context required
           } {...}
           cleanupTests
       }
       namespace delete ::example::test

次の水準の編成は幾つかの試験ファイルで作り上げた完全な組試験である｡一つの記述譜が全体の組の制御に使われている｡この記述譜の基本的機能は何かの必要な準備の後 runAllTests を呼出すことである｡この記述譜は通常､ all.tcl と名付けられる､理由は､複数の組試験を一つの実行試験に組合せる時に runAllTests に使われる無為設定の名前であるから｡　　　　　 The next level of organization is a full test suite, made up of several test files. One script is used to control the entire suite. The basic function of this script is to call runAllTests after doing any necessary setup. This script is usually named all.tcl because that is the default name used by runAllTests when combining multiple test suites into one testing run.

1. これは見本となる組試験の祖先の記述譜の骨組みである:　　　　　 Here is a sketch of a sample test suite main script:

       package require Tcl 8.6
       package require tcltest 2.5
       package require example
       ::tcltest::configure -testdir \
               [file dirname [file normalize [info script]]]
       eval ::tcltest::configure $argv
       ::tcltest::runAllTests

### 互換性　　COMPATIBILITY

以前の版の tcltest によって提供された ::tcltest 名前空間中の多くの命令と変数がここでは説明されていない｡それらはもはや tcltest に運用されている公的対話機能ではなく､新しい組試験に使うべきでもない｡然しながら､古い相互作用機能規格向けに書かれた既存の組試験の運用を続ける為に､多くのこれらの批判のある命令と変数は猶も以前と同じように動く｡譬えば､多くの環境で､変数 ::argv からの引数を伴った package require tcltest 2.1 の少し後に configure が自動的に呼ばれる｡これは tcltest が自動的に命令行から構成設定される古い振舞いに依存した組試験を運用する為である｡新しい試験ファイルはこれには依存しないで､明示的に次を含むべきである｡　　　　　　 A number of commands and variables in the ::tcltest namespace provided by earlier releases of tcltest have not been documented here. They are no longer part of the supported public interface of tcltest and should not be used in new test suites. However, to continue to support existing test suites written to the older interface specifications, many of those deprecated commands and variables still work as before. For example, in many circumstances, configure will be automatically called shortly after package require tcltest 2.1 succeeds with arguments from the variable ::argv. This is to support test suites that depend on the old behavior that tcltest was automatically configured from command line arguments. New test files should not depend on this, but should explicitly include

    eval ::tcltest::configure $::argv

or

    ::tcltest::configure {*}$::argv

命令行からの構成設定を確立するために｡　　　　　　 to establish a configuration from command line arguments.

### 未解決の問題点　　KNOWN ISSUES

test の入れ子になった評価に関わる二つの未解決の問題点がある｡第１の問題点は試験記述譜が実行される棚の水準に関する｡他の試験の内部に入れ子になった試験が最も外側の試験と同じ棚の水準で実行される事があり得る｡譬えば､次の命令文の中で: 　　　　　 There are two known issues related to nested evaluations of test. The first issue relates to the stack level in which test scripts are executed. Tests nested within other tests may be executed at the same stack level as the outermost test. For example, in the following code:

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

何であれ level-2.1 の中で実行された記述譜は､ level-1.1 の為に定義した記述譜のためのと同じ棚の水準で実行されることがある｡　　　　　　 any script executed in level-2.1 may be executed at the same stack level as the script defined for level-1.1.

更に､２つの tests が実行された間に､cleanupTests によってlevel-1.1の試験と同じ水準の試験についての結果のみ報告されるであろう｡しかし､level-1.1 に先立ち実行された全ての試験についての試験結果は level-2.1 が実行される時に利用できる｡これが意味することは､level-2.1 の試験の試験結果を利用しようと試みると､こうなるかもしれない､ “m” 試験は実行され､ “n” 試験は省略され､ “o” 試験は合格し､ “p” 試験は失敗した､ここで “m”, “n”, “o”, and “p” が参照している試験は試験 level-1.1 と同じ水準で実行された試験である｡　　　　　　　 In addition, while two tests have been run, results will only be reported by cleanupTests for tests at the same level as test level-1.1. However, test results for all tests run prior to level-1.1 will be available when test level-2.1 runs. What this means is that if you try to access the test results for test level-2.1, it will may say that “m” tests have run, “n” tests have been skipped, “o” tests have passed and “p” tests have failed, where “m”, “n”, “o”, and “p” refer to tests that were run at the same test level as test level-1.1.

試験命令中の出力と不都合の比較の実現は使用者の応用譜の命令中の puts の使用に依存する｡出力は定義された記述譜が実行されている間の puts 命令の再定義によって遮断される｡ C 手続函数から発信された又は､ C 応用譜から直接に印刷された不都合は試験命令によって捕捉されない｡従って､ test に対する -output の利用と､ -errorOutput 指示項目は出力手続函数に puts を使う純粋 Tcl 応用譜についてのみ便利である｡　　　　 Implementation of output and error comparison in the test command depends on usage of puts in your application code. Output is intercepted by redefining the global puts command while the defined test script is being run. Errors thrown by C procedures or printed directly from C applications will not be caught by the test command. Therefore, usage of the -output and -errorOutput options to test is useful only for pure Tcl applications that use puts to produce output.

### KEYWORDS

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