Devel::Cover::Collection(3) User Contributed Perl Documentation 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 () to generate coverage reports for CPAN distributions. The module supports: o Parallel processing of multiple modules o Docker-based isolation for coverage runs o HTML and JSON report generation o Tracking of covered and failed modules o 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: o colours - CSS colour definitions o html - Base HTML wrapper o summary - Main index page o about - About page o module_by_start - Module listing by first letter DEPENDENCIES o Perl 5.42.0 or later (for builtin "class" feature) o Devel::Cover::DB o JSON::MaybeXS o Parallel::Iterator o Template o Time::HiRes SEE ALSO Devel::Cover, AUTHOR Paul Johnson 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: . perl v5.42.0 2026-03-09 Devel::Cover::Collection(3)