.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" 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 >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::Fixme 3pm" .TH Test::Fixme 3pm "2022-10-13" "perl v5.34.0" "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::Fixme \- Check code for FIXMEs. .SH "VERSION" .IX Header "VERSION" version 0.16 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # In a test script like \*(Aqt/test\-fixme.t\*(Aq \& use Test::Fixme; \& run_tests(); \& \& # You can also tailor the behaviour. \& use Test::Fixme; \& run_tests( where => \*(Aqlib\*(Aq, # where to find files to check \& match => \*(AqTODO\*(Aq, # what to check for \& skip_all => $ENV{SKIP} # should all tests be skipped \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" When coding it is common to come up against problems that need to be addressed but that are not a big deal at the moment. What generally happens is that the coder adds comments like: .PP .Vb 1 \& # FIXME \- what about windows that are bigger than the screen? \& \& # FIXME \- add checking of user privileges here. .Ve .PP Test::Fixme allows you to add a test file that ensures that none of these get forgotten in the module. .SH "METHODS" .IX Header "METHODS" .SS "run_tests" .IX Subsection "run_tests" By default run_tests will search for '\s-1FIXME\s0' in all the files it can find in the project. You can change these defaults by using 'where' or \&'match' as follows: .PP .Vb 3 \& run_tests( where => \*(Aqlib\*(Aq, # just check the modules. \& match => \*(AqTODO\*(Aq # look for things that are not done yet. \& ); .Ve .IP "where" 4 .IX Item "where" Specifies where to search for files. This can be a scalar containing a single directory name, or it can be a list reference containing multiple directory names. .IP "match" 4 .IX Item "match" Expression to search for within the files. This may be a simple string, or a qr//\-quoted regular expression. For example: .Sp .Vb 1 \& match => qr/[T]ODO|[F]IXME|[B]UG/, .Ve .IP "filename_match" 4 .IX Item "filename_match" Expression to filter file names. This should be a qr//\-quoted regular expression. For example: .Sp .Vb 1 \& match => qr/\e.(:pm|pl)$/, .Ve .Sp would only match .pm and .pl files under your specified directory. .IP "manifest" 4 .IX Item "manifest" Specifies the name of your \s-1MANIFEST\s0 file which will be used as the list of files to test instead of \fIwhere\fR or \fIfilename_match\fR. .Sp .Vb 1 \& manifest => \*(AqMANIFEST\*(Aq, .Ve .IP "warn" 4 .IX Item "warn" Do not fail when a \s-1FIXME\s0 or other pattern is matched. Tests that would have been failures will still issue a diagnostic that will be viewed when you run \f(CW\*(C`prove\*(C'\fR without \f(CW\*(C`\-v\*(C'\fR, \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`./Build test\*(C'\fR. .IP "format" 4 .IX Item "format" Specifies format to be used for display of pattern matches. .RS 4 .IP "original" 4 .IX Item "original" The original and currently default format looks something like this: .Sp .Vb 11 \& # File: \*(Aq./lib/Test/Fixme.pm\*(Aq \& # 16 # ABSTRACT: Check code for FIXMEs. \& # 25 $args{match} = \*(AqFIXME\*(Aq unless defined $args{match} && length $args{match}; \& # 28 $args{format} ||= $ENV{TEST_FIXME_FORMAT}; \& # 228 # FIXME \- what about windows that are bigger than the screen? \& # 230 # FIXME \- add checking of user privileges here. \& # 239 By default run_tests will search for \*(AqFIXME\*(Aq in all the files it can \& # 280 Do not fail when a FIXME or other pattern is matched. Tests that would \& # 288 If you want to match something other than \*(AqFIXME\*(Aq then you may find \& # 296 run_tests( skip_all => $ENV{SKIP_TEST_FIXME} ); \& # 303 L .Ve .Sp With the line numbers on the left and the offending text on the right. .IP "perl" 4 .IX Item "perl" The \*(L"perl\*(R" format is that used by Perl itself to report warnings and errors. .Sp .Vb 10 \& # Pattern found at ./lib/Test/Fixme.pm line 16: \& # # ABSTRACT: Check code for FIXMEs. \& # Pattern found at ./lib/Test/Fixme.pm line 25: \& # $args{match} = \*(AqFIXME\*(Aq unless defined $args{match} && length $args{match}; \& # Pattern found at ./lib/Test/Fixme.pm line 28: \& # $args{format} ||= $ENV{TEST_FIXME_FORMAT}; \& # Pattern found at ./lib/Test/Fixme.pm line 228: \& # # FIXME \- what about windows that are bigger than the screen? \& # Pattern found at ./lib/Test/Fixme.pm line 230: \& # # FIXME \- add checking of user privileges here. \& # Pattern found at ./lib/Test/Fixme.pm line 239: \& # By default run_tests will search for \*(AqFIXME\*(Aq in all the files it can \& # Pattern found at ./lib/Test/Fixme.pm line 280: \& # Do not fail when a FIXME or other pattern is matched. Tests that would \& # Pattern found at ./lib/Test/Fixme.pm line 288: \& # If you want to match something other than \*(AqFIXME\*(Aq then you may find \& # Pattern found at ./lib/Test/Fixme.pm line 296: \& # run_tests( skip_all => $ENV{SKIP_TEST_FIXME} ); \& # Pattern found at ./lib/Test/Fixme.pm line 303: \& # L .Ve .Sp For files that contain many offending patterns it may be a bit harder to read for humans, but easier to parse for IDEs. .RE .RS 4 .Sp You may also use the \f(CW\*(C`TEST_FIXME_FORMAT\*(C'\fR environment variable to override either the default or the value specified in the test file. .RE .SH "HINTS" .IX Header "HINTS" If you want to match something other than '\s-1FIXME\s0' then you may find that the test file itself is being caught. Try doing this: .PP .Vb 1 \& run_tests( match => \*(AqTO\*(Aq.\*(AqDO\*(Aq ); .Ve .PP You may also wish to suppress the tests \- try this: .PP .Vb 2 \& use Test::Fixme; \& run_tests( skip_all => $ENV{SKIP_TEST_FIXME} ); .Ve .PP You can only run run_tests once per file. Please use several test files if you want to run several different tests. .SH "CAVEATS" .IX Header "CAVEATS" This module is fully supported back to Perl 5.8.1. It may work on 5.8.0. It should work on Perl 5.6.x and I may even test on 5.6.2. I will accept patches to maintain compatibility for such older Perls, but you may need to fix it on 5.6.x / 5.8.0 and send me a patch. .SH "SEE ALSO" .IX Header "SEE ALSO" Devel::FIXME .SH "ACKNOWLEDGMENTS" .IX Header "ACKNOWLEDGMENTS" Dave O'Neill added support for 'filename_match' and also being able to pass a list of several directories in the 'where' argument. Many thanks. .SH "AUTHOR" .IX Header "AUTHOR" Original author: Edmund von der Burg .PP Current maintainer: Graham Ollis .PP Contributors: .PP Dave O'Neill .PP gregor herrmann .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2016 by Edmund von der Burg , Graham Ollis . .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.