tcltest

package require tcltest ?2.3?

tcltest::test описание имени ?значение параметра...?
tcltest::test описание имени ?ограничения? тело результат

tcltest::loadTestedCommands
tcltest::makeDirectory имя ?директория?
tcltest::removeDirectory имя ?директория?
tcltest::makeFile содержимое имя ?директория?
tcltest::removeFile имя ?директория?
tcltest::viewFile имя ?директория?
tcltest::cleanupTests ?запускНесколькихТестов?
tcltest::runAllTests

tcltest::configure
tcltest::configure -параметр
tcltest::configure -параметр значение ?-параметр значение ...?
tcltest::customMatch режим команда
tcltest::testConstraint ограничение ?значение?
tcltest::outputChannel ?идентификаторКанала?
tcltest::errorChannel ?идентификаторКанала?
tcltest::interpreter ?интерпретатор?

tcltest::debug ?уровень?
tcltest::errorFile ?имяФайла?
tcltest::limitConstraints ?логическоеЗначение?
tcltest::loadFile ?имяФайла?
tcltest::loadScript ?скрипт?
tcltest::match ?списокШаблонов?
tcltest::matchDirectories ?списокШаблонов?
tcltest::matchFiles ?списокШаблонов?
tcltest::outputFile ?имяФайла?
tcltest::preserveCore ?уровень?
tcltest::singleProcess ?логическоеЗначение?
tcltest::skip ?списокШаблонов?
tcltest::skipDirectories ?списокШаблонов?
tcltest::skipFiles ?списокШаблонов?
tcltest::temporaryDirectory ?директория?
tcltest::testsDirectory ?директория?
tcltest::verbose ?уровень?

tcltest::test имя описание списокПараметров
tcltest::bytestring строка
tcltest::normalizeMsg сообщение
tcltest::normalizePath переменнаяПути
tcltest::workingDirectory ?директория?

Описание

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.

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.

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.

See СОЗДАНИЕ НАБОРОВ ТЕСТОВ С TCLTEST below for an extended example of how to use the commands of tcltest to produce test suites for your Tcl-enabled code.

Команды

