Test::...bution(3pm)

📦
version 2.00 · 7 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Test::...bution(3pm) — the Test::Distribution era 💖

okay bestie, sit down, grab a strawberry 🍓, because we're talking about Test::Distribution — a lil Perl module whose whole entire job is perform tests on all modules of a distribution. yes. it literally stress-tests your whole distro for you. no cap.

this one lives in User Contributed Perl Documentation, and she's giving very much "senior dev who still emails you back" energy. 💅

✨ SYNOPSIS ✨

like, here's the vibe. you make a test file and it goes a lil something like this:

$ cat t/01distribution.t
use Test::More;

BEGIN {
      eval {
              require Test::Distribution;
      };
      if($@) {
              plan skip_all => 'Test::Distribution not installed';
      }
      else {
              import Test::Distribution;
      }
 }

$ make test
...

that's it. that's the whole ass script. she does the rest. 🎀

🌸 DESCRIPTION 🌸

so when you drop this module into a test script, it goes through all the modules in your distribution and it:

  • checks their POD 📝
  • checks that they compile ok ✅
  • checks that they all define a $VERSION 🔢

but wait, there's more (there's always more). this module also runs a whole number of tests on the distribution itself:

  • it checks that your files match your SIGNATURE file, if you have one
  • it checks that your distribution isn't missing certain 'core' description files 👑
  • it checks to see you haven't missed out listing any pre-requisites in Makefile.PL

and here's the thing — it defines its own testing plan. so you usually don't use it together with other Test::* modules in the same file. the recommendation is literally to just make a one-line test script like the one in the SYNOPSIS up there. but… there are options. 👀

NOTE: if you do not specify any options, Test::Distribution will run all test types except signature testing, which must always be explicitly switched on. (yes, sig is shy. respect her boundaries.)

and fr fr, the author says: "In the future I may change the default to run no tests at all as this sounds safer. Mail me if you disagree." so if you have opinions, you know where to send them 📬

✨ OPTIONS ✨

on the line where you use() this module, you can throw in named arguments that influence the testing behavior. let's go one by one bestie.

  • tests => NUMBER — says that in addition to the tests this module runs, your test script is gonna run extra tests of its own. in other words, this value influences the test plan. for example:
use Test::Distribution tests => 1;
use Test::More;
is($foo, $bar, 'baz');

super important: do NOT pass a tests argument when you're using Test::More or other test modules, because the plan is being handled by Test::Distribution.

DEPRECATED FEATURE. the author plans to remove this in the future unless someone contacts them saying they find it useful. 👀 so like… speak now or forever hold your peace.
  • only => STRING|LIST — says only certain sets of tests should run. the possible values are the ones listed down in TEST TYPES. so if you only want the POD tests, you'd say:
use Test::Distribution only => 'pod';

and if you want the POD tests and the use tests and you're also running two tests of your own, you'd say:

use Test::Distribution
  only  => [ qw/pod use/ ],
  tests => 2;

tiny lil heads up 🫶: when you specify the versions option, the use option gets automatically added, because to get a module's $VERSION it has to be loaded. and since we're loading it anyway, might as well run a use test, right? efficiency queen.

the value for only can be a string or a reference to a list of strings.

  • not => STRING|LIST — says certain types of tests should not run. everything not mentioned in this argument runs. so if you want to test everything except POD:
use Test::Distribution
  not => 'pod';

the value for not can be a string or a reference to a list of strings. and yes — even though it doesn't seem to make much sense, you can use both only and not. in that case, only the tests specified in only, but not in not, get run (if this makes any sense 💀).

  • distversion — if you set this to a true value, then as well as testing that each module has a $VERSION defined, Test::Distribution will also make sure that the $VERSION matches that of the distribution. queen of consistency 👑
  • podcoveropts — you can set this to a hash reference of options to pass to Test::Pod::Coverage's pod_coverage_ok method (which in turn gets passed to Pod::Coverage). pass the vibes along, yk?

