Unix/Linux Go Back    


CentOS 7.0 - man page for perl::critic::testutils (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Perl::Critic::TestUtils(3)     User Contributed Perl Documentation     Perl::Critic::TestUtils(3)

NAME
       Perl::Critic::TestUtils - Utility functions for testing new Policies.

INTERFACE SUPPORT
       This is considered to be a public module.  Any changes to its interface will go through a
       deprecation cycle.

SYNOPSIS
	   use Perl::Critic::TestUtils qw(critique pcritique fcritique);

	   my $code = '<<END_CODE';
	   package Foo::Bar;
	   $foo = frobulator();
	   $baz = $foo ** 2;
	   1;
	   END_CODE

	   # Critique code against all loaded policies...
	   my $perl_critic_config = { -severity => 2 };
	   my $violation_count = critique( \$code, $perl_critic_config);

	   # Critique code against one policy...
	   my $custom_policy = 'Miscellanea::ProhibitFrobulation'
	   my $violation_count = pcritique( $custom_policy, \$code );

	   # Critique code against one filename-related policy...
	   my $custom_policy = 'Modules::RequireFilenameMatchesPackage'
	   my $violation_count = fcritique( $custom_policy, \$code, 'Foo/Bar.pm' );

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.

EXPORTS
       block_perlcriticrc()
	   If a user has a ~/.perlcriticrc file, this can interfere with testing.  This handy
	   method disables the search for that file -- simply call it at the top of your .t
	   program.  Note that this is not easily reversible, but that should not matter.

       critique_with_violations( $code_string_ref, $config_ref )
	   Test a block of code against the specified Perl::Critic::Config instance (or "undef"
	   for the default).  Returns the violations that occurred.

       critique( $code_string_ref, $config_ref )
	   Test a block of code against the specified Perl::Critic::Config instance (or "undef"
	   for the default).  Returns the number of violations that occurred.

       pcritique_with_violations( $policy_name, $code_string_ref, $config_ref )
	   Like "critique_with_violations()", but tests only a single policy instead of the whole
	   bunch.

       pcritique( $policy_name, $code_string_ref, $config_ref )
	   Like "critique()", but tests only a single policy instead of the whole bunch.

       fcritique_with_violations( $policy_name, $code_string_ref, $filename, $config_ref )
	   Like "pcritique_with_violations()", but pretends that the code was loaded from the
	   specified filename.	This is handy for testing policies like
	   "Modules::RequireFilenameMatchesPackage" which care about the filename that the source
	   derived from.

	   The $filename 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.

       fcritique( $policy_name, $code_string_ref, $filename, $config_ref )
	   Like "pcritique()", but pretends that the code was loaded from the specified filename.
	   This is handy for testing policies like "Modules::RequireFilenameMatchesPackage" which
	   care about the filename that the source derived from.

	   The $filename 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.

       subtests_in_tree( $dir )
	   Searches the specified directory recursively for .run 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 "Modules::RequireEndWithOne".  The inner hash specifies a single test to be
	   handed to "pcritique()" or "fcritique()", including the code string, test name, etc.
	   See below for the syntax of the .run files.

       should_skip_author_tests()
	   Answers whether author tests should run.

       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.

       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.

       bundled_policy_names()
	   Returns a list of Policy packages that come bundled with this package.  This functions
	   by searching MANIFEST for lib/Perl/Critic/Policy/*.pm and converts the results to
	   package names.

       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.

.run file information
       Testing a policy follows a very simple pattern:

	   * Policy name
	       * Subtest name
	       * Optional parameters
	       * Number of failures expected
	       * Optional exception expected
	       * Optional filename for code

       Each of the subtests for a policy is collected in a single .run 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:

	   (In file t/Variables/ProhibitVowels.run)

	   ## name Basics
	   ## failures 1
	   ## cut

	   my $vrbl_nm = 'foo';    # 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

       These are called "subtests", and two are shown above.  The beauty of incorporating
       multiple subtests in a file is that the .run is itself a (mostly) valid Perl file, and not
       hidden in a HEREDOC, so your editor's color-coding still works, and it is much easier to
       work with the code and the POD.

       If you need to pass any configuration parameters for your subtest, do so like this:

	   ## parms { allow_y => '0' }

       Note that all the values in this hash must be strings because that's what Perl::Critic
       will hand you from a .perlcriticrc.

       If it's a TODO subtest (probably because of some weird corner of PPI that we exercised
       that Adam is getting around to fixing, right?), then make a "##TODO" entry.

	   ## TODO Should pass when PPI 1.xxx comes out

       If the code is expected to trigger an exception in the policy, indicate that like so:

	   ## error 1

       If you want to test the error message, mark it with "/.../" to indicate a "like()" test:

	   ## error /Can't load Foo::Bar/

       If the policy you are testing cares about the filename of the code, you can indicate that
       "fcritique" should be used like so (see "fcritique" for more details):

	   ## filename lib/Foo/Bar.pm

       The value of "parms" will get "eval"ed and passed to "pcritique()", so be careful.

       In general, a subtest document runs from the "## cut" that starts it to either the next
       "## name" or the end of the file. In very rare circumstances you may need to end the test
       document earlier. A second "## cut" will do this. The only known need for this is in
       t/Miscellanea/RequireRcsKeywords.run, where it is used to prevent the RCS keywords in the
       file footer from producing false positives or negatives in the last test.

       Note that nowhere within the .run file itself do you specify the policy that you're
       testing.  That's implicit within the filename.

BUGS AND CAVEATS AND TODO ITEMS
       Test that we have a t/*/*.run for each lib/*/*.pm

       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?

AUTHOR
       Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.

COPYRIGHT
       Copyright (c) 2005-2011 Chris Dolan.

       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 LICENSE file
       included with this module.

perl v5.16.3				    2014-06-09		       Perl::Critic::TestUtils(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:01 PM.