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