test имя описание ?-параметр значение ...?: Определяет и, возможно, выполняет тест с именем имя и описанием описание. Имя и описание теста используются в сообщениях, сообщаемых test во время тестирования, как настроено параметрами tcltest. Остальные аргументы значение параметра определяют тест, включая скрипты для выполнения, условия для их выполнения, ожидаемый результат и способы сравнения ожидаемого и фактического результатов. См. ТЕСТЫ ниже для полного описания допустимых параметров и того, как они определяют тест. Команда test возвращает пустую строку.
test имя описание ?ограничения? тело результат: Эта форма test предоставлена для поддержки наборов тестов, написанных для версии 1 пакета tcltest, а также для более простого интерфейса для распространённого использования. Она эквивалентна “test имя описание -ограничения ограничения -тело тело -результат результат”. Все остальные параметры test принимают свои значения по умолчанию. Когда ограничения опущены, эту форму test можно отличить от первой, потому что все параметры начинаются с “-”.
loadTestedCommands: Выполняет в контексте вызывающего скрипт, указанный параметром configure -load или configure -loadfile. Возвращает результат выполнения этого скрипта, включая любые ошибки, поднятые скриптом. Используйте эту команду и связанные с ней параметры конфигурации для предоставления команд, которые нужно протестировать, интерпретатору, выполняющему набор тестов.
makeFile содержимое имя ?директория?: Создает файл с именем имя относительно директории директория и записывает содержимое в этот файл с использованием системы кодирования кодировки. Если содержимое не заканчивается символом новой строки, символ новой строки будет добавлен в конец файла с именем имя. Так как используется системная кодировка, эта команда подходит только для создания текстовых файлов. Файл будет удален при следующем вызове cleanupTests, если его не удалит команда removeFile. Значение по умолчанию для директории — это директория configure -tmpdir. Возвращает полный путь созданного файла. Используйте эту команду для создания любых текстовых файлов, необходимых тесту, с нужным содержимым.
removeFile имя ?директория?: Принудительно удаляет файл, на который ссылается имя. Это имя файла должно быть относительно директории. Значение по умолчанию для директории — это директория configure -tmpdir. Возвращает пустую строку. Используйте эту команду для удаления файлов, созданных командой makeFile.
makeDirectory имя ?директория?: Создаёт директорию с именем имя относительно директории директория. Директория будет удалена при следующем вызове cleanupTests, если её не удалит команда removeDirectory. Значение по умолчанию для директории — это директория configure -tmpdir. Возвращает полный путь созданной директории. Используйте эту команду для создания любых директорий, необходимых для существования теста.
removeDirectory имя ?директория?: Принудительно удаляет директорию, на которую ссылается имя. Эта директория должна быть относительно директории. Значение по умолчанию для директории — это директория configure -tmpdir. Возвращает пустую строку. Используйте эту команду для удаления директорий, созданных командой makeDirectory.
viewFile файл ?директория?: Возвращает содержимое файла, за исключением последней новой строки, так же, как возвращала бы команда read -nonewline. Это имя файла должно быть относительно директории. Значение по умолчанию для директории — это директория configure -tmpdir. Используйте эту команду как удобный способ превратить содержимое файла, сгенерированного тестом, в результат этого теста для сравнения с ожидаемым результатом. Содержимое файла читается с использованием системной кодировки, поэтому его полезность ограничена текстовыми файлами.
cleanupTests: Предназначена для очистки и суммирования после выполнения нескольких тестов. Обычно вызывается один раз на файл теста в конце файла после завершения всех тестов. Для наилучшей эффективности убедитесь, что cleanupTests вызывается даже если ранее в файле теста произошла ошибка.
Выводит статистику о проведённых тестах и удаляет файлы и директории, созданные командами makeDirectory и makeFile после последнего вызова cleanupTests. Имена файлов и директорий в директории configure -tmpdir, созданные после последнего вызова cleanupTests, но не созданные командами makeFile или makeDirectory, выводятся в 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 не обрабатываются.
Если переменная среды ::env(TCLTEST_OPTIONS) существует при загрузке пакета tcltest (с помощью package require tcltest), её значение используется как список аргументов для передачи в configure. Это позволяет установить значения по умолчанию для конфигурационных опций через среду.
customMatch mode script: Регистрирует mode как новое допустимое значение опции -match для команды test. При передаче опции -match mode команде test, скрипт script будет оценён для сравнения фактического результата выполнения тела теста с ожидаемым результатом. Для выполнения сопоставления скрипт script дополняется двумя дополнительными словами: ожидаемый результат и фактический результат. Завершенный скрипт оценивается в глобальном пространстве имён. От завершенного скрипта ожидается возврат булевого значения, указывающего на соответствие результатов. Встроенными режимами сопоставления в команде test являются exact, glob и regexp.
testConstraint constraint ?boolean?: Устанавливает или возвращает булево значение, связанное с указанным constraint. Дополнительную информацию см. в разделе ОГРАНИЧЕНИЯ ТЕСТОВ ниже.
interpreter ?executableName?: Устанавливает или возвращает имя исполняемого файла, который будет запущен командой exec командой runAllTests для выполнения каждого файла теста, когда configure -singleproc имеет значение false. Значение по умолчанию для interpreter – имя текущей программы, возвращаемое командой info nameofexecutable.
outputChannel ?channelID?: Устанавливает или возвращает идентификатор канала вывода. По умолчанию используется stdout. Любой тест, который выводит информацию о тесте, должен отправлять её в outputChannel, а не по умолчанию в stdout.
errorChannel ?channelID?: Устанавливает или возвращает идентификатор канала ошибок. По умолчанию используется stderr. Любой тест, который выводит сообщения об ошибках, должен отправлять этот вывод в errorChannel, а не напрямую в stderr.

