Module:...stTarget(3)

💖 Module::Install::TestTarget 💖

hey bestie, welcome to the Module:...stTarget(3) page from the User Contributed Perl Documentation crew 🫶 this is the whole vibe: custom test targets for make, assembled with code snippets so your distribution gets tested under all kinds of conditions. no cap.

---

🌸 NAME 🌸

Module::Install::TestTarget — Assembles Custom Test Targets For make ✨

---

✨ SYNOPSIS ✨

okay so inside Makefile.PL, it’s giving this:

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. literally a lil custom test-target machine, and it eats 💅

---

🌈 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 run, and 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 run, and 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.

---

mwah 💋 that’s the whole page — it’s from perl v5.40.0, dated 2024-09-05, and the page is Module:...stTarget(3) 🦋✨