NAME

       Test::NoBreakpoints - test that files do not contain soft breakpoints

VERSION

       version 0.15

SYNOPSIS

        use Test::NoBreakpoints;
        plan tests => $num_tests;
        no_breakpoints_ok( $file, 'Contains no soft breakpoints' );

       Module authors can include the following in a t/nobreakpoints.t file to add such checking
       to a module distribution:

         use Test::More;
         eval "use Test::NoBreakpoints 0.10";
         plan skip_all => "Test::NoBreakpoints 0.10 required for testing" if $@;
         all_files_no_breakpoints_ok();

DESCRIPTION

       I love soft breakpoints ("$DB::single = 1") in the Perl debugger.  Unfortunately, I have a
       habit of putting them in my code during development and forgetting to take them out before
       I upload it to CPAN, necessitating a hasty fix/package/bundle cycle followed by much
       cursing.

       Test::NoBreakpoints checks that files contain neither the string "$DB::single = 1" nor
       "$DB::signal = 1".  By adding such a test to all my modules, I swear less and presumably
       lighten the load on the CPAN in some small way.

FUNCTIONS

       Unless otherwise noted, all functions are tests built on top of Test::Builder, so the
       standard admonition about having made a plan before you run them apply.

   no_breakpoints_ok($file, [$description] )
       Checks that $file contains no breakpoints.  If the optional $description is not passed it
       defaults to "no breakpoint test of $file".

       If the test fails, the line number of the file where the breakpoint was found will be
       emitted.

       For compatibility with old versions of this module, the deprecated name "no_brkpts_ok" may
       also be used (but see "DEPRECATED FUNCTIONS").

   all_perl_files( [@dirs] )
       Returns a list of all *.pl, *.pm and *.t files in the directories listed.  If @dirs is not
       passed, defaults to "blib" and "t".

       The order of the files returned is machine-dependent.  If you want them sorted, you'll
       have to sort them yourself.

   all_files_no_breakpoints_ok( [@files] )
       Checks all files that look like they contain Perl using no_breakpoints_ok(). If @files is
       not provided, it defaults to the return of all_perl_files().

       For compatibility with old versions of this module, the deprecated name
       "all_files_no_brkpts_ok" may also be used (but see "DEPRECATED FUNCTIONS").

EXPORTS

       By default all_files_no_breakpoints_ok and no_breakpoints_ok.

       For the time being, the deprecated forms the above (all_files_no_brkpts_ok and
       no_brkpts_ok) are also exported (but see "DEPRECATED FUNCTIONS").

       On request, all_perl_files.

       Everything with the tag :all.

DEPRECATED FUNCTIONS

       Prior to v0.13 of this module, no_breakpoints_ok was called no_brkpts_ok and
       all_files_no_breakpoints_ok was similarly abbreviated.

       In v0.13, these older names were deprecated.  They are still exported by default, but will
       emit a warning unless you disable the deprecated lexical warning category:

         {
           no warnings 'deprecated';
           no_brkpts_ok(...);
         }

       In the next release, the deprecated functions will have to be pulled in via an import tag.
       In the release after that, they will cease to be.

ACKNOWLEDGEMENTS

       Michael Schwern for Test::Builder.

       Andy Lester for Test::Pod, which is where I got the idea and borrowed the logic of
       all_perl_files from.

BUGS

       •   doesn't catch some breakpoints

           This is a valid breakpoint:

             package DB;
             $single = 1;
             package main;

           as is this:

             my $break = \$DB::single;
             $$break = 1;

           but neither are currently caught.

TODO

       •   enhance regex to find esoteric setting of breakpoints

           If you have a legitimate breakpoint set that isn't caught, please send me an example
           and I'll try to augment the regex to match it.

       •   only look at code rather than the entire file

           This is not as easy as simply stripping out POD, because there might be inline tests
           or examples that are code in there (using Test::Inline).  Granted, those should be
           caught when the generated .t files are themselves tested, but I'd like to make it
           smarter.

       •   not use regular expressions

           The ideal way to find a breakpoint would be to compile the code and then walk the
           opcode tree to find places where the breakpoint is set.  B::FindAmpersand does
           something similar to this to find use of the $& in regular expressions, so this is
           probably the direction I'm going to head in.

SEE ALSO

       Test::Builder

       Test::Pod

AUTHORS

       •   James FitzGibbon <jfitz@cpan.org>

       •   Apocalypse <APOCAL@cpan.org>

       •   Chisel <chisel@chizography.net>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by James FitzGibbon and Chisel Wright.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.