/ 
Test-Load-Helper-1.0.1
/ Test::Load::Helper

NAME

Test::Load::Helper - automatically load test helpers by walking the directory tree

SYNOPSIS

# finds and loads the nearest test-helper.pl, searching upward from the calling file
use Test::Load::Helper;

# load a specialised helper instead of the default
use Test::Load::Helper file => q (test-helper-schema.pl);

# load helper into a specific package rather than the caller's own namespace
use Test::Load::Helper into => q (My::Fixtures);

# load a helper at an explicit relative path; its own hierarchy is honoured
use Test::Load::Helper file => q (./contracts/test-helper.pl);

DESCRIPTION

Inspired by the test_helper convention from RSpec, this module locates and loads a Perl test helper file by walking up the directory tree from the calling file. It removes the need for hardcoded relative paths such as require q (../../test-helper.pl).

When a test file does use Test::Load::Helper, the module determines the target package and the starting directory, then searches upward for a helper file. The file is evaluated inside the target package with use strict and use warnings in effect.

If no helper file is found the module does nothing silently — this is not an error.

Hierarchical helpers

A test-helper.pl may itself use Test::Load::Helper to chain to its parent:

# t/contracts/test-helper.pl
use Test::Load::Helper;            # loads t/test-helper.pl
use constant CONTRACT_HELPER => 1;

When a test case in t/contracts/ loads its local helper, both the local and the ancestor helper are evaluated, building up a chain of shared fixtures.

Deduplication

The same helper file is never evaluated into the same package twice. If two specialised helpers both chain to a common base, the base is evaluated only once. Because the internal key encodes both file path and target package, the same file can be loaded into different packages independently.

Bounding traversal

Set $ENV{TEST_LOAD_ROOT} to an absolute path to stop traversal at a given directory. This is useful in monorepos where helpers from a sibling project should not be picked up.

IMPORTING

The following named arguments are recognised by import:

file

Name or relative path of the helper file to search for. Defaults to test-helper.pl. A path such as ./subdir/test-helper.pl is resolved relative to the caller's directory; the hierarchy from that file's own directory is then honoured.

into

Package into which the helper is evaluated. Defaults to the caller's own package. Useful when loading shared fixtures into a dedicated namespace:

package My::Fixtures { use Test::Load::Helper }

# or equivalently:
use Test::Load::Helper into => q (My::Fixtures);

ENVIRONMENT

TEST_LOAD_ROOT

Absolute path at which upward traversal stops (inclusive). When unset, traversal continues to the filesystem root.

AUTHOR

Branislav Zahradník <barney.cpan@gmail.com>

COPYRIGHT AND LICENSE

Test::Load::Helper distribution is distributed under the Artistic License 2.0.