Devel::Cover::Collection(3pm)

NAME
Devel::Cover::Collection - Code coverage for a collection of modules

VERSION
version 1.52

SYNOPSIS
  use Devel::Cover::Collection;

  my $collection = Devel::Cover::Collection->new(
    results_dir => "/path/to/results",
    bin_dir     => "/path/to/bin",
    workers     => 4,
    verbose     => 1,
  );

  # Add modules to process
  $collection->add_modules("Some::Module", "Another::Module");

  # Or load from a file
  $collection->set_module_file("/path/to/modules.txt");
  $collection->process_module_file;

  # Run coverage collection
  $collection->cover_modules;

  # Generate HTML reports
  $collection->generate_html;

DESCRIPTION
Devel::Cover::Collection provides infrastructure for running code coverage analysis across a collection of CPAN modules. It is primarily used by the CPANCover service (<http://cpancover.com>) to generate coverage reports for CPAN distributions.

The module supports:

•   Parallel processing of multiple modules

•   Docker-based isolation for coverage runs

•   HTML and JSON report generation

•   Tracking of covered and failed modules

•   Compression of old coverage results

This module requires Perl 5.42.0 or later and uses the builtin "class" feature.

CONSTRUCTOR

  new
  my $collection = Devel::Cover::Collection->new(%options);

Creates a new Collection object. All options are optional and have sensible defaults.

ATTRIBUTES

  Read-Only Attributes
These attributes can only be set via the constructor.

bin_dir

Directory containing the "cover" binary. Used when running coverage commands.

cpancover_dir

Directory for CPANCover-specific files and configuration.

cpan_dir

An arrayref of CPAN directories to search for build directories. Defaults to "~/.cpan" and "~/.local/share/.cpan" if they exist.

results_dir

Directory where coverage results are stored. Required for most operations.

dryrun

Boolean. If true, commands are printed but not executed. Default: 0.

env

Environment identifier (e.g., 'prod', 'dev'). Default: 'prod'.

force

Boolean. If true, re-run coverage even for already-covered modules. Default: 0.

output_file

Filename for the main output file. Default: 'index.html'.

report

Report format to generate. Default: 'html_basic'.

timeout

Timeout in seconds for coverage runs. Default: 1800 (30 minutes).

verbose

Boolean. If true, print additional progress information. Default: 0.

workers

Number of parallel workers for coverage runs. Default: 0 (no parallelism).

docker

Docker command to use. Default: 'docker'.

local

Boolean. If true, run in local mode without Docker. Default: 0.

  Read-Write-Private Attributes
These attributes have public readers but private setters. Use the provided methods to modify them.

build_dirs

Arrayref of build directories to process. Modify via "add_build_dirs".

modules

Arrayref of module names to process. Modify via "add_modules" or "set_modules".

module_file

Path to a file containing module names (one per line). Set via "set_module_file".

  Read-Write Attributes
These attributes can be read and written directly.

dir

  $collection->dir("/path/to/dir");
  my $dir = $collection->dir;

Working directory for the current operation.

file

  $collection->file("/path/to/file");
  my $file = $collection->file;

Current file being processed.

METHODS

  Module Management
add_modules

  $collection->add_modules(@module_names);

Appends modules to the list of modules to process.

set_modules

  $collection->set_modules(@module_names);

Replaces the entire module list with the given modules.

set_module_file

  $collection->set_module_file("/path/to/modules.txt");

Sets the path to a file containing module names.

process_module_file

  $collection->process_module_file;

Reads module names from the file specified by "module_file" and adds them to the modules list. Blank lines and lines starting with "#" are ignored.

  Build Operations
build_modules

  $collection->build_modules;

Builds all modules in the modules list using "cpan -Ti". If "force" is true, uses the "-f" flag.

add_build_dirs

  $collection->add_build_dirs;

Scans the CPAN directories for build directories and adds them to "build_dirs".

local_build

  $collection->local_build;

Orchestrates a complete local build workflow: processes the module file, builds modules, adds build directories, and runs coverage on all.

  Coverage Operations
run

  $collection->run($build_dir);

Runs coverage analysis on a single build directory. Creates coverage reports in the results directory.

run_all

  $collection->run_all;

Runs coverage analysis on all directories in "build_dirs", using parallel workers if configured.

cover_modules

  $collection->cover_modules;

Covers all modules using Docker containers. Processes the module file, then runs coverage for each module in parallel.

  Report Generation
generate_html

  $collection->generate_html;

Generates HTML coverage reports for all modules in the results directory. Creates an index page, per-module pages, and an about page.

coverage_class

  my $css_class = $collection->coverage_class($percentage);

Converts a coverage percentage to a CSS class name for HTML reports:

  n/a     -> "na"
  < 75    -> "c0"
  < 90    -> "c1"
  < 100   -> "c2"
  100     -> "c3"

write_summary

  $collection->write_summary($vars);

Writes the HTML summary pages using Template Toolkit. Called by "generate_html".

write_json

  $collection->write_json($vars);

Writes a JSON file ("cpancover.json") containing coverage data for all modules.

  Status Tracking
is_covered

  if ($collection->is_covered($module_dir)) { ... }

Returns true if coverage results exist for the given module directory.

is_failed

  if ($collection->is_failed($module_dir)) { ... }

Returns true if the module has been marked as failed.

set_covered

  $collection->set_covered($module_dir);

Marks a module as successfully covered (removes any failure marker).

set_failed

  $collection->set_failed($module_dir);

Marks a module as failed by creating a timestamp file in the failed directory.

  Path Methods
made_res_dir

  my ($path, $output) = $collection->made_res_dir;
  my ($path, $output) = $collection->made_res_dir($subdir);

Creates and returns the results directory path. If $subdir is provided, creates that subdirectory within the results directory.

covered_dir

  my $path = $collection->covered_dir($module_dir);

Returns the path where coverage results for a module are stored.

failed_dir

  my $path = $collection->failed_dir;

Returns the path to the directory containing failure markers.

failed_file

  my $path = $collection->failed_file($module_dir);

Returns the path to the failure marker file for a module.

dc_file

  my $path = $collection->dc_file;

Returns the path to the "dc" utility script.

  Maintenance
compress_old_versions

  $collection->compress_old_versions($num_versions_to_keep);

Compresses old coverage results, keeping only the specified number of most recent versions for each module.

get_latest

  $collection->get_latest;

Fetches and prints the latest CPAN release information using CPAN::Releases::Latest.

  System Commands
sys

  my $output = $collection->sys(@command);

Runs a system command, displaying the first portion of output immediately and buffering the rest. Returns the output on success, empty string on failure.

bsys

  my $output = $collection->bsys(@command);

Like "sys", but buffers all output (no immediate display).

fsys

  my $output = $collection->fsys(@command);

Like "sys", but dies on failure.

fbsys

  my $output = $collection->fbsys(@command);

Like "bsys", but dies on failure.

EMBEDDED CLASSES

  Devel::Cover::Collection::Template::Provider
A subclass of Template::Provider that provides built-in templates for HTML report generation. The following templates are available:

•   colours - CSS colour definitions

•   html - Base HTML wrapper

•   summary - Main index page

•   about - About page

•   module_by_start - Module listing by first letter

DEPENDENCIES

•   Perl 5.42.0 or later (for builtin "class" feature)

•   Devel::Cover::DB

•   JSON::MaybeXS

•   Parallel::Iterator

•   Template

•   Time::HiRes

SEE ALSO
Devel::Cover, <http://cpancover.com>

AUTHOR
Paul Johnson <paul@pjcj.net>

LICENCE
Copyright 2014-2026, Paul Johnson (paul@pjcj.net)

This software is free. It is licensed under the same terms as Perl itself.

The latest version of this software should be available on CPAN and from my homepage: <https://pjcj.net/>.