Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::Perl::Critic(3) User Contributed Perl DocumentationTest::Perl::Critic(3)

NAME
       Test::Perl::Critic - Use	Perl::Critic in	test programs

SYNOPSIS
       Test one	file:

	 use Test::Perl::Critic;
	 use Test::More	tests => 1;
	 critic_ok($file);

       Or test all files in one	or more	directories:

	 use Test::Perl::Critic;
	 all_critic_ok($dir_1, $dir_2, $dir_N );

       Or test all files in a distribution:

	 use Test::Perl::Critic;
	 all_critic_ok();

       Recommended usage for CPAN distributions:

	 use strict;
	 use warnings;
	 use File::Spec;
	 use Test::More;
	 use English qw(-no_match_vars);

	 if ( not $ENV{TEST_AUTHOR} ) {
	     my	$msg = 'Author test.  Set $ENV{TEST_AUTHOR} to a true value to run.';
	     plan( skip_all => $msg );
	 }

	 eval {	require	Test::Perl::Critic; };

	 if ( $EVAL_ERROR ) {
	    my $msg = 'Test::Perl::Critic required to criticise	code';
	    plan( skip_all => $msg );
	 }

	 my $rcfile = File::Spec->catfile( 't',	'perlcriticrc' );
	 Test::Perl::Critic->import( -profile => $rcfile );
	 all_critic_ok();

DESCRIPTION
       Test::Perl::Critic wraps	the Perl::Critic engine	in a convenient
       subroutine suitable for test programs written using the Test::More
       framework.  This	makes it easy to integrate coding-standards
       enforcement into	the build process.  For	ultimate convenience (at the
       expense of some flexibility), see the criticism pragma.

       If you have an large existing code base,	you might prefer to use
       Test::Perl::Critic::Progressive,	which allows you to clean your code
       incrementally instead of	all at once..

       If you'd	like to	try Perl::Critic without installing anything, there is
       a web-service available at <http://perlcritic.com>.  The	web-service
       does not	support	all the	configuration features that are	available in
       the native Perl::Critic API, but	it should give you a good idea of what
       Perl::Critic can	do.

SUBROUTINES
       all_critic_ok( [	@FILES ] )
	   Runs	"critic_ok()" for all Perl files in the	list of	@FILES.	If a
	   file	is actually a directory, then all Perl files beneath that
	   directory (recursively) will	be run through "critic_ok()". If
	   @FILES is empty or not given, then the blib/	is used	if it exists,
	   and if not, then lib/ is used. Returns true if all files are	okay,
	   or false if any file	fails.

	   This	subroutine emits its own test plan, so you do not need to
	   specify the expected	number of tests	or call	"done_testing()".
	   Therefore, "all_critic_ok" generally	cannot be used in a test
	   script that includes	other sorts of tests.

	   all_critic_ok() is also optimized to	run tests in parallel over
	   multiple cores (if you have them) so	it is usually better to	call
	   this	function than calling critic_ok() directly.

       critic_ok( $FILE	[, $TEST_NAME ]	)
	   Okays the test if Perl::Critic does not find	any violations in
	   $FILE.  If it does, the violations will be reported in the test
	   diagnostics.	 The optional second argument is the name of test,
	   which defaults to "Perl::Critic test	for $FILE".

	   If you use this form, you should load Test::More and	emit your own
	   test	plan first or call "done_testing()" afterwards.

CONFIGURATION
       Perl::Critic is highly configurable.  By	default, Test::Perl::Critic
       invokes Perl::Critic with its default configuration.  But if you	have
       developed your code against a custom Perl::Critic configuration,	you
       will want to configure Test::Perl::Critic to do the same.

       Any arguments passed through the	"use" pragma (or via
       "Test::Perl::Critic->import()" )will be passed into the Perl::Critic
       constructor.  So	if you have developed your code	using a	custom
       ~/.perlcriticrc file, you can direct Test::Perl::Critic to use your
       custom file too.

	 use Test::Perl::Critic	(-profile => 't/perlcriticrc');
	 all_critic_ok();

       Now place a copy	of your	own ~/.perlcriticrc file in the	distribution
       as t/perlcriticrc.  Then, "critic_ok()" will be run on all Perl files
       in this distribution using this same Perl::Critic configuration.	 See
       the Perl::Critic	documentation for details on the .perlcriticrc file
       format.

       Any argument that is supported by the Perl::Critic constructor can be
       passed through this interface.  For example, you	can also set the
       minimum severity	level, or include & exclude specific policies like
       this:

	 use Test::Perl::Critic	(-severity => 2, -exclude => ['RequireRcsKeywords']);
	 all_critic_ok();

       See the Perl::Critic documentation for complete details on its options
       and arguments.

