prove

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ИСПОЛЬЗОВАНИЕ
• ПАРАМЕТРЫ
• ПРИМЕЧАНИЯ
  • .proverc
  • Чтение из STDIN
  • Директория по умолчанию для тестов
  • Вывод тестов с цветом
  • Код возврата
  • Аргументы для тестов
  • --exec
  • --merge
  • --trap
  • --state
  • --rules
    • Примеры --rules
    • Разрешение --rules
    • Совпадение по шаблонам в стиле Glob для --rules
    • Более сложные настройки для параллельного и последовательного выполнения правил
  • @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 в вашем объекте Оболочки.

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

Мы реализовали собственную систему совпадения по шаблонам в стиле 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.

Дополнительную информацию о том, как конфигурация передается SourceHandler, можно найти в 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.