REQUIREMENTS

• Perl 5.10.0 or greater.

  The latest version of Devel::Cover on which Perl 5.8 was supported was 1.23. Perl versions 5.6.1 and 5.6.2 were not supported after version 1.22. Perl versions 5.6.0 and earlier were never supported. Using Devel::Cover with Perl 5.8.7 was always problematic and frequently lead to crashes.

  Different versions of perl may give slightly different results due to changes in the op tree.

• The ability to compile XS extensions.

  This means a working C compiler and make program at least. If you built perl from source you will have these already and they will be used automatically. If your perl was built in some other way, for example you may have installed it using your Operating System's packaging mechanism, you will need to ensure that the appropriate tools are installed.

• Storable and Digest::MD5

  Both are in the core in Perl 5.8.0 and above.

REQUIRED MODULES

•

B::Debug

This was core before Perl 5.30.0.

OPTIONAL MODULES

• Template, and either PPI::HTML or Perl::Tidy

  Needed if you want syntax highlighted HTML reports.

• Pod::Coverage (0.06 or above) or Pod::Coverage::CountParents

  One is needed if you want Pod coverage. If Pod::Coverage::CountParents is installed, it is preferred.

• Test::More

  Required if you want to run Devel::Cover's own tests.

• Test::Differences

  Needed if the tests fail and you would like nice output telling you why.

• Template and Parallel::Iterator

  Needed if you want to run cpancover.

• JSON::MaybeXS

  JSON is used to store the coverage database if it is available. JSON::MaybeXS will select the best JSON backend installed.

Use with mod_perl

Alternatively, add -MDevel::Cover to the parameters for mod_perl. In this example, Devel::Cover will be operating in silent mode.

 PerlSwitches -MDevel::Cover=-silent,1

More on Coverage Options

Or, to ignore all files in "t/lib" as well as files ending in "Foo.pm":

    cover -test -silent -ignore ^t/lib/,Foo.pm$

Note that "-ignore" replaces any default ignore regexes. To preserve any ignore regexes which have already been set, use "+ignore":

    cover -test -silent +ignore ^t/lib/,Foo.pm$

Invasive specification

 # uncoverable <criterion> [details]

The keyword "uncoverable" must be the first text in the comment. It should be followed by the name of the coverage criterion which is uncoverable. There may then be further information depending on the nature of the uncoverable construct.

Statements

The "uncoverable" comment should appear on either the same line as the statement, or on the line before it:

    $impossible++;  # uncoverable statement
    # uncoverable statement
    it_has_all_gone_horribly_wrong();

If there are multiple statements (or any other criterion) on a line you can specify which statement is uncoverable by using the "count" attribute, count:n, which indicates that the uncoverable statement is the nth statement on the line.

    # uncoverable statement count:1
    # uncoverable statement count:2
    cannot_run_this(); or_this();

Branches

The "uncoverable" comment should specify whether the "true" or "false" branch is uncoverable.

    # uncoverable branch true
    if (pi == 3)

Both branches may be uncoverable:

    # uncoverable branch true
    # uncoverable branch false
    if (impossible_thing_happened_one_way()) {
        handle_it_one_way();      # uncoverable statement
    } else {
        handle_it_another_way();  # uncoverable statement
    }

If there is an elsif in the branch then it can be addressed as the second branch on the line by using the "count" attribute. Further elsifs are the third and fourth "count" value, and so on:

    # uncoverable branch false count:2
    if ($thing == 1) {
        handle_thing_being_one();
    } elsif ($thing == 2) {
        handle_thing_being_tow();
    } else {
        die "thing can only be one or two, not $thing"; # uncoverable statement
    }

Conditions

Because of the way in which Perl short-circuits boolean operations, there are three ways in which such conditionals can be uncoverable. In the case of " $x && $y" for example, the left operator may never be true, the right operator may never be true, and the whole operation may never be false. These conditions may be modelled thus:

    # uncoverable branch true
    # uncoverable condition left
    # uncoverable condition false
    if ($x && !$y) {
        $x++;  # uncoverable statement
    }

    # uncoverable branch true
    # uncoverable condition right
    # uncoverable condition false
    if (!$x && $y) {
    }

"Or" conditionals are handled in a similar fashion (TODO - provide some examples) but "xor" conditionals are not properly handled yet.

As for branches, the "count" value may be used for either conditions in elsif conditionals, or for complex conditions.

Subroutines

A subroutine should be marked as uncoverable at the point where the first statement is marked as uncoverable. Ideally all other criteria in the subroutine would be marked as uncoverable automatically, but that isn't the case at the moment.

    sub z {
        # uncoverable subroutine
        $y++; # uncoverable statement
    }

Non-invasive specification

The interface to managing this file is the cover program, and the options are:

 -uncoverable_file
 -add_uncoverable_point
 -delete_uncoverable_point   **UNIMPLEMENTED**
 -clean_uncoverable_points   **UNIMPLEMENTED**

The parameter for -add_uncoverable_point is a string composed of up to seven space separated elements: "$file $criterion $line $count $type $class $note".

The contents of the uncoverable file is the same, with one point per line.

User variables

Note that when Devel::Cover is invoked via an environment variable, any modules specified on the command line, such as via the -Mmodule option, will not be covered. This is because the environment variables are processed after the command line and any code to be covered must appear after Devel::Cover has been loaded. To work around this, Devel::Cover can also be specified on the command line.

Developer variables

Absence of shared dependencies

 sub foo {
     eval { require Storable };
     if ($@) {
         carp "Can't find Storable";
         return;
     }
     # ...
 }

You might write a test for the failure mode as

 BEGIN { @INC = () }
 foo();
 # check for error message

Because Devel::Cover uses Storable internally, the import will succeed (and the test will fail) under a coverage run.

Modules used by Devel::Cover while gathering coverage:

• B
• B::Debug
• B::Deparse
• Carp
• Cwd
• Digest::MD5
• File::Path
• File::Spec
• Storable or JSON::MaybeXS (and its backend) or Sereal

Redefined subroutines

The module Test::TestCoverage uses this technique and so should not be used in conjunction with Devel::Cover.