Команды конфигурации со сокращениями

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 как один аргумент, заключенный в фигурные скобки, вместо необходимости экранирования новых строк между аргументами команды test. Аргумент optionList ожидается как список с чётным числом элементов, представляющих аргументы option и value для передачи в test. Однако эти значения не передаются непосредственно, как в альтернативных формах команды switch. Вместо этого эта форма делает неудачную попытку переопределить правила подстановки Tcl, выполняя подстановки некоторых элементов списка в попытке реализовать интерпретацию «сделай как я хочу» для заключённого в фигурные скобки «блока». Результат почти невозможно четко документировать, и поэтому этот вариант не рекомендуется. Обратитесь к примерам в разделе СОЗДАНИЕ НАБОРОВ ТЕСТОВ С TCLTEST ниже, чтобы увидеть, что эта форма на самом деле не необходима для избежания экранированных новых строк. Если вы настаиваете на использовании этой формы, изучите исходный код tcltest, если хотите узнать подробности о подстановках, или просто заключите третий и последующие аргументы для test в фигурные скобки и надейтесь на лучшее.
workingDirectory ?directoryName?: Устанавливает или возвращает текущую рабочую директорию во время выполнения набора тестов. Значение по умолчанию для workingDirectory – директория, в которой был запущен набор тестов. Команды Tcl cd и pwd являются достаточными заменителями.
normalizeMsg msg: Возвращает результат удаления «лишних» новых строк из msg, где «лишние» являются довольно неточным определением. Tcl предлагает множество команд для обработки строк, чтобы модифицировать их по своему желанию, а customMatch позволяет гибко сопоставлять фактические и ожидаемые результаты.
normalizePath pathVar: Разрешает символьные ссылки в пути, создавая путь без внутренних перенаправлений. Предполагается, что pathVar является абсолютным. pathVar изменяется на месте. Команда Tcl file normalize является достаточным заменителем.
bytestring string: Создаёт строку, состоящую из запрошенной последовательности байтов, в отличие от строки с правильно сформированными UTF-8 символами, используя значение, предоставленное в string. Это позволяет тестировщику создавать ненормализованные или неправильно сформированные строки для передачи в C-процедуры, которые должны принимать строки с вложенными нулевыми типами и подтверждать, что строка результата имеет определённый шаблон байтов. Это точно эквивалентно команде Tcl encoding convertfrom identity.

Тесты

Команда test является сердцем пакета tcltest. Её основная функция – оценить скрипт Tcl и сравнить результат с ожидаемым результатом. Опции команды test определяют скрипт теста, среду, в которой его нужно оценить, ожидаемый результат и способ сравнения фактического результата с ожидаемым. Некоторые конфигурационные опции tcltest также влияют на работу команды test.

Сводка допустимых опций для 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-функции должно быть включено в описание для тестов регрессии. Если тест предназначен для воспроизведения ошибки, укажите идентификатор ошибки в описании.

Допустимые атрибуты и их значения:

-constraints keywordList|expression: Необязательный атрибут -constraints может содержать список одного или нескольких ключевых слов или выражение. Если значение -constraints представляет собой список ключевых слов, каждое из этих ключевых слов должно быть именем ограничения, определённого вызовом testConstraint. Если какое-либо из перечисленных ограничений ложно или не существует, тест пропускается. Если значение -constraints представляет собой выражение, это выражение вычисляется. Если выражение вычисляется как истинное, то тест выполняется. Обратите внимание, что форма выражения для -constraints может повлиять на работу configure -constraints и configure -limitconstraints, и не рекомендуется. Соответствующие ограничения должны быть добавлены к любым тестам, которые не должны всегда выполняться. То есть, условное выполнение теста должно выполняться с помощью параметра -constraints, а не с помощью условного выполнения test. Таким образом, тест-суитой всегда сообщается то же количество тестов, хотя количество пропущенных может меняться в зависимости от среды тестирования. Значение по умолчанию — пустой список. См. ТЕСТОВЫЕ ОГРАНИЧЕНИЯ ниже для списка встроенных ограничений и информации о том, как добавить свои собственные ограничения.
-setup script: Необязательный атрибут -setup указывает скрипт, который будет выполнен перед скриптом, указанным атрибутом -body. Если вычисление script вызывает ошибку, тест завершится неудачей. Значение по умолчанию — пустой скрипт.
-body script: Атрибут -body указывает скрипт, который необходимо запустить для выполнения теста, который должен возвращать результат, который можно проверить на правильность. Если вычисление script вызывает ошибку, тест завершится неудачей (если не используется параметр -returnCodes, чтобы указать, что ошибка ожидается). Значение по умолчанию — пустой скрипт.
-cleanup script: Необязательный атрибут -cleanup указывает скрипт, который будет выполнен после скрипта, указанного атрибутом -body. Если вычисление script вызывает ошибку, тест завершится неудачей. Значение по умолчанию — пустой скрипт.
-match mode: Атрибут -match определяет, как сравниваются ожидаемые ответы, предоставленные параметрами -result, -output и -errorOutput. Допустимые значения для mode — regexp, glob, exact и любое значение, зарегистрированное предыдущим вызовом customMatch. Значение по умолчанию — exact.
-result expectedValue: Атрибут -result предоставляет expectedValue, с которым будет сравниваться возвращаемое значение скрипта. Значение по умолчанию — пустая строка.
-output expectedValue: Атрибут -output предоставляет expectedValue, с которым будет сравниваться любой вывод, отправленный в stdout или outputChannel во время выполнения скрипта(ов). Обратите внимание, что для сравнения используется только вывод, напечатанный с помощью глобальной команды puts. Если -output не указан, вывод, отправленный в stdout и outputChannel, не обрабатывается для сравнения.
-errorOutput expectedValue: Атрибут -errorOutput предоставляет expectedValue, с которым будет сравниваться любой вывод, отправленный в stderr или errorChannel во время выполнения скрипта(ов). Обратите внимание, что для сравнения используется только вывод, напечатанный с помощью глобальной команды 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, которое является списком имён ограничений. Существует два режима управления ограничениями. Чаще всего используется режим по умолчанию, указанный установкой configure -limitconstraints в значение false. Тест будет выполняться только в том случае, если все ограничения в списке имеют истинное значение. Таким образом, опция -constraints команды test — удобный, символический способ определения любых условий, необходимых для того, чтобы тест был возможным или осмысленным. Например, test с -constraints unix будет выполняться только в том случае, если ограничение unix истинно, что указывает, что тестовый набор выполняется на платформе Unix.