🌈 TEST TYPES 🌈

here's the whole menu of available tests. pick your fighters 🥊

  • description — checks that the following files exist:
Changes  or ChangeLog
MANIFEST
README
Build.PL or Makefile.PL
  • prereq — checks whether all use()d modules that aren't in the perl core are also mentioned in Makefile.PL's PREREQ_PM. (so basically, did you forget to declare a dependency? because that's a crime.)
  • pod — checks for POD errors in files.
  • podcover — checks for Pod Coverage.
  • sig — if the distribution has a SIGNATURE file, checks that the SIGNATURE matches the files.
  • use — this use()s the modules to make sure the load happens ok.
  • versions — checks that all packages define $VERSION strings.

💜 EXPOSED INTERNALS 💜

there are a few subroutines that help you see what this module is doing. note: these subroutines are neither exported nor exportable, so you have to call them fully qualified. no shortcuts bestie.

  • Test::Distribution::packages() — this is a list of packages that have been found. basically, we assume each file contains a package with the name indicated by the file's relative position. for example, a file in blib/lib/Foo/Bar.pm is expected to be available via use Foo::Bar. 📦
  • Test::Distribution::files() — this is a list of files that tests have been run on. the filenames are relative to the distribution's root directory, so they start with blib/lib. 📁
  • Test::Distribution::num_tests() — this is the number of tests that this module has run, based on your specifications. 🔢

🎀 INSTALLATION 🎀

this module uses Module::Build for its installation. to install this module, type the following:

perl Build.PL
./Build
./Build test
./Build install

if you do not have Module::Build, type:

perl Makefile.PL

to fetch it. or use CPAN or CPANPLUS and fetch it "manually". ✨

💅 DEPENDENCIES 💅

this module requires these other modules and libraries:

File::Basename
File::Find::Rule
File::Spec
Test::More

this module has these optional dependencies:

Module::CoreList
Test::Pod
Test::Pod::Coverage
  • if Module::CoreList is missing, the prereq tests are skipped.
  • if Test::Pod is missing, the pod tests are skipped.

⭐ TODO ⭐

just because these items are in the todo list, does not mean they will actually be done. if you think one of these would be helpful, say so — and it'll move up on the priority list. 📈

  • Module::Build support [currently waiting for a fix on Test::Prereq]

🦋 FEATURE IDEAS 🦋

  • export test type — this would mandate that there should be a test for each exported symbol of each module.

let the author know what you think of these ideas. are they necessary? unnecessary? do you have feature requests of your own? spill 🫖

💀 BUGS 💀

to report a bug or request an enhancement, use CPAN's excellent Request Tracker. go on, they're nice about it.

👑 SOURCE AVAILABILITY 👑

this source is part of a SourceForge project which always has the latest sources in svn.

http://sourceforge.net/projects/sagar-r-shah/

🌸 AUTHORS 🌸

Marcel Gruenauer <marcel@cpan.org>

Sagar R. Shah

🧚 OTHER CREDITS 🧚

this module was inspired by a use.perl.org journal entry by "brian d foy" (see <http://use.perl.org/~brian_d_foy/journal/7463>) where he describes an idea by Andy Lester. iconic lineage honestly 🤝

Copyright 2002-2003 Marcel Gruenauer. All rights reserved.

Copyright 2003-2007, Sagar R. Shah, All rights reserved.

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

🌈 SEE ALSO 🌈

perl(1), ExtUtils::Manifest(3pm), File::Find::Rule(3pm), Module::CoreList(3pm), Test::More(3pm), Test::Pod(3pm), Test::Pod::Coverage(3pm), Test::Signature(3pm).

and that's the whole page bestie! 🫶 this was documented as part of perl v5.36.0, dated 2022-10-14, under the <rainbow>Test::...bution(3pm)</rainbow> manual name — go write some tests, you absolute main character 👑✨

📦 where this page comes from