DIAGNOSTIC DETAILS
       By default, Test::Perl::Critic displays basic information about each
       Policy violation	in the diagnostic output of the	test.  You can
       customize the format and	content	of this	information by using the
       "-verbose" option.  This	behaves	exactly	like the "-verbose" switch on
       the perlcritic program.	For example:

	 use Test::Perl::Critic	(-verbose => 6);

	 #or...

	 use Test::Perl::Critic	(-verbose => '%f: %m at	%l');

       If given	a number, Test::Perl::Critic reports violations	using one of
       the predefined formats described	below. If given	a string, it is
       interpreted to be an actual format specification. If the	"-verbose"
       option is not specified,	it defaults to 3.

	   Verbosity	 Format	Specification
	   -----------	 -------------------------------------------------------
	    1		 "%f:%l:%c:%m\n",
	    2		 "%f: (%l:%c) %m\n",
	    3		 "%m at	%f line	%l\n",
	    4		 "%m at	line %l, column	%c.  %e.  (Severity: %s)\n",
	    5		 "%f: %m at line %l, column %c.	 %e.  (Severity: %s)\n",
	    6		 "%m at	line %l, near '%r'.  (Severity:	%s)\n",
	    7		 "%f: %m at line %l near '%r'.	(Severity: %s)\n",
	    8		 "[%p] %m at line %l, column %c.  (Severity: %s)\n",
	    9		 "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
	   10		 "%m at	line %l, column	%c.\n  %p (Severity: %s)\n%d\n",
	   11		 "%m at	line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"

       Formats are a combination of literal and	escape characters similar to
       the way "sprintf" works.	See String::Format for a full explanation of
       the formatting capabilities. Valid escape characters are:

	   Escape    Meaning
	   -------   ----------------------------------------------------------------
	   %c	     Column number where the violation occurred
	   %d	     Full diagnostic discussion	of the violation (DESCRIPTION in POD)
	   %e	     Explanation of violation or page numbers in PBP
	   %F	     Just the name of the logical file where the violation occurred.
	   %f	     Path to the logical file where the	violation occurred.
	   %G	     Just the name of the physical file	where the violation occurred.
	   %g	     Path to the physical file where the violation occurred.
	   %l	     Logical line number where the violation occurred
	   %L	     Physical line number where	the violation occurred
	   %m	     Brief description of the violation
	   %P	     Full name of the Policy module that created the violation
	   %p	     Name of the Policy	without	the Perl::Critic::Policy:: prefix
	   %r	     The string	of source code that caused the violation
	   %C	     The class of the PPI::Element that	caused the violation
	   %s	     The severity level	of the violation

CAVEATS
       Despite the convenience of using	a test script to enforce your coding
       standards, there	are some inherent risks	when distributing those	tests
       to others.  Since you don't know	which version of Perl::Critic the end-
       user has	and whether they have installed	any additional Policy modules,
       you can't really	be sure	that your code will pass the
       Test::Perl::Critic tests	on another machine.

       For these reasons, we strongly advise you to make your perlcritic tests
       optional, or exclude them from the distribution entirely.

       The recommended usage in	the "SYNOPSIS" section illustrates one way to
       make your perlcritic.t test optional.  Another option is	to put
       perlcritic.t and	other author-only tests	in a separate directory	(xt/
       seems to	be common), and	then use a custom build	action when you	want
       to run them.  Also, you should not list Test::Perl::Critic as a
       requirement in your build script.  These	tests are only relevant	to the
       author and should not be	a prerequisite for end-use.

       See <http://chrisdolan.net/talk/2005/11/14/private-regression-tests/>
       for an interesting discussion about Test::Perl::Critic and other	types
       of author-only regression tests.

FOR Dist::Zilla	USERS
       If you use Test::Perl::Critic with Dist::Zilla, beware that some	DZ
       plugins may mutate your code in ways that are not compliant with	your
       Perl::Critic rules. In particular, the standard
       Dist::Zilla::Plugin::PkgVersion will inject a $VERSION declaration at
       the top of the file, which will violate
       Perl::Critic::Policy::TestingAndDebughgin::RequireUseStrict. One
       solution	is to use the Dist::Zilla::Plugin::OurPkgVersion which allows
       you to control where the	$VERSION declaration appears.

EXPORTS
	 critic_ok()
	 all_critic_ok()

BUGS
       If you find any bugs, please submit them	to
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>.	Thanks.

SEE ALSO
       Module::Starter::PBP

       Perl::Critic

       Test::More

CREDITS
       Andy Lester, whose Test::Pod module provided most of the	code and
       documentation for Test::Perl::Critic.  Thanks, Andy.

AUTHOR
       Jeffrey Ryan Thalhammer <jeff@thaljef.org>

COPYRIGHT
       Copyright (c) 2005-2014 Jeffrey Ryan Thalhammer.

       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.24.1			  2017-07-02		 Test::Perl::Critic(3)

NAME | SYNOPSIS | DESCRIPTION | SUBROUTINES | CONFIGURATION | DIAGNOSTIC DETAILS | CAVEATS | FOR Dist::Zilla USERS | EXPORTS | BUGS | SEE ALSO | CREDITS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::Perl::Critic&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help