prove

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ИСПОЛЬЗОВАНИЕ
• ПАРАМЕТРЫ
• ПРИМЕЧАНИЯ
  • .proverc
  • Чтение из STDIN
  • Директория по умолчанию для тестов
  • Цветной вывод тестов
  • Код завершения
  • Аргументы для тестов
  • --exec
  • --merge
  • --trap
  • --state
  • --rules
    • Примеры --rules
    • Разрешение --rules
    • Сопоставление шаблонов --rules в стиле Glob
    • Более сложные настройки для параллельного и последовательного выполнения правил
  • @INC
  • Режим taint
• ФОРМАТИРОВЩИКИ
• ОБРАБОТЧИКИ ИСТОЧНИКОВ
• ПЛАГИНЫ
  • Доступные плагины
  • Создание плагинов

НАЗВАНИЕ

prove - Запуск тестов с помощью TAP-оболочки.

ИСПОЛЬЗОВАНИЕ

prove [options] [files or directories]

ПАРАМЕТРЫ

Логические параметры:

-v,  --verbose         Print all test lines.
-l,  --lib             Add 'lib' to the path for your tests (-Ilib).
-b,  --blib            Add 'blib/lib' and 'blib/arch' to the path for
                       your tests
-s,  --shuffle         Run the tests in random order.
-c,  --color           Colored test output (default).
     --nocolor         Do not color test output.
     --count           Show the X/Y test count when not verbose
                       (default)
     --nocount         Disable the X/Y test count.
-D   --dry             Dry run. Show test that would have run.
-f,  --failures        Show failed tests.
-o,  --comments        Show comments.
     --ignore-exit     Ignore exit status from test scripts.
-m,  --merge           Merge test scripts' STDERR with their STDOUT.
-r,  --recurse         Recursively descend into directories.
     --reverse         Run the tests in reverse order.
-q,  --quiet           Suppress some test output while running tests.
-Q,  --QUIET           Only print summary results.
-p,  --parse           Show full list of TAP parse errors, if any.
     --directives      Only show results with TODO or SKIP directives.
     --timer           Print elapsed time after each test.
     --trap            Trap Ctrl-C and print summary on interrupt.
     --normalize       Normalize TAP output in verbose output
-T                     Enable tainting checks.
-t                     Enable tainting warnings.
-W                     Enable fatal warnings.
-w                     Enable warnings.
-h,  --help            Display this help
-?,                    Display this help
-V,  --version         Display the version
-H,  --man             Longer manpage for prove
     --norc            Don't process default .proverc

Параметры, принимающие аргументы:

-I                     Library paths to include.
-P                     Load plugin (searches App::Prove::Plugin::*.)
-M                     Load a module.
-e,  --exec            Interpreter to run the tests ('' for compiled
                       tests.)
     --ext             Set the extension for tests (default '.t')
     --harness         Define test harness to use.  See TAP::Harness.
     --formatter       Result formatter to use. See FORMATTERS.
     --source          Load and/or configure a SourceHandler. See
                       SOURCE HANDLERS.
-a,  --archive out.tgz Store the resulting TAP in an archive file.
-j,  --jobs N          Run N test jobs in parallel (try 9.)
     --state=opts      Control prove's persistent state.
     --statefile=file  Use `file` instead of `.prove` for state
     --rc=rcfile       Process options from rcfile
     --rules           Rules for parallel vs sequential processing.

ПРИМЕЧАНИЯ

.proverc

Если файлы ~/.proverc или ./.proverc существуют, они будут прочитаны, и все параметры, которые они содержат, будут обработаны перед параметрами командной строки. Параметры в .proverc задаются так же, как и параметры командной строки:

# .proverc
--state=hot,fast,save
-j9

Дополнительные файлы параметров могут быть указаны с помощью параметра --rc. Обработка файлов параметров по умолчанию отключена параметром --norc.

В Windows и VMS файл параметров называется _proverc, а не .proverc и ищется только в текущей директории.

Чтение из STDIN

Если у вас есть список тестов (или URL-адресов, или чего-либо ещё, что вы хотите протестировать) в файле, вы можете добавить их в свои тесты, используя символ '-':

prove - < my_list_of_things_to_test.txt

См. README в каталоге examples этого дистрибутива.

Директория по умолчанию для тестов

