.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "Test::Strict 3pm"
.TH Test::Strict 3pm 2024-03-08 "perl v5.38.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
Test::Strict \- Check syntax, presence of use strict; and test coverage
.SH VERSION
.IX Header "VERSION"
Version 0.52
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\f(CW\*(C`Test::Strict\*(C'\fR lets you check the syntax, presence of \f(CW\*(C`use strict;\*(C'\fR
and presence \f(CW\*(C`use warnings;\*(C'\fR in your perl code.
It report its results in standard Test::Simple fashion:
.PP
.Vb 4
\&    use Test::Strict tests => 3;
\&    syntax_ok( \*(Aqbin/myscript.pl\*(Aq );
\&    strict_ok( \*(AqMy::Module\*(Aq, "use strict; in My::Module" );
\&    warnings_ok( \*(Aqlib/My/Module.pm\*(Aq );
.Ve
.PP
Module authors can include the following in a t/strict.t
and have \f(CW\*(C`Test::Strict\*(C'\fR automatically find and check
all perl files in a module distribution:
.PP
.Vb 2
\&  use Test::Strict;
\&  all_perl_files_ok(); # Syntax ok and use strict;
.Ve
.PP
or
.PP
.Vb 2
\&    use Test::Strict;
\&    all_perl_files_ok( @mydirs );
.Ve
.PP
\&\f(CW\*(C`Test::Strict\*(C'\fR can also enforce a minimum test coverage
the test suite should reach.
Module authors can include the following in a t/cover.t
and have \f(CW\*(C`Test::Strict\*(C'\fR automatically check the test coverage:
.PP
.Vb 2
\&    use Test::Strict;
\&    all_cover_ok( 80 );  # at least 80% coverage
.Ve
.PP
or
.PP
.Vb 2
\&    use Test::Strict;
\&    all_cover_ok( 80, \*(Aqt/\*(Aq );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The most basic test one can write is "does it compile ?".
This module tests if the code compiles and play nice with Test::Simple modules.
.PP
Another good practice this module can test is to "use strict;" in all perl files.
.PP
By setting a minimum test coverage through \f(CWall_cover_ok()\fR, a code author
can ensure his code is tested above a preset level of \fIkwality\fR throughout the development cycle.
.PP
Along with Test::Pod, this module can provide the first tests to setup for a module author.
.PP
This module should be able to run under the \-T flag for perl >= 5.6.
All paths are untainted with the following pattern: \f(CW\*(C`qr|^([\-+@\ew./:\e\e]+)$|\*(C'\fR
controlled by \f(CW$Test::Strict::UNTAINT_PATTERN\fR.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .SS "syntax_ok( $file [, $text] )"
.el .SS "syntax_ok( \f(CW$file\fP [, \f(CW$text\fP] )"
.IX Subsection "syntax_ok( $file [, $text] )"
Run a syntax check on \f(CW$file\fR by running \f(CW\*(C`perl \-c $file\*(C'\fR with an external perl interpreter.
The external perl interpreter path is stored in \f(CW$Test::Strict::PERL\fR which can be modified.
You may prefer \f(CWuse_ok()\fR from Test::More to syntax test a module.
For a module, the path (lib/My/Module.pm) or the name (My::Module) can be both used.
.ie n .SS "strict_ok( $file [, $text] )"
.el .SS "strict_ok( \f(CW$file\fP [, \f(CW$text\fP] )"
.IX Subsection "strict_ok( $file [, $text] )"
Check if \f(CW$file\fR contains a \f(CW\*(C`use strict;\*(C'\fR statement.
\&\f(CW\*(C`use Moose\*(C'\fR and \f(CW\*(C`use Mouse\*(C'\fR are also considered valid.
use Modern::Perl is also accepted.
.PP
This is a pretty naive test which may be fooled in some edge cases.
For a module, the path (lib/My/Module.pm) or the name (My::Module) can be both used.
.SS modules_enabling_strict
.IX Subsection "modules_enabling_strict"
Experimental. Returning a list of modules and pragmata that enable strict.
To modify this list, change \f(CW@Test::Strict::MODULES_ENABLING_STRICT\fR.
.PP
List taken from Module::CPANTS::Kwalitee::Uses v95
.SS modules_enabling_warnings
.IX Subsection "modules_enabling_warnings"
Experimental. Returning a list of modules and pragmata that enable warnings
To modify this list, change \f(CW@Test::Strict::MODULES_ENABLING_WARNINGS\fR.
.PP
List taken from Module::CPANTS::Kwalitee::Uses v95
.ie n .SS "warnings_ok( $file [, $text] )"
.el .SS "warnings_ok( \f(CW$file\fP [, \f(CW$text\fP] )"
.IX Subsection "warnings_ok( $file [, $text] )"
Check if warnings have been turned on.
.PP
If \f(CW$file\fR is a module, check if it contains a \f(CW\*(C`use warnings;\*(C'\fR or \f(CW\*(C`use warnings::...\*(C'\fR
or \f(CW\*(C`use Moose\*(C'\fR or \f(CW\*(C`use Mouse\*(C'\fR statement. use Modern::Perl is also accepted.
If the perl version is <= 5.6, this test is skipped (\f(CW\*(C`use warnings\*(C'\fR appeared in perl 5.6).
.PP
If \f(CW$file\fR is a script, check if it starts with \f(CW\*(C`#!...perl \-w\*(C'\fR.
If the \-w is not found and perl is >= 5.6, check for a \f(CW\*(C`use warnings;\*(C'\fR or \f(CW\*(C`use warnings::...\*(C'\fR
or \f(CW\*(C`use Moose\*(C'\fR or \f(CW\*(C`use Mouse\*(C'\fR statement. use Modern::Perl is also accepted.
.PP
This is a pretty naive test which may be fooled in some edge cases.
For a module, the path (lib/My/Module.pm) or the name (My::Module) can be both used.
.ie n .SS "all_perl_files_ok( [ @directories ] )"
.el .SS "all_perl_files_ok( [ \f(CW@directories\fP ] )"
.IX Subsection "all_perl_files_ok( [ @directories ] )"
Applies \f(CWstrict_ok()\fR and \f(CWsyntax_ok()\fR to all perl files found in \f(CW@directories\fR (and sub directories).
If no <@directories> is given, the starting point is one level above the current running script,
that should cover all the files of a typical CPAN distribution.
A perl file is *.pl or *.pm or *.t or a file starting with \f(CW\*(C`#!...perl\*(C'\fR
.PP
If the test plan is defined:
.PP
.Vb 2
\&  use Test::Strict tests => 18;
\&  all_perl_files_ok();
.Ve
.PP
the total number of files tested must be specified.
.PP
You can control which tests are run on each perl site through:
.PP
.Vb 4
\&  $Test::Strict::TEST_SYNTAX   (default = 1)
\&  $Test::Strict::TEST_STRICT   (default = 1)
\&  $Test::Strict::TEST_WARNINGS (default = 0)
\&  $Test::Strict::TEST_SKIP     (default = []) "Trusted" files to skip
.Ve
.ie n .SS "all_cover_ok( [coverage_threshold [, @t_dirs]] )"
.el .SS "all_cover_ok( [coverage_threshold [, \f(CW@t_dirs\fP]] )"
.IX Subsection "all_cover_ok( [coverage_threshold [, @t_dirs]] )"
This will run all the tests in \f(CW@t_dirs\fR
(or current script's directory if \f(CW@t_dirs\fR is undef)
under Devel::Cover
and calculate the global test coverage of the code loaded by the tests.
If the test coverage is greater or equal than \f(CW\*(C`coverage_threshold\*(C'\fR, it is a pass,
otherwise it's a fail. The default coverage threshold is 50
(meaning 50% of the code loaded has been covered by test).
.PP
The threshold can be modified through \f(CW$Test::Strict::COVERAGE_THRESHOLD\fR.
.PP
You may want to select which files are selected for code
coverage through \f(CW$Test::Strict::DEVEL_COVER_OPTIONS\fR,
see Devel::Cover for the list of available options.
The default is '+ignore,"/Test/Strict\eb"'.
.PP
The path to \f(CW\*(C`cover\*(C'\fR utility can be modified through \f(CW$Test::Strict::COVER\fR.
.PP
The 50% threshold is a completely arbitrary value, which should not be considered
as a good enough coverage.
.PP
The total coverage is the return value of \f(CWall_cover_ok()\fR.
.SH CAVEATS
.IX Header "CAVEATS"
For \f(CWall_cover_ok()\fR to work properly, it is strongly advised to install the most recent version of Devel::Cover
and use perl 5.8.1 or above.
In the case of a \f(CW\*(C`make test\*(C'\fR scenario, \f(CWall_perl_files_ok()\fR re-run all the tests in a separate perl interpreter,
this may lead to some side effects.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::More, Test::Pod. Test::Distribution, Test::NoWarnings
.SH REPOSITORY
.IX Header "REPOSITORY"
<https://github.com/manwar/Test\-Strict>
.SH AUTHOR
.IX Header "AUTHOR"
Pierre Denis, \f(CW\*(C`<pdenis@gmail.com>\*(C'\fR.
.SH MAINTAINER
.IX Header "MAINTAINER"
Gabor Szabo <http://szabgab.com/>
.PP
Currently maintained by Mohammad S Anwar (MANWAR), \f(CW\*(C`<mohammad.anwar at yahoo.com>\*(C'\fR
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2005, 2010 Pierre Denis, All Rights Reserved.
.PP
You may use, modify, and distribute this package under the
same terms as Perl itself.