The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-DescribeMe-0.004
River stage one • 6 direct dependents • 9 total dependents
3 ++
/ Test::DescribeMe

NAME

Test::DescribeMe - Tell test runners what kind of test you are

VERSION

version 0.004

SYNOPSIS

Maybe you're an author test and users shouldn't run you:

  use Test::DescribeMe qw(author);

Or maybe you are a really slow test you don't want to bother most people with:

  use Test::DescribeMe qw(extended);

Or perhaps you only want to run on smokers

  use Test::DescribeMe qw(smoke);

Or a combination there of

  use Test::DescribeMe qw(smoke extended);

Or you require user input

  use Test::DescribeMe qw(interactive);

DESCRIPTION

Sometimes you want to run (or not run) tests under certain conditions. This module provides a way to identify what kind of test a test is and will skip the test if the matching conditions aren't met. See "BACKGROUND" below for a longer description.

Usage

To describe what kind of test you are, you use() this module and pass test types to the import list. This SHOULD be done before importing Test::More if you set explicit plans or tests will break!

Example:

  use Test::DescribeMe qw(smoke);
  use Test::More tests => 5;

(Although you probably want "done_testing" in Test::More without explicit plans).

The available test descriptions and effects are:

  • smoke - This test only wants to run on smoke boxes.

  • interactive - This test requires user interaction and should not be run in cases where this isn't wanted or available

  • extended - This test should only be run if someone really wants to - as it may take a long time or use lots of resources.

  • author - This is an author test and should only be run during development time.

  • release - This is a release test and should onyl be run pre-release to ensure a build is insane.

More Control

If this doesn't provide the control you're looking for - for example, NOT running a test if on a smoker, see Test::Settings.

BACKGROUND

With the Lancaster Consensus at the Perl QA Hackathon 2013, a 'new' system has been defined which provides two new test environment variables and reaffirms an existing one.

AUTOMATED_TESTING was meant to be used by smokers, but has been abused to say things like "Only run this test on smokers since it takes a long time." The problem with this is install tools want to say "Run all tests but don't prompt the user" and the only way to do that is with AUTOMATED_TESTING, and so they end up running the long running tests and wasting time.

In order to support the other behaviors, AUTOMATED_TESTING will once again mean "I am a smoker running these tests" and two new environmental variables EXTENDED_TESTING and NONINTERACTIVE_TESTING will handle the two other cases.

EXTENDED_TESTING is for tests that may take a long time or require special configuration that is too complex for typical intalls - like requiring other software for testing or internet connections.

NONINTERACTIVE_TESTING can be used by a build system like App::cpanminus to say don't run tests that require user interaction.

SEE ALSO

Test::Settings - Ask or tell when certain types of tests should be run

Test::Is - Skip test in a declarative way, following the Lancaster Consensus

https://github.com/Perl-Toolchain-Gang/toolchain-site/blob/master/lancaster-consensus.md - The Annotated Lancaster Consensus

AUTHOR

Matthew Horsfall (alh) - <wolfsage@gmail.com>

LICENSE

You may distribute this code under the same terms as Perl itself.