Каждый test должен включать любые -constraints, необходимые для его выполнения только там, где это уместно. В пакете tcltest предварительно определено несколько ограничений, перечисленных ниже. Регистрация пользовательских ограничений выполняется командой testConstraint. Пользовательские ограничения могут появляться в файле теста или в скрипте, указанном параметрами configure -load или configure -loadfile.

Ниже приведён список ограничений, предварительно определённых самим пакетом tcltest:

singleTestInterp: Этот тест может выполняться только в том случае, если все файлы тестов загружаются в один интерпретатор.
unix: Этот тест может выполняться только на любой платформе Unix.
win: Этот тест может выполняться только на любой платформе Windows.
nt: Этот тест может выполняться только на любой платформе Windows NT.
mac: Этот тест может выполняться только на любой платформе Mac.
unixOrWin: Этот тест может выполняться только на платформе Unix или Windows.
macOrWin: Этот тест может выполняться только на платформе Mac или Windows.
macOrUnix: Этот тест может выполняться только на платформе Mac или Unix.
tempNotWin: Этот тест не может выполняться на Windows. Этот флаг используется для временного отключения теста.
tempNotMac: Этот тест не может выполняться на Mac. Этот флаг используется для временного отключения теста.
unixCrash: Этот тест завершается ошибкой, если он выполняется на Unix. Этот флаг используется для временного отключения теста.
winCrash: Этот тест завершается ошибкой, если он выполняется на Windows. Этот флаг используется для временного отключения теста.
macCrash: Этот тест завершается ошибкой, если он выполняется на Mac. Этот флаг используется для временного отключения теста.
emptyTest: Этот тест пустой, поэтому не стоит его запускать, но он остаётся заглушкой для теста, который необходимо написать в будущем. Это ограничение имеет значение false, чтобы заставить тесты пропускаться, если пользователь не укажет иное.
knownBug: Этот тест известен тем, что не проходит, и ошибка ещё не исправлена. Это ограничение имеет значение false, чтобы заставить тесты пропускаться, если пользователь не укажет иное.
nonPortable: Этот тест можно выполнять только в определённых известных средах разработки. Некоторые тесты по своей природе непереносимы, потому что зависят от таких вещей, как длина слова, конфигурация файловой системы, менеджер окон и т. д. Это ограничение имеет значение false, чтобы заставить тесты пропускаться, если пользователь не укажет иное.
userInteraction: Для этого теста требуется взаимодействие пользователя. Это ограничение имеет значение false, чтобы заставить тесты пропускаться, если пользователь не укажет иное.
interactive: Этот тест может выполняться только в том случае, если интерпретатор находится в интерактивном режиме (когда глобальная переменная tcl_interactive установлена в 1).
nonBlockFiles: Этот тест можно выполнять только в том случае, если платформа поддерживает установку файлов в режим без блокировки.
asyncPipeClose: Этот тест можно выполнять только в том случае, если платформа поддерживает асинхронное сброс и асинхронное закрытие на трубе.
unixExecs: Этот тест можно выполнять только в том случае, если на этой машине доступны команды Unix-типа cat, echo, sh, wc, rm, sleep, fgrep, ps, chmod и mkdir.
hasIsoLocale: Этот тест может выполняться только в том случае, если можно переключиться на локаль ISO.
root: Этот тест может выполняться только в том случае, если пользователь Unix является root.
notRoot: Этот тест может выполняться только в том случае, если пользователь Unix не является root.
eformat: Этот тест может выполняться только в том случае, если приложение имеет рабочую версию sprintf по отношению к формату «e» для чисел с плавающей точкой.
stdio: Этот тест может выполняться только в том случае, если интерпретатор можно открыть как трубу.

