.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 "Perl::Critic::TestUtils 3pm" .TH Perl::Critic::TestUtils 3pm "2015-08-11" "perl v5.20.2" "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" Perl::Critic::TestUtils \- Utility functions for testing new Policies. .SH "INTERFACE SUPPORT" .IX Header "INTERFACE SUPPORT" This is considered to be a public module. Any changes to its interface will go through a deprecation cycle. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Perl::Critic::TestUtils qw(critique pcritique fcritique); \& \& my $code = \*(Aq< 2 }; \& my $violation_count = critique( \e$code, $perl_critic_config); \& \& # Critique code against one policy... \& my $custom_policy = \*(AqMiscellanea::ProhibitFrobulation\*(Aq \& my $violation_count = pcritique( $custom_policy, \e$code ); \& \& # Critique code against one filename\-related policy... \& my $custom_policy = \*(AqModules::RequireFilenameMatchesPackage\*(Aq \& my $violation_count = fcritique( $custom_policy, \e$code, \*(AqFoo/Bar.pm\*(Aq ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is used by Perl::Critic only for self-testing. It provides a few handy subroutines for testing new Perl::Critic::Policy modules. Look at the test programs that ship with Perl::Critic for more examples of how to use these subroutines. .SH "EXPORTS" .IX Header "EXPORTS" .IP "\fIblock_perlcriticrc()\fR" 4 .IX Item "block_perlcriticrc()" If a user has a \fI~/.perlcriticrc\fR file, this can interfere with testing. This handy method disables the search for that file \*(-- simply call it at the top of your \fI.t\fR program. Note that this is not easily reversible, but that should not matter. .ie n .IP "critique_with_violations( $code_string_ref, $config_ref )" 4 .el .IP "critique_with_violations( \f(CW$code_string_ref\fR, \f(CW$config_ref\fR )" 4 .IX Item "critique_with_violations( $code_string_ref, $config_ref )" Test a block of code against the specified Perl::Critic::Config instance (or \f(CW\*(C`undef\*(C'\fR for the default). Returns the violations that occurred. .ie n .IP "critique( $code_string_ref, $config_ref )" 4 .el .IP "critique( \f(CW$code_string_ref\fR, \f(CW$config_ref\fR )" 4 .IX Item "critique( $code_string_ref, $config_ref )" Test a block of code against the specified Perl::Critic::Config instance (or \f(CW\*(C`undef\*(C'\fR for the default). Returns the number of violations that occurred. .ie n .IP "pcritique_with_violations( $policy_name, $code_string_ref, $config_ref )" 4 .el .IP "pcritique_with_violations( \f(CW$policy_name\fR, \f(CW$code_string_ref\fR, \f(CW$config_ref\fR )" 4 .IX Item "pcritique_with_violations( $policy_name, $code_string_ref, $config_ref )" Like \f(CW\*(C`critique_with_violations()\*(C'\fR, but tests only a single policy instead of the whole bunch. .ie n .IP "pcritique( $policy_name, $code_string_ref, $config_ref )" 4 .el .IP "pcritique( \f(CW$policy_name\fR, \f(CW$code_string_ref\fR, \f(CW$config_ref\fR )" 4 .IX Item "pcritique( $policy_name, $code_string_ref, $config_ref )" Like \f(CW\*(C`critique()\*(C'\fR, but tests only a single policy instead of the whole bunch. .ie n .IP "fcritique_with_violations( $policy_name, $code_string_ref, $filename, $config_ref )" 4 .el .IP "fcritique_with_violations( \f(CW$policy_name\fR, \f(CW$code_string_ref\fR, \f(CW$filename\fR, \f(CW$config_ref\fR )" 4 .IX Item "fcritique_with_violations( $policy_name, $code_string_ref, $filename, $config_ref )" Like \f(CW\*(C`pcritique_with_violations()\*(C'\fR, but pretends that the code was loaded from the specified filename. This is handy for testing policies like \f(CW\*(C`Modules::RequireFilenameMatchesPackage\*(C'\fR which care about the filename that the source derived from. .Sp The \f(CW$filename\fR parameter must be a relative path, not absolute. The file and all necessary subdirectories will be created via File::Temp and will be automatically deleted. .ie n .IP "fcritique( $policy_name, $code_string_ref, $filename, $config_ref )" 4 .el .IP "fcritique( \f(CW$policy_name\fR, \f(CW$code_string_ref\fR, \f(CW$filename\fR, \f(CW$config_ref\fR )" 4 .IX Item "fcritique( $policy_name, $code_string_ref, $filename, $config_ref )" Like \f(CW\*(C`pcritique()\*(C'\fR, but pretends that the code was loaded from the specified filename. This is handy for testing policies like \&\f(CW\*(C`Modules::RequireFilenameMatchesPackage\*(C'\fR which care about the filename that the source derived from. .Sp The \f(CW$filename\fR parameter must be a relative path, not absolute. The file and all necessary subdirectories will be created via File::Temp and will be automatically deleted. .ie n .IP "subtests_in_tree( $dir )" 4 .el .IP "subtests_in_tree( \f(CW$dir\fR )" 4 .IX Item "subtests_in_tree( $dir )" Searches the specified directory recursively for \fI.run\fR files. Each one found is parsed and a hash-of-list-of-hashes is returned. The outer hash is keyed on policy short name, like \&\f(CW\*(C`Modules::RequireEndWithOne\*(C'\fR. The inner hash specifies a single test to be handed to \f(CW\*(C`pcritique()\*(C'\fR or \f(CW\*(C`fcritique()\*(C'\fR, including the code string, test name, etc. See below for the syntax of the \fI.run\fR files. .IP "\fIshould_skip_author_tests()\fR" 4 .IX Item "should_skip_author_tests()" Answers whether author tests should run. .IP "\fIget_author_test_skip_message()\fR" 4 .IX Item "get_author_test_skip_message()" Returns a string containing the message that should be emitted when a test is skipped due to it being an author test when author tests are not enabled. .IP "\fIstarting_points_including_examples()\fR" 4 .IX Item "starting_points_including_examples()" Returns a list of the directories contain code that needs to be tested when it is desired that the examples be included. .IP "\fIbundled_policy_names()\fR" 4 .IX Item "bundled_policy_names()" Returns a list of Policy packages that come bundled with this package. This functions by searching \fI\s-1MANIFEST\s0\fR for \&\fIlib/Perl/Critic/Policy/*.pm\fR and converts the results to package names. .ie n .IP "names_of_policies_willing_to_work( %configuration )" 4 .el .IP "names_of_policies_willing_to_work( \f(CW%configuration\fR )" 4 .IX Item "names_of_policies_willing_to_work( %configuration )" Returns a list of the packages of policies that are willing to function on the current system using the specified configuration. .SH "\fI.run\fP file information" .IX Header ".run file information" Testing a policy follows a very simple pattern: .PP .Vb 6 \& * Policy name \& * Subtest name \& * Optional parameters \& * Number of failures expected \& * Optional exception expected \& * Optional filename for code .Ve .PP Each of the subtests for a policy is collected in a single \fI.run\fR file, with test properties as comments in front of each code block that describes how we expect Perl::Critic to react to the code. For example, say you have a policy called Variables::ProhibitVowels: .PP .Vb 1 \& (In file t/Variables/ProhibitVowels.run) \& \& ## name Basics \& ## failures 1 \& ## cut \& \& my $vrbl_nm = \*(Aqfoo\*(Aq; # Good, vowel\-free name \& my $wango = 12; # Bad, pronouncable name \& \& \& ## name Sometimes Y \& ## failures 1 \& ## cut \& \& my $yllw = 0; # "y" not a vowel here \& my $rhythm = 12; # But here it is .Ve .PP These are called \*(L"subtests\*(R", and two are shown above. The beauty of incorporating multiple subtests in a file is that the \fI.run\fR is itself a (mostly) valid Perl file, and not hidden in a \s-1HEREDOC,\s0 so your editor's color-coding still works, and it is much easier to work with the code and the \s-1POD.\s0 .PP If you need to pass any configuration parameters for your subtest, do so like this: .PP .Vb 1 \& ## parms { allow_y => \*(Aq0\*(Aq } .Ve .PP Note that all the values in this hash must be strings because that's what Perl::Critic will hand you from a \fI.perlcriticrc\fR. .PP If it's a \s-1TODO\s0 subtest (probably because of some weird corner of \s-1PPI\s0 that we exercised that Adam is getting around to fixing, right?), then make a \f(CW\*(C`##TODO\*(C'\fR entry. .PP .Vb 1 \& ## TODO Should pass when PPI 1.xxx comes out .Ve .PP If the code is expected to trigger an exception in the policy, indicate that like so: .PP .Vb 1 \& ## error 1 .Ve .PP If you want to test the error message, mark it with \f(CW\*(C`/.../\*(C'\fR to indicate a \f(CW\*(C`like()\*(C'\fR test: .PP .Vb 1 \& ## error /Can\*(Aqt load Foo::Bar/ .Ve .PP If the policy you are testing cares about the filename of the code, you can indicate that \f(CW\*(C`fcritique\*(C'\fR should be used like so (see \&\f(CW\*(C`fcritique\*(C'\fR for more details): .PP .Vb 1 \& ## filename lib/Foo/Bar.pm .Ve .PP The value of \f(CW\*(C`parms\*(C'\fR will get \f(CW\*(C`eval\*(C'\fRed and passed to \f(CW\*(C`pcritique()\*(C'\fR, so be careful. .PP In general, a subtest document runs from the \f(CW\*(C`## cut\*(C'\fR that starts it to either the next \f(CW\*(C`## name\*(C'\fR or the end of the file. In very rare circumstances you may need to end the test document earlier. A second \f(CW\*(C`## cut\*(C'\fR will do this. The only known need for this is in \&\fIt/Miscellanea/RequireRcsKeywords.run\fR, where it is used to prevent the \s-1RCS\s0 keywords in the file footer from producing false positives or negatives in the last test. .PP Note that nowhere within the \fI.run\fR file itself do you specify the policy that you're testing. That's implicit within the filename. .SH "BUGS AND CAVEATS AND TODO ITEMS" .IX Header "BUGS AND CAVEATS AND TODO ITEMS" Test that we have a t/*/*.run for each lib/*/*.pm .PP Allow us to specify the nature of the failures, and which one. If there are 15 lines of code, and six of them fail, how do we know they're the right six? .SH "AUTHOR" .IX Header "AUTHOR" Chris Dolan and the rest of the Perl::Critic team. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2005\-2011 Chris Dolan. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the \s-1LICENSE\s0 file included with this module.