REQUIREMENTS¶

• Perl 5.6.1 or greater. Perl 5.8.8 or greater is recommended.

  Perl 5.7 is unsupported. Perl 5.8.8 or greater is recommended. Perl 5.8.7 has problems and may crash. Whilst Perl 5.6 should mostly work you will probably miss out on coverage information which would be available using a more modern version and will likely run into bugs in perl. Devel::Cover support for unsupported Perl versions may be removed at any time, but I try to keep older versions running provided this does not cause undue difficulty i other areas.

  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.

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::Warn

  Some of Devel::Cover's own tests require it.

• 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, JSON::PP or JSON::XS

  JSON is used to store the coverage database if it is available.

Use with mod_perl¶

By adding "use Devel::Cover;" to your mod_perl startup script, you should be able to collect coverage information when running under mod_perl. You can also add any options you need at this point. I would suggest adding this as early as possible in your startup script in order to collect as much coverage information as possible.

More on Coverage Options¶

You can specify options to some coverage criteria. At the moment only pod coverage takes any options. These are the parameters which are passed into the Pod::Coverage constructor. The extra options are separated by dashes, and you may specify as many as you wish. For example, to specify that all subroutines containing xx are private, call Devel::Cover with the option -coverage,pod-also_private-xx.

Invasive specification¶

You can use special comments in your code to specify uncoverable criteria. Comments are of the form:

 # 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, of 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
    }

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.

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¶

If you can't, or don't want to add coverage comments to your code, you can specify the uncoverable information in a separate file. My default this file is .uncoverable but you can override that.

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

 -uncoverable_file
 -add_uncoverable_point
 -delete_uncoverable_point
 -clean_uncoverable_points

Of these, only the first two are implemented at the moment. The parameter for -add_uncoverable_point is a string composed of up to seven space separated elements: "$file $criterion $line $count $type $class $note".

TODO - more information and examples.

User variables¶

The -silent option is turned on when Devel::Cover is invoked via $HARNESS_PERL_SWITCHES or $PERL5OPT. Devel::Cover tries to do the right thing when $MOD_PERL is set. $DEVEL_COVER_OPTIONS is appended to any options passed into Devel::Cover.

Developer variables¶

When running Devel::Cover's own test suite, $DEVEL_COVER_DEBUG turns on debugging information, $DEVEL_COVER_GOLDEN_VERSION overrides Devel::Cover's own idea of which golden results it should test against, and $DEVEL_COVER_NO_COVERAGE runs the tests without collecting coverage. $DEVEL_COVER_DB_FORMAT may be set to either "JSON" or "Storable" to override the default choice of DB format (JSON if available, otherwise Storable). $DEVEL_COVER_IO_OPTIONS provides fine-grained control over the DB format. For example, setting it to "pretty" when the format is JSON will store the DB in a readable JSON format.

Absence of shared dependencies¶

Perl keeps track of which modules have been loaded (to avoid reloading them). Because of this, it isn't possible to get coverage for a path where a runtime import fails if the module being imported is one that Devel::Cover uses internally. For example, suppose your program has this function:

 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

Redefined subroutines¶

If you redefine a subroutine you may find that the original subroutine is not reported on. This is because I haven't yet found a way to locate the original CV. Hints, tips or patches to resolve this will be gladly accepted.