Альтернативный режим управления ограничениями активируется установкой configure -limitconstraints в значение true. При этой настройке все существующие ограничения, кроме тех, которые находятся в списке ограничений, возвращаемом configure -constraints, устанавливаются в значение false. Когда устанавливается значение configure -constraints, все эти ограничения устанавливаются в значение true. Влияние состоит в том, что при использовании обоих параметров configure -constraints и configure -limitconstraints выполняются только те тесты, которые включают только ограничения из списка configure -constraints; все остальные пропускаются. Например, можно настроить конфигурацию с

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

для запуска ровно тех тестов, которые проверяют известные ошибки, и для выяснения, проходят ли какие-либо из них, что указывает на то, что ошибка была исправлена.

Запуск всех тестов

Единственная команда runAllTests оценивается для запуска всего набора тестов, охватывающего множество файлов и каталогов. Параметры конфигурации tcltest управляют точными операциями. Команда runAllTests начинает с вывода сводки своей конфигурации в outputChannel.

Файлы тестов, которые будут оцениваться, ищутся в каталоге configure -testdir. Список файлов в этом каталоге, которые соответствуют любому из шаблонов в configure -file и не соответствуют ни одному из шаблонов в configure -notfile, генерируется и сортируется. Затем каждый файл оценивается по очереди. Если configure -singleproc имеет значение true, то каждый файл будет подключен в контексте вызывающего элемента. Если это false, то копия interpreter будет выполнен для оценки каждого файла. Многопроцессорная работа полезна, когда тестирование может привести к ошибкам настолько серьезным, что процесс завершается. Хотя такая ошибка может завершить дочерний процесс, оценивающий один файл, главный процесс может продолжить остальную часть набора тестов. При многопроцессорной работе конфигурация tcltest в главном процессе передается дочерним процессам в качестве аргументов командной строки, за исключением configure -outfile. Команда runAllTests в главном процессе собирает весь вывод из дочерних процессов и объединяет их результаты в один главный отчет. Любые сообщения об отдельных сбоях тестов или сообщения, запрошенные настройкой configure -verbose, передаются непосредственно в outputChannel главным процессом.

После оценки всех выбранных файлов тестов сводка результатов выводится в outputChannel. Сводка включает общее количество тестов, оцененных, разделенных на пропущенные, пройденные и не пройденные. Сводка также отмечает количество оцененных файлов и имена любых файлов с не пройденными тестами или ошибками. Также выводится список ограничений, которые привели к пропуску тестов, и количество пропущенных тестов для каждого. Кроме того, выводятся сообщения, если кажется, что оценка файла теста привела к оставлению временных файлов в configure -tmpdir.

После завершения и обобщения всех выбранных файлов тестов, runAllTests затем рекурсивно воздействует на подкаталоги configure -testdir. Все подкаталоги, которые соответствуют любому из шаблонов в configure -relateddir и не соответствуют ни одному из шаблонов в configure -asidefromdir, проверяются. Если в таком каталоге найден файл с именем all.tcl, он будет подключен в контексте вызывающего элемента. Независимо от того, содержит ли проверенный каталог файл all.tcl, его подкаталоги также сканируются по шаблонам configure -relateddir и configure -asidefromdir. Таким образом, многие каталоги в древовидной структуре каталогов могут иметь все свои файлы тестов, оцененные с помощью одной команды runAllTests.

Настраиваемые параметры

Команда configure используется для установки и запроса настраиваемых параметров tcltest. Допустимые параметры:

