NAME

Test::Coverage - Check test files for sufficient coverage

SYNOPSIS

# in xt/coverage.rakutest
use Test::Coverage;

coverage-at-least 80;  # ok if at least 80% of lines is covered

uncovered-at-most 10;  # ok if at most 10 lines are not covered

DESCRIPTION

The Test::Coverage distribution provides an easy way for Raku module developers to see whether the test-suite of their module covers as much as possible of the code of their module.

As such it exports subroutines to allow easy checking in a test script that lives in the "xt" directory, so that it will only be run by the author.

Note that as such, this does not add any dependencies to a module, not even for testing as "test-depends" as these tests should only be run by the author in normal circumstances.

By default, all of the test files in the "t" directory, and its subdirectories (extensions .rakutest and .t) will be run against all of the unique files provided by the provides section in the META6.json file.

For convenience, all of the features of the Test module are also exported by this module.

This distribution is really just a thin wrapper around all of the functionality offered by the Code::Coverage module.

SUBROUTINES

coverage-at-least

coverage-at-least 80;  # ok if at least 80% of lines is covered

The coverage-at-least subroutine counts as a single test, and reports a passed test if the percentage of lines covered by the tests in the module reached the given amount (or more).

uncovered-at-most

uncovered-at-most 10;  # ok if at most 10 lines are not covered

The uncovered-at-most subroutine counts as a single test, and reports a passed test if the number of lines not covered by the tests in the module is less then or equal to the number given.

default-coverage-setup

default-coverage-setup;

# run the actual tests and calculate coverage
run;

coverage-at-least 80;  # ok if at least 80% of lines is covered
uncovered-at-most 10;  # ok if at most 10 lines are not covered

The default-coverage-setup subroutine sets up the underlying Code::Coverage object, sets the $*CODE-COVERAGE environment variable with it and returns that.

In most situations this is not needed, as any call to the coverage-at-least and uncovered-at-most subroutines will trigger the setup and running of the tests automatically.

run

my $*CODE-COVERAGE := Code::Coverage.new(...);

run;

# check results

The run subroutine runs the tests and updates any information in the Code::Coverage object that should be available in the $*CODE-COVERAGE environment variable.

It is only needed if some non-standard setup is needed, or if you need to run the tests in a non-standard way:

default-coverage-setup;

run("foo");
run("bar");

# check results

report

report                          # show report if test failed
  unless uncovered-at-most 10;  # ok if at most 10 lines are not covered

The report subroutine will print a report of the coverage tests if called in sink context. It is typically only called if a test fails.

If not in sink context, will return the string of the report:

mail report, :to<coverage@reports.org>;

source-with-coverage

source-with-coverage;  # produce as sibling dir to script

source-with-coverage($dir);

The source-with-coverage subroutine will produce the annotated source of all targets in the given directory (as an IO::Path) with the .rakucov extension. If called without any argument, will assume a directory with the same name (but without extension) as the name of the script.

So e.g. a script in xt/coverage.rakutest in a Foo::Bar distribution would create a directory xt/coverage/Foo and write the annotated source in xt/coverage/Foo/Bar.rakucov.

Note: if you're making use of this feature, it's probably wise to add *.rakucov to the .gitignore file.

AUTHOR

Elizabeth Mattijsen liz@raku.rocks

Source can be located at: https://github.com/lizmat/Test-Coverage . Comments and Pull Requests are welcome.

If you like this module, or what I'm doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.