NAME

Module::Install::TestTarget - Assembles Custom Test Targets For `make`

SYNOPSIS

inside Makefile.PL:

use inc::Module::Install;
tests 't/*t';

# override the default `make test`
default_test_target
    includes           => ["$ENV{HOME}/perl5/lib"],
    load_modules       => [qw/Foo Bar/],
    run_on_prepare     => [qw/before.pl/],
    run_on_finalize    => [qw/after.pl/],
    insert_on_prepare  => ['print "start -> ", scalar localtime, "\n"'],
    insert_on_finalize => ['print "end   -> ", scalar localtime, "\n"'],
    tests              => ['t/baz/*t'],
    env                => { PERL_ONLY => 1 },
;

# create a new test target (allows `make foo`)
test_target foo => (
    includes           => ["$ENV{HOME}/perl5/lib"],
    load_modules       => [qw/Foo Bar/],
    run_on_prepare     => [qw/before.pl/],
    run_on_finalize    => [qw/after.pl/],
    insert_on_prepare  => ['print "start -> ", scalar localtime, "\n"'],
    insert_on_finalize => ['print "end   -> ", scalar localtime, "\n"'],
    tests              => ['t/baz/*t'],
    env                => { PERL_ONLY => 1 },
    alias              => 'testall', # make testall is run the make foo
);

# above target 'foo' will turn into something like:
perl "-MExtUtils::Command::MM" "-I/home/xaicron/perl5/lib" "-MFoo" "-MBar" "-e" "do { local \$@; do 'before.pl'; die \$@ if $@ }; sub { print \"start -> \", scalar localtime, \"\n\" }->(); test_harness(0, 'inc'); do { local \$@; do 'after.pl'; die \$@ if \$@ }; sub { print \"end -> \", scalar localtime, \"\n\" }->();" t/baz/*t

DESCRIPTION

Module::Install::TestTarget creates make test variations with code snippets. This helps module developers to test their distributions with various conditions.

EXAMPLES

TEST A MODULE WITH XS/PP BACKENDS

Suppose your XS module can load a PurePerl backend by setting the PERL_ONLY environment variable. You can force your tests to use this environment flag using this construct:

test_target test_pp => (
    env => { PERL_ONLY => 1 },
);

TEST AN APP USING DATABASES

Suppose you want to instantiate a mysqld instance using Test::mysqld, but you don't want to start/stop mysqld for every test script. You can start mysqld once using this module.

First create a script like this:

# t/start_mysqld.pl
use Test::mysqld;
my $mysqld = Test::mysqld->new( ... );

Then in your Makefile.PL, simply specify that you want to run this script before executing any tests.

test_target test_db => (
    run_on_prepare => [ 't/start_mysqld.pl' ]
);

Since the script is going to be executed in global scope, $mysqld will stay active during the execution of your tests -- the mysqld instance that came up will shutdown automatically after the tests are executed.

You can use this trick to run other daemons, such as memcached (maybe via Test::Memcached)

FUNCTIONS

test_target($target, %args)

Defines a new test target with %args.

%args are:

includes => \@include_paths

Sets include paths.

test_target foo => (
    includes => ['/path/to/inc'],
);

# `make foo` will be something like this:
perl -I/path/to/inc  -MExtUtils::Command::MM -e "test_harness(0, 'inc')" t/*t

load_modules => \@module_names

Sets modules which are loaded before running test_harness().

test_target foo => (
    load_modules => ['Foo', 'Bar::Baz'],
);

# `make test` will be something like this:
perl -MFoo -MBar::Baz -MExtUtils::Command::MM -e "test_harness(0, 'inc')" t/*t

run_on_prepare => \@scripts

Sets scripts to run before running test_harness().

test_target foo => (
    run_on_prepare => ['tool/run_on_prepare.pl'],
);

# `make foo` will be something like this:
perl -MExtUtils::Command::MM -e "do { local \$@; do 'tool/run_on_prepare.pl; die \$@ if \$@ }; test_harness(0, 'inc')" t/*t

run_on_finalize => \@scripts

Sets scripts to run after running test_harness().

use inc::Module::Install;
tests 't/*t';
test_target foo => (
    run_on_finalize => ['tool/run_on_after.pl'],
);

# `make foo` will be something like this:
perl -MExtUtils::Command::MM -e "test_harness(0, 'inc'); do { local \$@; do 'tool/run_on_after.pl; die \$@ if \$@ };" t/*t

insert_on_prepare => \@codes

Sets perl codes to run before running test_harness().

use inc::Module::Install;
tests 't/*t';
test_target foo => (
    insert_on_prepare => ['print scalar localtime , "\n"', sub { system qw/cat README/ }],
);

# `make foo` will be something like this:
perl -MExtUtils::Command::MM "sub { print scalar localtme, "\n" }->(); sub { system 'cat', 'README' }->(); test_harness(0, 'inc')" t/*t

The perl codes runs run_on_prepare runs later.

insert_on_finalize => \@codes

Sets perl codes to run after running test_harness().

use inc::Module::Install;
tests 't/*t';
test_target foo => (
    insert_on_finalize => ['print scalar localtime , "\n"', sub { system qw/cat README/ }],
);

# `make foo` will be something like this:
perl -MExtUtils::Command::MM "test_harness(0, 'inc'); sub { print scalar localtme, "\n" }->(); sub { system 'cat', 'README' }->();" t/*t

The perl codes runs run_on_finalize runs later.

alias => $name

Sets an alias of the test.

test_target test_pp => (
    run_on_prepare => 'tool/force-pp.pl',
    alias          => 'testall',
);

# `make test_pp` and `make testall` will be something like this:
perl -MExtUtils::Command::MM -e "do { local \$@; do 'tool/force-pp.pl'; die \$@; if \$@ }; test_harness(0, 'inc')" t/*t

alias_for_author => $name

The same as alias, but only enabled if it is in author's environment.

env => \%env

Sets environment variables.

test_target foo => (
    env => {
        FOO => 'bar',
    },
);

# `make foo` will be something like this:
perl -MExtUtils::Command::MM -e "\$ENV{q{FOO}} = q{bar}; test_harness(0, 'inc')" t/*t

tests => \@test_files

Sets test files to run.

test_target foo => (
    tests  => ['t/foo.t', 't/bar.t'],
    env    => { USE_FOO => 1 },
);

# `make foo` will be something like this:
perl -MExtUtils::Command::MM -e "$ENV{USE_FOO} = 1 test_harness(0, 'inc')" t/foo.t t/bar.t

default_test_target(%args)

Override the default `make test` with %args.

Same argument as test_target(), but `target` and `alias` are not allowed.

AUTHOR

Yuji Shimada <xaicron {at} cpan.org>

Goro Fuji (gfx) <gfuji at cpan.org>

Maki Daisuke (lestrrat)

SEE ALSO

Module::Install

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Module::Install::TestTarget

perl -MCPAN -e shell
install Module::Install::TestTarget