-singleproc boolean

Управляет тем, запускает ли runAllTests дочерний процесс для каждого тестового файла. Запуска не происходит, когда boolean имеет значение true. Значение по умолчанию — false.

-debug level

Устанавливает уровень отладки на level, целое числовое значение, указывающее, сколько информации об отладке должно быть выведено в stdout. Обратите внимание, что сообщения об отладке всегда выводятся в stdout, независимо от значения параметра configure -outfile. Значение по умолчанию — 0. Уровни определены следующим образом:

0: Не отображать никакой информации об отладке.
1: Отображать информацию о том, пропущен ли тест, потому что он не соответствует ни одному из тестов, указанных с помощью configure -match (userSpecifiedNonMatch), или соответствует любому из тестов, указанных с помощью configure -skip (userSpecifiedSkip). Также выводить предупреждения о возможной нехватке очистки или баланса в тестовых файлах. Также выводить предупреждения о повторном использовании имен тестов.
2: Отображать массив флагов, разобранный обработчиком командной строки, содержимое глобального массива env и все пользовательские переменные, которые существуют в текущем пространстве имен, так как они используются.
3: Отображать информацию о том, что делают отдельные процедуры в тестовом наборе.

-verbose level

Устанавливает желаемый уровень подробности вывода на level, список из нуля или более элементов body, pass, skip, start, error, line, msec и usec. Значение по умолчанию — “body error”. Уровни определены следующим образом:

body (b): Отображать тело не пройденных тестов
pass (p): Выводить вывод, когда тест пройден
skip (s): Выводить вывод, когда тест пропущен
start (t): Выводить вывод всякий раз, когда начинается тест
error (e): Выводить errorInfo и errorCode, если они существуют, когда код возврата теста не соответствует ожидаемому коду возврата
line (l): Выводить информацию о строке исходного файла не пройденных тестов
msec (m): Выводить время выполнения каждого теста в миллисекундах
usec (u): Выводить время выполнения каждого теста в микросекундах

Обратите внимание, что уровни подробности msec и usec предоставляются только как показательные меры. Они не решают проблему воспроизводимости, которую следует учитывать при проведении тестовых или контрольных измерений производительности. Чтобы использовать эти уровни подробности для тщательного отслеживания ухудшения производительности, рассмотрите возможность обертывания ваших тестовых блоков командами time.

Однобуквенные сокращения, указанные выше, также распознаются, так что «configure -verbose pt» эквивалентно «configure -verbose {pass start}».

-preservecore level

Устанавливает уровень сохранения ядра на level. Этот уровень определяет, насколько строгими будут проверки на наличие файлов ядра. Значение по умолчанию — 0. Уровни определены следующим образом:

0: Без проверки — не проверять наличие файлов ядра в конце каждой команды теста, но проверять их в runAllTests после оценки всех тестовых файлов.
1: Также проверять наличие файлов ядра в конце каждой команды test.
2: Проверять наличие файлов ядра во всех описанных выше случаях и сохранять копию каждого созданного файла ядра в configure -tmpdir.

Создание наборов тестов с помощью tcltest

Основным элементом набора тестов является отдельная команда test. Начнем с нескольких примеров.

Тест скрипта, который возвращается нормально.
```
test example-1.0 {normal return} {
    format %s value
} value
```
Тест скрипта, для которого требуется настройка и очистка контекста. Обратите внимание на стиль фигурных скобок и отступов, который избегает необходимости использования продолжения строк.
```
test example-1.1 {test file existence} -setup {
    set file [makeFile {} test]
} -body {
    file exists $file
} -cleanup {
    removeFile test
} -result 1
```

Тест скрипта, который вызывает ошибку.

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

Тест с ограничением.

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 собираются вместе в один тестовый файл. Тестовые файлы должны иметь имена с расширением «.test», потому что это стандартный шаблон, используемый runAllTests для поиска тестовых файлов. Хорошим правилом является наличие одного тестового файла для каждого файла исходного кода вашего проекта. Рекомендуется редактировать тестовый файл и файл исходного кода вместе, сохраняя тесты синхронизированными с изменениями кода.

Большая часть кода в тестовом файле должна содержать команды test. Используйте ограничения для пропуска тестов, а не условную оценку команд test.

