.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Test::Distribution 3pm" .TH Test::Distribution 3pm "2015-12-24" "perl v5.22.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Distribution \- perform tests on all modules of a distribution .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& $ cat t/01distribution.t \& use Test::More; \& \& BEGIN { \& eval { \& require Test::Distribution; \& }; \& if($@) { \& plan skip_all => \*(AqTest::Distribution not installed\*(Aq; \& } \& else { \& import Test::Distribution; \& } \& } \& \& $ make test \& ... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" When using this module in a test script, it goes through all the modules in your distribution, checks their \s-1POD,\s0 checks that they compile ok and checks that they all define a \f(CW$VERSION\fR. .PP This module also performs a numer of test on the distribution itself. It checks that your files match your \s-1SIGNATURE\s0 file if you have one. It checks that your distribution isn't missing certain 'core' description files. It checks to see you havent' missed out listing any pre-requisites in Makefile.PL. .PP It defines its own testing plan, so you usually don't use it in conjunction with other \f(CW\*(C`Test::*\*(C'\fR modules in the same file. It's recommended that you just create a one-line test script as shown in the \&\s-1SYNOPSIS\s0 above. However, there are options... .PP \&\fB\s-1NOTE\s0\fR If you do not specify any options Test::Distribution will run all test types \fBexcept\fR signature testing which must always be explicitly switched on. .PP In the future I may change the default to run no tests at all as this sounds safer. Mail me if you disagree. .SH "OPTIONS" .IX Header "OPTIONS" On the line in which you \f(CW\*(C`use()\*(C'\fR this module, you can specify named arguments that influence the testing behavior. .ie n .IP """tests => NUMBER""" 4 .el .IP "\f(CWtests => NUMBER\fR" 4 .IX Item "tests => NUMBER" Specifies that in addition to the tests run by this module, your test script will run additional tests. In other words, this value influences the test plan. For example: .Sp .Vb 3 \& use Test::Distribution tests => 1; \& use Test::More; \& is($foo, $bar, \*(Aqbaz\*(Aq); .Ve .Sp It is important that you don't specify a \f(CW\*(C`tests\*(C'\fR argument when using \f(CW\*(C`Test::More\*(C'\fR or other test modules as the plan is handled by \&\f(CW\*(C`Test::Distribution\*(C'\fR. .Sp \&\s-1DEPRECATED FEATURE. I\s0 plan to remove this in the future unless I'm contacted by someone that says they find this useful. .ie n .IP """only => STRING|LIST""" 4 .el .IP "\f(CWonly => STRING|LIST\fR" 4 .IX Item "only => STRING|LIST" Specifies that only certain sets of tests are to be run. Possible values are those mentioned in \s-1TEST TYPES\s0 below. For example, if you only want to run the \s-1POD\s0 tests, you could say: .Sp .Vb 1 \& use Test::Distribution only => \*(Aqpod\*(Aq; .Ve .Sp To specify that you only want to run the \s-1POD\s0 tests and the \f(CW\*(C`use\*(C'\fR tests, and also that you are going to run two tests of your own, use: .Sp .Vb 3 \& use Test::Distribution \& only => [ qw/pod use/ ], \& tests => 2; .Ve .Sp Note that when you specify the \f(CW\*(C`versions\*(C'\fR option, the \f(CW\*(C`use\*(C'\fR option is automatically added. This is because in order to get a module's \&\f(CW$VERSION\fR, it has to be loaded. In this case we might as well run a \&\f(CW\*(C`use\*(C'\fR test. .Sp The value for \f(CW\*(C`only\*(C'\fR can be a string or a reference to a list of strings. .ie n .IP """not => STRING|LIST""" 4 .el .IP "\f(CWnot => STRING|LIST\fR" 4 .IX Item "not => STRING|LIST" Specifies that certain types of tests should not be run. All tests not mentioned in this argument are run. For example, if you want to test everything except the \s-1POD,\s0 use: .Sp .Vb 2 \& use Test::Distribution \& not => \*(Aqpod\*(Aq; .Ve .Sp The value for \f(CW\*(C`not\*(C'\fR can be a string or a reference to a list of strings. Although it doesn't seem to make much sense, you can use both \&\f(CW\*(C`only\*(C'\fR and \f(CW\*(C`not\*(C'\fR. In this case only the tests specified in \f(CW\*(C`only\*(C'\fR, but not \f(CW\*(C`not\*(C'\fR are run (if this makes any sense). .ie n .IP """distversion""" 4 .el .IP "\f(CWdistversion\fR" 4 .IX Item "distversion" If you test this to a true value, as well as testing that each module has a \&\f(CW$VERSION\fR defined, Test::Distribution will also ensure that the \f(CW$VERSION\fR matches that of the distribution. .ie n .IP """podcoveropts""" 4 .el .IP "\f(CWpodcoveropts\fR" 4 .IX Item "podcoveropts" You can set this to be a hash reference of options to pass to Test::Pod::Coverage's pod_coverage_ok method (which in turn gets passed to Pod::Coverage. .SH "TEST TYPES" .IX Header "TEST TYPES" Here is a description of the types of tests available. .ie n .IP """description""" 4 .el .IP "\f(CWdescription\fR" 4 .IX Item "description" Checks that the following files exist: .RS 4 .IP "Changes or ChangeLog" 4 .IX Item "Changes or ChangeLog" .PD 0 .IP "\s-1MANIFEST\s0" 4 .IX Item "MANIFEST" .IP "\s-1README\s0" 4 .IX Item "README" .IP "Build.PL or Makefile.PL" 4 .IX Item "Build.PL or Makefile.PL" .RE .RS 4 .RE .ie n .IP """prereq""" 4 .el .IP "\f(CWprereq\fR" 4 .IX Item "prereq" .PD Checks whether all \f(CW\*(C`use()\*(C'\fRd modules that aren't in the perl core are also mentioned in Makefile.PL's \f(CW\*(C`PREREQ_PM\*(C'\fR. .ie n .IP """pod""" 4 .el .IP "\f(CWpod\fR" 4 .IX Item "pod" Checks for \s-1POD\s0 errors in files .ie n .IP """podcover""" 4 .el .IP "\f(CWpodcover\fR" 4 .IX Item "podcover" Checks for Pod Coverage .ie n .IP """sig""" 4 .el .IP "\f(CWsig\fR" 4 .IX Item "sig" If the distribution has a \s-1SIGNATURE \s0 file, checks the \s-1SIGNATURE\s0 matches the files. .ie n .IP """use""" 4 .el .IP "\f(CWuse\fR" 4 .IX Item "use" This \f(CW\*(C`use()\*(C'\fRs the modules to make sure the load happens ok. .ie n .IP """versions""" 4 .el .IP "\f(CWversions\fR" 4 .IX Item "versions" Checks that all packages define \f(CW$VERSION\fR strings. .SH "EXPOSED INTERNALS" .IX Header "EXPOSED INTERNALS" There are a few subroutines to help you see what this module is doing. Note that these subroutines are neither exported nor exportable, so you have to call them fully qualified. .ie n .IP """Test::Distribution::packages()""" 4 .el .IP "\f(CWTest::Distribution::packages()\fR" 4 .IX Item "Test::Distribution::packages()" This is a list of packages that have been found. That is, we assume that each file contains a package of the name indicated by the file's relative position. For example, a file in \f(CW\*(C`blib/lib/Foo/Bar.pm\*(C'\fR is expected to be available via \f(CW\*(C`use Foo::Bar\*(C'\fR. .ie n .IP """Test::Distribution::files()""" 4 .el .IP "\f(CWTest::Distribution::files()\fR" 4 .IX Item "Test::Distribution::files()" This is a list of files that tests have been run on. The filenames are relative to the distribution's root directory, so they start with \&\f(CW\*(C`blib/lib\*(C'\fR. .ie n .IP """Test::Distribution::num_tests()""" 4 .el .IP "\f(CWTest::Distribution::num_tests()\fR" 4 .IX Item "Test::Distribution::num_tests()" This is the number of tests that this module has run, based on your specifications. .SH "INSTALLATION" .IX Header "INSTALLATION" This module uses Module::Build for its installation. To install this module type the following: .PP .Vb 4 \& perl Build.PL \& ./Build \& ./Build test \& ./Build install .Ve .PP If you do not have Module::Build type: .PP .Vb 1 \& perl Makefile.PL .Ve .PP to fetch it. Or use \s-1CPAN\s0 or \s-1CPANPLUS\s0 and fetch it \*(L"manually\*(R". .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" This module requires these other modules and libraries: .PP .Vb 4 \& File::Basename \& File::Find::Rule \& File::Spec \& Test::More .Ve .PP This module has these optional dependencies: .PP .Vb 3 \& Module::CoreList \& Test::Pod \& Test::Pod::Coverage .Ve .PP If \f(CW\*(C`Module::CoreList\*(C'\fR is missing, the \f(CW\*(C`prereq\*(C'\fR tests are skipped. .PP If \f(CW\*(C`Test::Pod\*(C'\fR is missing, the \f(CW\*(C`pod\*(C'\fR tests are skipped. .SH "TODO" .IX Header "TODO" Just because these items are in the todo list, does not mean they will actually be done. If you think one of these would be helpful say so \- and it will then move up on my priority list. .IP "\(bu" 4 Module::Build support [currently waiting for a fix on Test::Prereq ] .SH "FEATURE IDEAS" .IX Header "FEATURE IDEAS" .ie n .IP """export"" test type" 4 .el .IP "\f(CWexport\fR test type" 4 .IX Item "export test type" This would mandate that there should be a test for each exported symbol of each module. .PP Let me know what you think of these ideas. Are they necessary? Unnecessary? Do you have feature requests of your own? .SH "BUGS" .IX Header "BUGS" To report a bug or request an enhancement use \s-1CPAN\s0's excellent Request Tracker. .SH "SOURCE AVAILABILITY" .IX Header "SOURCE AVAILABILITY" This source is part of a SourceForge project which always has the latest sources in svn. .PP http://sourceforge.net/projects/sagar\-r\-shah/ .SH "AUTHORS" .IX Header "AUTHORS" Marcel Gru\*:nauer .PP Sagar R. Shah .SH "OTHER CREDITS" .IX Header "OTHER CREDITS" This module was inspired by a use.perl.org journal entry by \f(CW\*(C`brian d foy\*(C'\fR (see ) where he describes an idea by Andy Lester. .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2002\-2003 Marcel Gru\*:nauer. All rights reserved. .PP Copyright 2003\-2007, Sagar R. Shah, All rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIperl\fR\|(1), \fIExtUtils::Manifest\fR\|(3pm), \fIFile::Find::Rule\fR\|(3pm), \&\fIModule::CoreList\fR\|(3pm), \fITest::More\fR\|(3pm), \fITest::Pod\fR\|(3pm), \&\fITest::Pod::Coverage\fR\|(3pm), \fITest::Signature\fR\|(3pm).