prove

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

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

Выполнить любые тесты с заданиями.

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 в вашем объекте Harness.

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

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

ПЛАГИНЫ

Плагины можно загрузить, используя синтаксис -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.