Рекомендуемая система для написания условных тестов, используя ограничения для защиты:
```
testConstraint X [expr $myRequirement]
test goodConditionalTest {} X {
    # body
} result
```
Не рекомендуется использовать систему для написания условных тестов, используя команду if для защиты:
```
if $myRequirement {
    test badConditionalTest {} {
        #body
    } result
}
```

Используйте опции -setup и -cleanup для создания и освобождения всех контекстных требований к телу теста. Не делайте тесты зависимыми от предыдущих тестов в файле. Эти предыдущие тесты могут быть пропущены. Если несколько последовательных тестов требуют одного и того же контекста, соответствующие скрипты настройки и очистки могут быть сохранены в переменной для передачи каждому тесту опций -setup и -cleanup. Это лучшее решение, чем выполнение настройки вне команд test, поскольку настройка будет выполняться только при необходимости, и любые ошибки во время настройки будут сообщены, а не приведут к прерыванию выполнения тестового файла.

Файл с тестами должен быть совместим с другими тестовыми файлами и не должен их конфликтовать, даже когда configure -singleproc 1 приводит к оценке всех файлов в общем интерпретаторе. Простым способом достижения этого является определение всеми вашими тестами всех команд и переменных в пространстве имен, которое удаляется при завершении оценки тестового файла. Хорошим пространством имен является подпространство test пространства имен модуля, который вы тестируете.

Файл с тестами также должен быть способен к непосредственной оценке как скрипт, не завися от вызова master runAllTests. Это означает, что каждый тестовый файл должен обрабатывать аргументы командной строки, чтобы предоставить тестеру полный контроль над конфигурацией, который предоставляет tcltest.

После всех команд test в тестовом файле должна вызываться команда cleanupTests.

Вот набросок образцового тестового файла, иллюстрирующего эти моменты:

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 -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 при объединении нескольких наборов тестов в одну тестовую сессию.

Вот набросок образцового скрипта управления набором тестов:

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

Совместимость

Ряд команд и переменных в пространстве имен ::tcltest, предоставляемых более ранними выпусками tcltest, не документированы здесь. Они больше не являются частью поддерживаемого публичного интерфейса tcltest и не должны использоваться в новых наборах тестов. Однако для продолжения поддержки существующих наборов тестов, написанных по спецификациям старого интерфейса, многие из этих устаревших команд и переменных по-прежнему работают так же, как и раньше. Например, во многих случаях configure будет автоматически вызываться вскоре после успешного выполнения package requiretcltest 2.1 с аргументами из переменной ::argv. Это для поддержки наборов тестов, которые зависят от старого поведения, когда tcltest автоматически настраивался из аргументов командной строки. Новые тестовые файлы не должны зависеть от этого, а должны явно включать

eval ::tcltest::configure $::argv

или

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

для создания конфигурации из аргументов командной строки.

Известные проблемы

Есть две известные проблемы, связанные с вложенными вычислениями команды test. Первая проблема связана с уровнем стека, на котором выполняются тестовые скрипты. Тесты, вложенные внутри других тестов, могут выполняться на том же уровне стека, что и самый внешний тест. Например, в следующем коде:

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

любой скрипт, выполняемый на уровне 2.1, может выполняться на том же уровне стека, что и скрипт, определенный для уровня 1.1.

Кроме того, хотя два теста test были выполнены, результаты будут сообщены только командой cleanupTests для тестов на том же уровне, что и уровень теста 1.1. Однако результаты тестов для всех тестов, выполненных до уровня 1.1, будут доступны при выполнении теста уровня 2.1. Это означает, что если вы попытаетесь получить доступ к результатам теста уровня 2.1, он может сказать, что выполнено «m» тестов, пропущено «n» тестов, пройдено «o» тестов и «p» тестов не пройдено, где «m», «n», «o» и «p» относятся к тестам, выполненным на том же уровне теста, что и тест уровня 1.1.

Реализация сравнения вывода и ошибок в команде test зависит от использования команды puts в вашем коде приложения. Вывод перехватывается путем переопределения глобальной команды puts во время выполнения определенного тестового скрипта. Ошибки, сгенерированные процедурами C или напечатанные непосредственно из приложений C, не будут перехвачены командой test. Поэтому использование опций -output и -errorOutput для команды test полезно только для чисто Tcl-приложений, которые используют команду puts для вывода.

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/tcltest.htm