Если не указаны файлы или директории, prove ищет все файлы, соответствующие шаблону t/*.t.

Цветной вывод тестов

Цветной вывод тестов с помощью TAP::Formatter::Color по умолчанию включён, но если вывод не направлен на терминал, цвет отключается. Вы можете переопределить это, добавив переключатель --color.

Поддержка цвета требует Term::ANSIColor и, в системах Windows, также Win32::Console::ANSI. Если необходимые модули не установлены, цветной вывод не будет доступен.

Код завершения

Если тесты завершаются неудачно, prove выйдет со статусом, отличным от нуля.

Аргументы для тестов

Возможна передача аргументов тестам. Для этого разделите их от собственных аргументов prove с помощью двоеточия '::'. Например

prove -v t/mytest.t :: --url http://example.com

запустит t/mytest.t с параметрами '--url http://example.com'. При запуске нескольких тестов каждый из них получит те же аргументы.

--exec

Обычно достаточно передать список Perl-тестов, и оболочка узнает, как их выполнить. Однако, если ваши тесты написаны не на Perl, или если вы хотите, чтобы все тесты вызывались одинаково, используйте параметр -e, или --exec:

prove --exec '/usr/bin/ruby -w' t/
prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/
prove --exec '/path/to/my/customer/exec'

--merge

Если вам нужно убедиться, что диагностические сообщения отображаются в правильном порядке относительно результатов тестов, вы можете использовать параметр --merge для объединения STDERR скриптов тестов в их STDOUT.

Это гарантирует, что STDOUT (где отображаются результаты тестов) и STDERR (где отображаются диагностические сообщения) будут синхронизированы. Оболочка отобразит все диагностические сообщения, которые ваши тесты выведут в STDERR.

Предупреждение: это немного хак. В частности, обратите внимание, что если что-то, что появляется в STDERR, выглядит как результат теста, оболочка тестов может запутаться. Используйте этот параметр только в том случае, если вы понимаете последствия и можете смириться с риском.

--trap

Параметр --trap попытается перехватить SIGINT (Ctrl-C) во время выполнения теста и отобразить сводку теста, даже если выполнение было прервано

--state

Вы можете попросить prove запомнить состояние предыдущих запусков тестов и выбрать/упорядочить тесты для выполнения на основе сохранённого состояния.

Параметр --state требует аргумента, который должен быть списком, разделённым запятыми, одного или нескольких следующих параметров.

last

Запустить те же тесты, что и в прошлый раз, когда состояние было сохранено. Это позволяет, например, восстановить порядок перемешанного теста.

# Run all tests in random order
$ prove -b --state=save --shuffle

# Run them again in the same order
$ prove -b --state=last

failed

Запустить только тесты, которые завершились неудачей в предыдущем запуске.

# Run all tests
$ prove -b --state=save

# Run failures
$ prove -b --state=failed

Если вы также укажете параметр save, вновь пройденные тесты будут исключены из последующих запусков.

# Repeat until no more failures
$ prove -b --state=failed,save

passed

Запустить только тесты, которые завершились успехом в прошлый раз. Полезно для того, чтобы убедиться, что не возникли новые проблемы.

all

Запустить все тесты в обычном порядке. Можно указать несколько параметров, например, чтобы запустить все тесты, а те, что завершились неудачей в прошлый раз, в начале:

$ prove -b --state=failed,all,save

hot

Запустить тесты, которые в последний раз завершились неудачей, в первую очередь. Время последней неудачи каждого теста сохраняется. Параметр hot заставляет тесты выполняться в порядке последней неудачи.

$ prove -b --state=hot,save

Тесты, которые никогда не завершались неудачей, не будут выбраны. Чтобы запустить все тесты, начиная с последней неудачи, используйте

$ prove -b --state=hot,all,save

Это сочетание параметров также может быть указано следующим образом

$ prove -b --state=adrian

todo

Запустить все тесты со статусом todo.

slow

Запустить тесты в порядке от самых медленных к самым быстрым. Это полезно в сочетании с параметром параллельного тестирования -j, чтобы убедиться, что ваши самые медленные тесты начнут выполняться первыми.

$ prove -b --state=slow -j9

fast

Запустить тесты в порядке от самых быстрых к самым медленным.

new

Запустить тесты в порядке от самых новых к самым старым на основе времени модификации скриптов тестов.

old

Запустить тесты в порядке от самых старых к самым новым.

fresh

Запустить те скрипты тестов, которые были изменены после последнего выполнения тестов.

save

Сохранить состояние при завершении. Состояние сохраняется в файл .prove (_prove в Windows и VMS) в текущей директории.

Параметр --state может быть указан более одного раза.

$ prove -b --state=hot --state=all,save

--rules

Параметр --rules используется для управления тем, какие тесты выполняются последовательно, а какие — параллельно, если указан параметр --jobs. Этот параметр может быть указан несколько раз, и порядок имеет значение.

Наиболее практичное использование, вероятно, заключается в указании того, что некоторые тесты не «готовы к параллельному выполнению». Поскольку упоминание файла с помощью --rules не приводит к его выбору для выполнения в качестве теста, вы можете «установить и забыть» некоторые предпочтения правил в файле .proverc. Тогда вы сможете извлечь максимальную выгоду из преимуществ параллельного тестирования, сохраняя при этом некоторые исключения, которые будут выполняться последовательно.

Примеры --rules

# All tests are allowed to run in parallel, except those starting with "p"
--rules='seq=t/p*.t' --rules='par=**'

# All tests must run in sequence except those starting with "p", which should be run parallel
--rules='par=t/p*.t'

Разрешение --rules

• По умолчанию все тесты могут выполняться параллельно. Указание любых собственных правил отменяет это правило.

• «Первое совпадение — выигрывает». Первое правило, которое соответствует тесту, будет применено.

• Любой тест, который не соответствует ни одному правилу, будет выполнен последовательно в конце выполнения.

• Наличие правила не подразумевает выбор теста. Вам по-прежнему необходимо указать тесты для выполнения.

• Указание правила для разрешения параллельного выполнения тестов не заставляет их выполняться параллельно. Вам по-прежнему необходимо указать количество параллельных jobs в вашем объекте оболочки.

Сопоставление шаблонов --rules в стиле Glob

Мы реализовали собственное сопоставление шаблонов в стиле Glob для --rules. Вот поддерживаемые шаблоны:

** is any number of characters, including /, within a pathname
* is zero or more characters within a filename/directory name
? is exactly one character within a filename/directory name
{foo,bar,baz} is any of foo, bar or baz.
\ is an escape character

Более сложные настройки для параллельного и последовательного выполнения правил

Если вам нужно более сложное управление тем, что выполняется параллельно, а что последовательно, см. соответствующую документацию по «правилам» в TAP::Harness и TAP::Parser::Scheduler. Если того, что возможно напрямую с помощью prove недостаточно, вы можете написать свою собственную оболочку для прямого доступа к этим функциям.

@INC

prove вводит разделение между «параметрами, переданными Perl, который запускает prove», и «параметрами, переданными Perl, который запускает тесты»; это сделано намеренно. Таким образом, Perl, который запускает тест, начинает с каталогов по умолчанию @INC. Дополнительные каталоги библиотек можно добавить через переменную окружения PERL5LIB, через -Ifoo в PERL5OPT или через параметр -Ilib к prove.

Режим taint

Обычно, когда Perl-программа выполняется в режиме taint, содержимое переменной окружения PERL5LIB не отображается в @INC.

Поскольку PERL5LIB часто используется во время тестирования для добавления каталогов сборки в @INC, prove передает имена любых каталогов, найденных в PERL5LIB, в качестве параметров -I. Это приводит к тому, что PERL5LIB учитывается, даже когда prove выполняется в режиме taint.

ФОРМАТИРОВЩИКИ

Вы можете загрузить пользовательский TAP::Parser::Formatter:

prove --formatter MyFormatter

ОБРАБОТЧИКИ ИСТОЧНИКОВ

Вы можете загрузить пользовательские TAP::Parser::SourceHandler, чтобы изменить способ, которым парсер интерпретирует определенные источники TAP.

prove --source MyHandler --source YetAnother t

Если вы хотите предоставить конфигурацию источнику, вы можете использовать:

prove --source MyCustom \
      --source Perl --perl-option 'foo=bar baz' --perl-option avg=0.278 \
      --source File --file-option extensions=.txt --file-option extensions=.tmp t
      --source pgTAP --pgtap-option pset=format=html --pgtap-option pset=border=2

Каждый --$source-option параметр должен задавать пару ключ/значение, разделенную =. Если параметр может принимать несколько значений, просто укажите его несколько раз, как в примерах extensions= выше. Если параметр должен быть ссылкой на хэш, укажите значение как вторую пару, разделенную =, как в примерах pset= выше (экранируйте = с обратной косой чертой).

Все --sources объединяются в хэш и передаются в параметр sources «new» в TAP::Harness.

Для получения более подробной информации о том, как конфигурация передаётся в SourceHandlers, см. TAP::Parser::IteratorFactory.

ПЛАГИНЫ

Плагины могут быть загружены с помощью синтаксиса -Pplugin, например:

prove -PMyPlugin

Это будет искать модуль под названием App::Prove::Plugin::MyPlugin, а если не найдёт, MyPlugin. Если плагин не будет найден, prove сообщит об ошибке и выйдет.

Вы можете передавать аргументы вашему плагину, добавив =arg1,arg2,etc к имени плагина:

prove -PMyPlugin=fou,du,fafa

Пожалуйста, обратитесь к документации по каждому плагину для получения более подробной информации.

Доступные плагины

Для получения актуального списка доступных плагинов, пожалуйста, обратитесь к CPAN:

http://search.cpan.org/search?query=App%3A%3AProve+Plugin

Написание плагинов

См. раздел "PLUGINS" в App::Prove.