{ "content": [ { "type": "text", "text": "# Devel::Cover (perldoc)\n\n## NAME\n\nDevel::Cover - Code coverage metrics for Perl\n\n## SYNOPSIS\n\nTo get coverage for an uninstalled module:\ncover -test\nor\ncover -delete\nHARNESSPERLSWITCHES=-MDevel::Cover make test\ncover\nTo get coverage for an uninstalled module which uses Module::Build (0.26 or later):\n./Build testcover\nIf the module does not use the t/*.t framework:\nPERL5OPT=-MDevel::Cover make test\nIf you want to get coverage for a program:\nperl -MDevel::Cover yourprog args\ncover\nTo alter default values:\nperl -MDevel::Cover=-db,coverdb,-coverage,statement,time yourprog args\n\n## DESCRIPTION\n\nThis module provides code coverage metrics for Perl. Code coverage metrics describe how\nthoroughly tests exercise code. By using Devel::Cover you can discover areas of code not\nexercised by your tests and determine which tests to create to increase coverage. Code coverage\ncan be considered an indirect measure of quality.\n\n## Sections\n\n- **NAME**\n- **VERSION**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **REQUIREMENTS AND RECOMMENDED MODULES** (1 subsections)\n- **OPTIONS** (1 subsections)\n- **SELECTING FILES TO COVER**\n- **UNCOVERABLE CRITERIA** (4 subsections)\n- **ENVIRONMENT** (2 subsections)\n- **ACKNOWLEDGEMENTS**\n- **SEE ALSO**\n- **LIMITATIONS** (2 subsections)\n- **BUGS**\n- **LICENCE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Devel::Cover", "section": "", "mode": "perldoc", "summary": "Devel::Cover - Code coverage metrics for Perl", "synopsis": "To get coverage for an uninstalled module:\ncover -test\nor\ncover -delete\nHARNESSPERLSWITCHES=-MDevel::Cover make test\ncover\nTo get coverage for an uninstalled module which uses Module::Build (0.26 or later):\n./Build testcover\nIf the module does not use the t/*.t framework:\nPERL5OPT=-MDevel::Cover make test\nIf you want to get coverage for a program:\nperl -MDevel::Cover yourprog args\ncover\nTo alter default values:\nperl -MDevel::Cover=-db,coverdb,-coverage,statement,time yourprog args", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 27, "subsections": [] }, { "name": "DESCRIPTION", "lines": 41, "subsections": [] }, { "name": "REQUIREMENTS AND RECOMMENDED MODULES", "lines": 54, "subsections": [ { "name": "Use with modperl", "lines": 10 } ] }, { "name": "OPTIONS", "lines": 24, "subsections": [ { "name": "More on Coverage Options", "lines": 15 } ] }, { "name": "SELECTING FILES TO COVER", "lines": 25, "subsections": [] }, { "name": "UNCOVERABLE CRITERIA", "lines": 17, "subsections": [ { "name": "Invasive specification", "lines": 88 }, { "name": "Non-invasive specification", "lines": 7 }, { "name": "-uncoverable_file", "lines": 1 }, { "name": "-add_uncoverable_point", "lines": 8 } ] }, { "name": "ENVIRONMENT", "lines": 1, "subsections": [ { "name": "User variables", "lines": 10 }, { "name": "Developer variables", "lines": 10 } ] }, { "name": "ACKNOWLEDGEMENTS", "lines": 8, "subsections": [] }, { "name": "SEE ALSO", "lines": 6, "subsections": [] }, { "name": "LIMITATIONS", "lines": 2, "subsections": [ { "name": "Absence of shared dependencies", "lines": 43 }, { "name": "Redefined subroutines", "lines": 7 } ] }, { "name": "BUGS", "lines": 8, "subsections": [] }, { "name": "LICENCE", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "Devel::Cover - Code coverage metrics for Perl\n", "subsections": [] }, "VERSION": { "content": "version 1.36\n", "subsections": [] }, "SYNOPSIS": { "content": "To get coverage for an uninstalled module:\n\ncover -test\n\nor\n\ncover -delete\nHARNESSPERLSWITCHES=-MDevel::Cover make test\ncover\n\nTo get coverage for an uninstalled module which uses Module::Build (0.26 or later):\n\n./Build testcover\n\nIf the module does not use the t/*.t framework:\n\nPERL5OPT=-MDevel::Cover make test\n\nIf you want to get coverage for a program:\n\nperl -MDevel::Cover yourprog args\ncover\n\nTo alter default values:\n\nperl -MDevel::Cover=-db,coverdb,-coverage,statement,time yourprog args\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides code coverage metrics for Perl. Code coverage metrics describe how\nthoroughly tests exercise code. By using Devel::Cover you can discover areas of code not\nexercised by your tests and determine which tests to create to increase coverage. Code coverage\ncan be considered an indirect measure of quality.\n\nAlthough it is still being developed, Devel::Cover is now quite stable and provides many of the\nfeatures to be expected in a useful coverage tool.\n\nStatement, branch, condition, subroutine, and pod coverage information is reported. Statement\nand subroutine coverage data should be accurate. Branch and condition coverage data should be\nmostly accurate too, although not always what one might initially expect. Pod coverage comes\nfrom Pod::Coverage. If Pod::Coverage::CountParents is available it will be used instead.\nCoverage data for other criteria are not yet collected.\n\nThe cover program can be used to generate coverage reports. Devel::Cover ships with a number of\nreports including various types of HTML output, textual reports, a report to display missing\ncoverage in the same format as compilation errors and a report to display coverage information\nwithin the Vim editor.\n\nIt is possible to add annotations to reports, for example you can add a column to an HTML report\nshowing who last changed a line, as determined by git blame. Some annotation modules are shipped\nwith Devel::Cover and you can easily create your own.\n\nThe gcov2perl program can be used to convert gcov files to \"Devel::Cover\" databases. This allows\nyou to display your C or XS code coverage together with your Perl coverage, or to use any of the\nDevel::Cover reports to display your C coverage data.\n\nCode coverage data are collected by replacing perl ops with functions which count how many times\nthe ops are executed. These data are then mapped back to reality using the B compiler modules.\nThere is also a statement profiling facility which should not be relied on. For proper profiling\nuse Devel::NYTProf. Previous versions of Devel::Cover collected coverage data by replacing\nperl's runops function. It is still possible to switch to that mode of operation, but this now\ngets little testing and will probably be removed soon. You probably don't care about any of\nthis.\n\nThe most appropriate mailing list on which to discuss this module would be perl-qa. See\n.\n\nThe Devel::Cover repository can be found at . This is also\nwhere problems should be reported.\n", "subsections": [] }, "REQUIREMENTS AND RECOMMENDED MODULES": { "content": "REQUIREMENTS\n* Perl 5.10.0 or greater.\n\nThe latest version of Devel::Cover on which Perl 5.8 was supported was 1.23. Perl versions\n5.6.1 and 5.6.2 were not supported after version 1.22. Perl versions 5.6.0 and earlier were\nnever supported. Using Devel::Cover with Perl 5.8.7 was always problematic and frequently\nlead to crashes.\n\nDifferent versions of perl may give slightly different results due to changes in the op\ntree.\n\n* The ability to compile XS extensions.\n\nThis means a working C compiler and make program at least. If you built perl from source you\nwill have these already and they will be used automatically. If your perl was built in some\nother way, for example you may have installed it using your Operating System's packaging\nmechanism, you will need to ensure that the appropriate tools are installed.\n\n* Storable and Digest::MD5\n\nBoth are in the core in Perl 5.8.0 and above.\n\nREQUIRED MODULES\n* B::Debug\n\nThis was core before Perl 5.30.0.\n\nOPTIONAL MODULES\n* Template, and either PPI::HTML or Perl::Tidy\n\nNeeded if you want syntax highlighted HTML reports.\n\n* Pod::Coverage (0.06 or above) or Pod::Coverage::CountParents\n\nOne is needed if you want Pod coverage. If Pod::Coverage::CountParents is installed, it is\npreferred.\n\n* Test::More\n\nRequired if you want to run Devel::Cover's own tests.\n\n* Test::Differences\n\nNeeded if the tests fail and you would like nice output telling you why.\n\n* Template and Parallel::Iterator\n\nNeeded if you want to run cpancover.\n\n* JSON::MaybeXS\n\nJSON is used to store the coverage database if it is available. JSON::MaybeXS will select\nthe best JSON backend installed.\n", "subsections": [ { "name": "Use with modperl", "content": "By adding \"use Devel::Cover;\" to your modperl startup script, you should be able to collect\ncoverage information when running under modperl. You can also add any options you need at this\npoint. I would suggest adding this as early as possible in your startup script in order to\ncollect as much coverage information as possible.\n\nAlternatively, add -MDevel::Cover to the parameters for modperl. In this example, Devel::Cover\nwill be operating in silent mode.\n\nPerlSwitches -MDevel::Cover=-silent,1\n" } ] }, "OPTIONS": { "content": "-blib - \"use blib\" and ignore files matching \\bt/ (default true\nif blib directory exists, false otherwise)\n-coverage criterion - Turn on coverage for the specified criterion. Criteria\ninclude statement, branch, condition, path, subroutine,\npod, time, all and none (default all available)\n-db coverdb - Store results in coverage db (default ./coverdb)\n-dir path - Directory in which coverage will be collected (default\ncwd)\n-ignore RE - Set regular expressions for files to ignore (default\n\"/Devel/Cover\\b\")\n+ignore RE - Append to regular expressions of files to ignore\n-inc path - Set prefixes of files to include (default @INC)\n+inc path - Append to prefixes of files to include\n-looseperms val - Use loose permissions on all files and directories in\nthe coverage db so that code changing EUID can still\nwrite coverage information (default off)\n-merge val - Merge databases, for multiple test benches (default on)\n-select RE - Set regular expressions of files to select (default none)\n+select RE - Append to regular expressions of files to select\n-silent val - Don't print informational messages (default off)\n-subsonly val - Only cover code in subroutine bodies (default off)\n-replaceops val - Use op replacing rather than runops (default on)\n-summary val - Print summary information if val is true (default on)\n", "subsections": [ { "name": "More on Coverage Options", "content": "You can specify options to some coverage criteria. At the moment only pod coverage takes any\noptions. These are the parameters which are passed into the Pod::Coverage constructor. The extra\noptions are separated by dashes, and you may specify as many as you wish. For example, to\nspecify that all subroutines containing xx are private, call Devel::Cover with the option\n-coverage,pod-alsoprivate-xx.\n\nOr, to ignore all files in \"t/lib\" as well as files ending in \"Foo.pm\":\n\ncover -test -silent -ignore ^t/lib/,Foo.pm$\n\nNote that \"-ignore\" replaces any default ignore regexes. To preserve any ignore regexes which\nhave already been set, use \"+ignore\":\n\ncover -test -silent +ignore ^t/lib/,Foo.pm$\n" } ] }, "SELECTING FILES TO COVER": { "content": "You may select the files for which you want to collect coverage data using the select, ignore\nand inc options. The system uses the following procedure to decide whether a file will be\nincluded in coverage reports:\n\n* If the file matches a RE given as a select option, it will be included\n\n* Otherwise, if it matches a RE given as an ignore option, it won't be included\n\n* Otherwise, if it is in one of the inc directories, it won't be included\n\n* Otherwise, it will be included\n\nYou may add to the REs to select by using +select, or you may reset the selections using\n-select. The same principle applies to the REs to ignore.\n\nThe inc directories are initially populated with the contents of perl's @INC array. You may\nreset these directories using -inc, or add to them using +inc.\n\nAlthough these options take regular expressions, you should not enclose the RE within // or any\nother quoting characters.\n\nThe options -coverage, [+-]select, [+-]ignore and [+-]inc can be specified multiple times, but\nthey can also take multiple comma separated arguments. In any case you should not add a space\nafter the comma, unless you want the argument to start with that literal space.\n", "subsections": [] }, "UNCOVERABLE CRITERIA": { "content": "Sometimes you have code which is uncoverable for some reason. Perhaps it is an else clause that\ncannot be reached, or a check for an error condition that should never happen. You can tell\nDevel::Cover that certain criteria are uncoverable and then they are not counted as errors when\nthey are not exercised. In fact, they are counted as errors if they are exercised.\n\nThis feature should only be used as something of a last resort. Ideally you would find some way\nof exercising all your code. But if you have analysed your code and determined that you are not\ngoing to be able to exercise it, it may be better to record that fact in some formal fashion and\nstop Devel::Cover complaining about it, so that real problems are not lost in the noise.\n\nIf you have uncoverable criteria I suggest not using the default HTML report (with uses\nhtmlminimal at the moment) because this sometimes shows uncoverable points as uncovered.\nInstead, you should use the htmlbasic report for HTML output which should behave correctly in\nthis regard.\n\nThere are two ways to specify a construct as uncoverable, one invasive and one non-invasive.\n", "subsections": [ { "name": "Invasive specification", "content": "You can use special comments in your code to specify uncoverable criteria. Comments are of the\nform:\n\n# uncoverable [details]\n\nThe keyword \"uncoverable\" must be the first text in the comment. It should be followed by the\nname of the coverage criterion which is uncoverable. There may then be further information\ndepending on the nature of the uncoverable construct.\n\nStatements\nThe \"uncoverable\" comment should appear on either the same line as the statement, or on the line\nbefore it:\n\n$impossible++; # uncoverable statement\n# uncoverable statement\nithasallgonehorriblywrong();\n\nIf there are multiple statements (or any other criterion) on a line you can specify which\nstatement is uncoverable by using the \"count\" attribute, count:n, which indicates that the\nuncoverable statement is the nth statement on the line.\n\n# uncoverable statement count:1\n# uncoverable statement count:2\ncannotrunthis(); orthis();\n\nBranches\nThe \"uncoverable\" comment should specify whether the \"true\" or \"false\" branch is uncoverable.\n\n# uncoverable branch true\nif (pi == 3)\n\nBoth branches may be uncoverable:\n\n# uncoverable branch true\n# uncoverable branch false\nif (impossiblethinghappenedoneway()) {\nhandleitoneway(); # uncoverable statement\n} else {\nhandleitanotherway(); # uncoverable statement\n}\n\nIf there is an elsif in the branch then it can be addressed as the second branch on the line by\nusing the \"count\" attribute. Further elsifs are the third and fourth \"count\" value, and so on:\n\n# uncoverable branch false count:2\nif ($thing == 1) {\nhandlethingbeingone();\n} elsif ($thing == 2) {\nhandlethingbeingtow();\n} else {\ndie \"thing can only be one or two, not $thing\"; # uncoverable statement\n}\n\nConditions\nBecause of the way in which Perl short-circuits boolean operations, there are three ways in\nwhich such conditionals can be uncoverable. In the case of \" $x && $y\" for example, the left\noperator may never be true, the right operator may never be true, and the whole operation may\nnever be false. These conditions may be modelled thus:\n\n# uncoverable branch true\n# uncoverable condition left\n# uncoverable condition false\nif ($x && !$y) {\n$x++; # uncoverable statement\n}\n\n# uncoverable branch true\n# uncoverable condition right\n# uncoverable condition false\nif (!$x && $y) {\n}\n\n\"Or\" conditionals are handled in a similar fashion (TODO - provide some examples) but \"xor\"\nconditionals are not properly handled yet.\n\nAs for branches, the \"count\" value may be used for either conditions in elsif conditionals, or\nfor complex conditions.\n\nSubroutines\nA subroutine should be marked as uncoverable at the point where the first statement is marked as\nuncoverable. Ideally all other criteria in the subroutine would be marked as uncoverable\nautomatically, but that isn't the case at the moment.\n\nsub z {\n# uncoverable subroutine\n$y++; # uncoverable statement\n}\n" }, { "name": "Non-invasive specification", "content": "If you can't, or don't want to add coverage comments to your code, you can specify the\nuncoverable information in a separate file. By default the files PWD/.uncoverable and\nHOME/.uncoverable are checked. If you use the -uncoverablefile parameter then the file you\nprovide is checked as well as those two files.\n\nThe interface to managing this file is the cover program, and the options are:\n" }, { "name": "-uncoverable_file", "content": "" }, { "name": "-add_uncoverable_point", "content": "-deleteuncoverablepoint UNIMPLEMENTED\n-cleanuncoverablepoints UNIMPLEMENTED\n\nThe parameter for -adduncoverablepoint is a string composed of up to seven space separated\nelements: \"$file $criterion $line $count $type $class $note\".\n\nThe contents of the uncoverable file is the same, with one point per line.\n" } ] }, "ENVIRONMENT": { "content": "", "subsections": [ { "name": "User variables", "content": "The -silent option is turned on when Devel::Cover is invoked via $HARNESSPERLSWITCHES or\n$PERL5OPT. Devel::Cover tries to do the right thing when $MODPERL is set. $DEVELCOVEROPTIONS\nis appended to any options passed into Devel::Cover.\n\nNote that when Devel::Cover is invoked via an environment variable, any modules specified on the\ncommand line, such as via the -Mmodule option, will not be covered. This is because the\nenvironment variables are processed after the command line and any code to be covered must\nappear after Devel::Cover has been loaded. To work around this, Devel::Cover can also be\nspecified on the command line.\n" }, { "name": "Developer variables", "content": "When running Devel::Cover's own test suite, $DEVELCOVERDEBUG turns on debugging information,\n$DEVELCOVERGOLDENVERSION overrides Devel::Cover's own idea of which golden results it should\ntest against, and $DEVELCOVERNOCOVERAGE runs the tests without collecting coverage.\n$DEVELCOVERDBFORMAT may be set to \"Sereal\", \"JSON\" or \"Storable\" to override the default\nchoice of DB format (Sereal, then JSON if either are available, otherwise Storable).\n$DEVELCOVERIOOPTIONS provides fine-grained control over the DB format. For example, setting\nit to \"pretty\" when the format is JSON will store the DB in a readable JSON format.\n$DEVELCOVERCPUS overrides the automated detection of the number of CPUs to use in parallel\ntesting.\n" } ] }, "ACKNOWLEDGEMENTS": { "content": "Some code and ideas cribbed from:\n\n* Devel::OpProf\n\n* B::Concise\n\n* B::Deparse\n", "subsections": [] }, "SEE ALSO": { "content": "* Devel::Cover::Tutorial\n\n* B\n\n* Pod::Coverage\n", "subsections": [] }, "LIMITATIONS": { "content": "There are things that Devel::Cover can't cover.\n", "subsections": [ { "name": "Absence of shared dependencies", "content": "Perl keeps track of which modules have been loaded (to avoid reloading them). Because of this,\nit isn't possible to get coverage for a path where a runtime import fails if the module being\nimported is one that Devel::Cover uses internally. For example, suppose your program has this\nfunction:\n\nsub foo {\neval { require Storable };\nif ($@) {\ncarp \"Can't find Storable\";\nreturn;\n}\n# ...\n}\n\nYou might write a test for the failure mode as\n\nBEGIN { @INC = () }\nfoo();\n# check for error message\n\nBecause Devel::Cover uses Storable internally, the import will succeed (and the test will fail)\nunder a coverage run.\n\nModules used by Devel::Cover while gathering coverage:\n\n* B\n\n* B::Debug\n\n* B::Deparse\n\n* Carp\n\n* Cwd\n\n* Digest::MD5\n\n* File::Path\n\n* File::Spec\n\n* Storable or JSON::MaybeXS (and its backend) or Sereal\n" }, { "name": "Redefined subroutines", "content": "If you redefine a subroutine you may find that the original subroutine is not reported on. This\nis because I haven't yet found a way to locate the original CV. Hints, tips or patches to\nresolve this will be gladly accepted.\n\nThe module Test::TestCoverage uses this technique and so should not be used in conjunction with\nDevel::Cover.\n" } ] }, "BUGS": { "content": "Almost certainly.\n\nSee the BUGS file, the TODO file and the bug trackers at\n and\n\n\nPlease report new bugs on Github.\n", "subsections": [] }, "LICENCE": { "content": "Copyright 2001-2019, Paul Johnson (paul@pjcj.net)\n\nThis software is free. It is licensed under the same terms as Perl itself.\n\nThe latest version of this software should be available on CPAN and from my homepage:\nhttp://www.pjcj.net/.\n", "subsections": [] } } } }