NAME

Test::Perl::Critic - Use Perl::Critic in test scripts

SYNOPSIS

  use Test::Perl::Critic;

  critic_ok($file);                          #Test one file
  all_critic_ok($dir_1, $dir_2, $dir_N );    #Test all files in several $dirs
  all_critic_ok()                            #Test all files in distro

DESCRIPTION

Test::Perl::Critic wraps the the Perl::Critic manpage engine in a convenient subroutine suitable for test scripts written for the Test::Harness manpage. 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.

SUBROUTINES

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''.

all_critic_ok( [@DIRECTORIES] )

Runs critic_ok() for all Perl files beneath the given list of directories. If given an empty list, the function tries to find all Perl files in the blib/ directory. If the blib/ directory does not exist, then it tries the lib/ directory. Returns true if all files are okay, or false if any file fails.

If you are building a module with the usual CPAN directory structure, just make a t/perlcritic.t file like this:

  use Test::More;
  eval 'use Test::Perl::Critic';
  plan skip_all => 'Test::Perl::Critic required to criticise code' if $@;
  all_critic_ok();

Or if you use a the latest version of the Module::Starter::PBP manpage, it will generate this and several other standard test scripts for you.

all_code_files ( [@DIRECTORIES] )

Returns a list of all the Perl files found beneath each DIRECTORY, If @DIRECTORIES is an empty list, defaults to blib/. If blib/ does not exist, it tries lib/. Skips any files in CVS or Subversion directories.

A Perl file is:

Any file that ends in .PL, .pl, .pm, or .t
Any file that has a first line with a shebang containing 'perl'

CONFIGURATION

the Perl::Critic manpage 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 given to the use pragma will be passed into the the Perl::Critic manpage constructor. For example, if you have developed your code using a custom f<.perlcritirc> file, you can ask Test::Perl::Critic to use a custom file too:

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

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

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 giving an additional -format option to the use pragma. For example:

  use Test::Perl::Critic (-format => "%m at line %l, column %c.");
  all_critic_ok();

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

  Escape    Meaning
  -------   ------------------------------------------------------------------
  %m        Brief description of the violation
  %f        Name of the file where the violation occurred.
  %l        Line number where the violation occurred
  %c        Column number where the violation occurred
  %e        Explanation of violation or page numbers in PBP
  %d        Full diagnostic discussion of the violation
  %r        The string of source code that caused the violation
  %p        Name of the Policy module that created the violation
  %s        The severity level of the violation

CAVEATS

Despite the obvious convenience of using test scripts to verify that your code complies with coding standards, its not really sensible to distribute your module with those scripts. You don't know which version of Perl::Critic the user has and whether they have installed additional Policy modules, you can't really be sure that your code will pass the Test::Perl::Critic tests on another machine.

The easy solution is to add your criticize.t test script to the MANIFEST.SKIP. When you test your build, you'll still be able to run the Perl::Critic tests when you 'make test', but they won't be included in the tarball when you 'make dist'.

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

EXPORTS

  critic_ok()
  all_critic_ok()

BUGS

Please report all bugs to http://rt.cpan.org. Thanks.

CREDITS

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

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

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.

Test::Perl::Critic - Use Perl::Critic in test scripts