BrowserREPL-button-tip-on BrowserREPL-button-tip-off

EditButtonTip 2026-03-26

Distributions: testing

Testing your distribution of modules

A testing program such as Perl's prove or the Raku equivalent prove6 can be run in the root directory of the distribution as, e.g., 

prove -e 'raku -I.'
Code

or

prove6 -I.
Code

In both cases, the testing program looks for a directory t/ and runs the test programs there (see Testing).

The parameter -I., rather than -Ilib, in the examples above is significant because then the compiler will inspect the META6.json file in the root directory of the distribution.

If you are just beginning to develop a module (or series of modules), and you have not decided what to call or where to place the code (perhaps splitting it into several *.rakumod files), but assuming all the module files are under the lib/ directory, then it is possible to use 

prove6 -Ilib
Code

This is deceptive. A distribution may pass all the tests based on local files, and it may pass release steps, but the distribution (and the modules/classes/roles it contains) may not be automatically installed. To give a common example, but not the only way this problem can manifest itself, if the distribution is listed in the depends section of another distribution, and a user is trying to install the other distribution using zef (or a package manager using the same testing regime), perhaps using a CLI command zef install --deps-only ., then zef arranges for the tests of the dependent modules based on -I. and not -Ilib. This will lead to rakudo errors complaining about the absence of named compunits unless the META6.json file is correct.

The use-ok Test§

The most basic test that should be run for each compunit that is defined for the distribution is 

use-ok 'MyModule';
Code

assuming inside META6.json there is a line such as 

provides: { "MyModule": "lib/MyModule.rakumod" },
Code

The meta-ok test§

It is also highly recommended to use the Test::META meta-ok test, which verifies the validity of the META6.json file. If you wish to add a distribution (containing modules) to the Ecosystem, then this test will be applied to the distribution.

Extended Tests§

Since meta-ok only needs to be tested by the developer/maintainer of a distribution, it can be within a set of extended tests in another directory, e.g. /xt. This is because prove6, for example, only runs the tests in t/ by default. Then to run the extended tests: 

prove6 -I. xt/
Code

Indeed it is becoming common practice by Raku community developers to place the extensive testing of a distribution in xt/ and to put minimal sanity tests in t/. Extensive testing is essential for development and quality control, but it can slow down the installation of popular distributions.

An alternative to placing the meta-ok test in an extended test directory, but to ensure that it is only run when a developer or maintainer wants to, is to make the test dependent on an environment variable, e.g., in t/99-author-test.rakutest there is the following code 

use Test;

plan 1;

if ?%*ENV<AUTHOR_TESTING> {
    require Test::META <&meta-ok>;
    meta-ok;
    done-testing;
} else {
    skip-rest "Skipping author test";
    exit;
}
Code

Then when the distribution is being tested by the developer, use

    AUTHOR_TESTING=1 prove6 -I.
Code

Non-Core Testing Tools§

Some community modules for testing module quality:

  • Test::META Test your META6.json file
  • Test::Output Test the output to STDOUT and STDERR your program generates
  • Test::Screen Use GNU screen to test full screen VT applications
  • Test::When Control when your tests are run (author testing, online testing, etc.)

See also Distributions: Tools for a general list of module-related tooling.

Documentation about Modules§

Want to distribute your modules?