Test::Manifest(3)

📦
version 2.026 · 13 versions
, in fedora 43

💅 Test::Manifest — like, the manual page, but make it make sense ✨

okay so bestie, welcome to Test::Manifest (that's the Test::Manifest(3) manpage, from the User Contributed Perl Documentation section — we're in Perl land now, buckle up 🎀).

🌸 NAME 🌸

Test::Manifest — the module that lets you vibe with a t/test_manifest file 💖

✨ SYNOPSIS ✨

here's the whole shape of it, no cap:

        # in Makefile.PL
        eval "use Test::Manifest 2.00";

        # in Build.PL
        my $class = do {
                if( eval 'use Test::Manifest 2.00; 1' ) {
                        Test::Manifest->get_module_build_subclass;
                        }
                else {
                        'Module::Build';
                        }
                };

        my $build = $class->new( ... )

        # in the file t/test_manifest, list the tests you want
        # to run in the order you want to run them

like, that last comment is literally the whole point of the module, bestie 💀

🦋 DESCRIPTION 🦋

so Test::Harness just assumes you wanna run every single .t file in the t/ directory in ASCII-betical order during make test or ./Build test unless you say otherwise. which, honestly? rude. 😭

and that leads people to invent interesting naming schemes for their test files just to force them into the order they want. and those interesting names? they ossify when they hit source control. and then they get even more interesting as more tests show up. it's giving chaos, honestly.

enter Test::Manifest 👑 it overrides the default test file order. instead of running all the t/*.t files in ASCII-betical order, it goes and looks in the t/test_manifest file to find out which tests you actually want to run and the order you want to run them in. then it constructs the right value for the build system so everything does the right thing. slay.

in t/test_manifest, you just literally list the tests you want to run. their order in the file is the order they run in, periodt.

  • you can comment lines with a #, just like in Perl
  • Test::Manifest will strip leading and trailing whitespace from each line
  • it also checks that the specified file is actually in the t/ directory
  • if the file doesn't exist, it does not put its name in the list of test files to run, and it will issue a warning ⚠️

optionally, you can add a number after the test name in test_manifest to define sets of tests. see "get_t_files" for the whole tea ☕

🧚 ExtUtils::MakeMaker

to override the test order behaviour in MakeMaker, Test::Manifest inserts itself into the test_via_harness step by providing its own test runner 🫶

in Makefile.PL, all you gotta do is load Test::Manifest before you call WriteMakefile. and to make it optional (which, iconic), load it in an eval:

        eval "use Test::Manifest";

🍓 Module::Build

overriding parts of Module::Build is tricker if you wanna use the subclassing mechanism and still make Test::Manifest optional. but listen — if you can load Test::Manifest (version 2.00 or later), Test::Manifest can create the subclass for you 💅

        my $class = do {
                if( eval 'use Test::Manifest 2.00; 1' ) {
                        Test::Manifest->get_module_build_subclass;
                        }
                else {
                        'Module::Build' # if Test::Manifest isn't there
                        }
                };

        $class->new( ... );
        $class->create_build_file;

now — this is a bit of a problem when you already have your own subclass. but no worries, because Test::Manifest overrides find_test_files, so you can grab just that code and add it to your own subclass code string:

        my $code = eval 'use Test::Manifest 2.00; 1'
                        ?
                Test::Manifest->get_module_build_code_string
                        :
                '';

        my $class = Module::Build->subclass(
                ...,
                code => "$code\n...your subclass code string...",
                );

⭐ Class methods ⭐

get_module_build_subclass

For Module::Build only. 💜

returns a Module::Build subclass that overrides find_test_files. and if you wanna have your own Module::Build subclass and still use Test::Manifest, you can get just the code string with get_module_build_code_string.

get_module_build_code_string

For Module::Build only. 💜

returns the overridden find_test_files as Perl code in a string, suitable for the code key in Module::Build-subclass()>`. you can add this to other bits you're overriding or extending. cute, right?

see Module::Build::Base::find_test_files to see the base implementation 👀

🌈 Functions 🌈

run_t_manifest( TEST_VERBOSE, INST_LIB, INST_ARCHLIB, TEST_LEVEL )

For MakeMaker only. you don't have to mess with this at the user level, bestie, it's not for you 🙈

runs all of the files in t/test_manifest through Test::Harness:runtests in the order they appear in the file. this is inserted automatically, like so:

        eval "use Test::Manifest";

get_t_files( [LEVEL] )

in scalar context it returns a single string that you can use directly in WriteMakefile(). in list context it returns a list of the files it found in t/test_manifest.

if a t/test_manifest file does not exist, get_t_files() returns nothing.

get_t_files() warns you if it can't find t/test_manifest, or if entries start with t/. it skips blank lines, and strips Perl style comments from the file.

each line in t/test_manifest can have three parts: the test name, the test level (a floating point number), and a comment. by default, the test level is 1.

        test_name.t 2  #Run this only for level 2 testing

without an argument, get_t_files() returns all the test files it finds. with an argument that is true (so heads up — you can't use 0 as a level 💀) and is a number, it skips tests with a level greater than that argument. then you can define sets of tests and choose a set to run. for instance, you might create a set for end users, but also add on a set for deeper testing for developers. main character energy for both audiences, honestly.

experimentally, you can include a command to grab test names from another file. the command starts with a ; to distinguish it from a true filename. the filename (currently) is relative to the current working directory, unlike the filenames, which are relative to t/. the filenames in the included file are still relative to t/.

        ;include t/file_with_other_test_names.txt

also experimentally, you can stop Test::Manifest from reading filenames with the ;skip directive. Test::Manifest will skip the filenames up to the ;unskip directive (or end of file):

        run_this1
        ;skip
        skip_this
        ;unskip
        run_this2

to select sets of tests, specify the level in the environment variable TEST_LEVEL:

        make test # run all tests no matter the level
        make test TEST_LEVEL=2  # run all tests level 2 and below

eventually this will end up as an option to Build.PL:

        ./Build test --testlevel=2  # Not yet supported
🫶 heads up: that --testlevel thing is not yet supported. don't come for me, I'm just the messenger.

make_test_manifest()

creates the test_manifest file in the t directory by reading the contents of the t/ directory.

TO DO: specify tests in argument lists.

TO DO: specify files to skip.

like, those are literally the TO DOs. we're manifesting them ✨

manifest_name()

returns the name of the test manifest file, relative to t/. 🎀

🔥 SOURCE AVAILABILITY 🔥

this source is in Github:

        http://github.com/briandfoy/test-manifest/

go star it, iykyk ⭐

💖 CREDITS 💖

  • Matt Vanderpol suggested and supplied a patch for the ;include feature. king behaviour 👑
  • Olivier Mengué supplied a documentation patch. also king behaviour 👑

💜 AUTHOR 💜

brian d foy, "<briandfoy@pobox.com>"

Copyright © 2002-2025, brian d foy <briandfoy@pobox.com>. All rights reserved.

this program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

and that's the whole page, bestie 🫶 this was perl v5.42.0, dated 2025-07-25, and it's the Test::Manifest(3) manpage — go forth and manifest your tests in the exact order you want 💅✨

📦 where this page comes from