Is available at http://slaysys.com/src/SelfTest-0.01.tar.gz Here's the POD such as it is, comment & test away. I will be splitting it into light & SelfTest::Heavy at some point. NAME SelfTest - Inline testing of code from command line SYNOPSIS ## In a module MyModule: (can also use in a script) use strict ; ## Applies to source code & test code use SelfTest ; ## Detects when module is run from command line use OtherModule ; ## Applies only to source, not to test code =begin testing use MyModule ; ## Must use self use Test ; ## Unless you prefer other means plan tests => 2 ; my $m = MyModule->new ; =end testing # ..normal Perl & POD here... =for testing ok( my_module_func(), "expected result", "comment" ) ; # More normal code... =begin testing $m->foo() ; ok( $m->func, 1, "comment" ) ; =end testing ## If you want to use an external test file: use SelfTest( test_file => "t/foo.t" ) ; DESCRIPTION ALPHA CODE WARNING: Use at yor own risk. Report bugs. Live long and... SelfTest is a source filter that normally does nothing. Cool. However, when a perl source code file is run in "self test mode", all normal code and POD is ignored and only POD marked as being for "testing" will be seen by perl. This allows you to execute tests embedded in a module or script's POD very easily: perl lib/Foo.pm PERL_SELF_TEST=1 bin/foo.pl Self test mode is entered automatically when a source file that uses SelfTest from a package other than `main' is run from the command line. It is not entered automatically if SelfTest is used from package `main', otherwise you would have trouble running self-testing scripts from the command line. Automatic self testing can be suppressed by passing the option "-noauto": use SelfTest( -noauto, ... ) ; or by setting the environment variable PERL_SELF_TEST to 0. In many Unix shells, this can be done like so: PERL_SELF_TEST=0 perl lib/Foo.pm POD embedded test code may look like: =begin testing ## Any perl code allowed here. ok( foo(), 'foo result', etc. ) ; =end testing =for testing ## Any perl code allowed here. No blank lines, of course ok( $is_ok ) =item fun() fun() can be called like this: =alsofor testing ## EXPERIMENTAL, see RFC11 $result = fun( 10 ) ; =for testing ok( $result, 10 ) ; ok( fun( 11 ), 11 ) ; ## Further testing =cut sub fun { return shift ; } If a module does a use SelftTest ; ## Must be 'use', not 'require' the module is run from the comand line instead of being required or used, all normal code and POD will be discarded and only the test code will be run. When the module is required or used by another module, SelfTest is a fairly quick noop. It currently bloats your memory a little bit more than need be, but that will minimized in the future by moving selftest-mode code to a SelfTest::Heavy module, minimizing the footprint of SelfTest. This allow you to execute your module from within your editor and see if it passes the embedded tests. This is make maintaining tests quite convenient. SelfTest detects whether it is being run from the command line WARNING: this module implements the experimental `=alsofor', `=alsobegin', and `=alsoend' as outlined in RFC11. Most other POD parsers do not, although there are two prototype implementations as of this writing that do (Pod::StdParser, which I wrote and is a bit of a hack, and Pod::Tests, by Michael Schwern). This module does not implement the experimental `=for example', `=begin example', and `=end example' because they are not yet well defined and because more flexibility is acheived using `=also..' constructs. This may change as they become better defined and more useful. The Resulting Test Script When in self test mode, the perl compiler will see all source code before the use SelfTest ; and then only the lines from marked sections. Typically, `use SelfTest' comes immediately after `use warnings' and `use strict', so that both of the pragmas affect test code and the module. Any modules the test script needs that the main source file does not should be placed in a `=begin testing' section. This includes using the source module itself, although a `use Test' is issued automatically as a convenience (see example below). If you don't want to `use Test', then contact me and I'll add an option to disable this behavior. Each line of this example is marked-up to show which version of the module it winds up in, test or normal. 1:package MyModule ; normal code, test code 2: normal code, test code 3:use strict ; normal code, test code 4:use warnings ; normal code, test code 5:use SelfTest( tests => 2 ) ; normal code (but is a noop) 6:use Carp ; normal code 7: normal code 9:=begin testing normal POD(ignored), test comment 10: normal POD(ignored), test code 12: use MyModule ; normal POD(ignored), test code 13: ok( foo() ) ; normal POD(ignored), test code 14: my $result ; normal POD(ignored), test code 15: normal POD(ignored), test code 16: =end testing normal POD(ignored), test comment 17: normal POD 18:=alsofor testing normal POD(experimental), test comment 19: $result = foo() ; normal POD(experimantal), test code 20: normal POD 21:=for testing normal POD(ignored), test comment 22: ok($result) ; normal POD(ignored), test code 23: normal POD 24:foo() does this and that. normal POD 25: normal POD 26:=cut normal POD 27: normal code 28:sub foo() { 1 } ; normal code The test script perl sees when this module is compiled in selftest mode might look like: package MyModule ; use strict ; use warnings ; use Test ; plan tests => 2, todo => [] ; #=begin testing #line 10 use MyModule ; ok( foo() ) ; my $result ; #=end testing #=alsofor testing #line 18 $result = foo() ; # #=for testing #line 21 ok($result) ; # When using the `test_file' option, all lines after the `use Test' are omitted and the named file is substituted instead: package MyModule ; use SelfTest( test_file => "t/MyModule.t" ) ; unfortunately puts the contents of MyModule.t into package "MyModule", but this is normally not a problem. This may well change in future releases. ENVIRONMENT VARIABLES PERL_SELF_TEST Value Action ----- ------ 0 Prevents SelfTesting "" Lets SelfTest determine whether to enter self-test mode 1 Forces SelfTest mode on first C<use SelfTest> encountered All other values are reserved for future use. PERL_SELF_TEST_DEBUG Value Action ----- ------ 0, "" Disables SelfTest debug output 1 outputs the post-filtered script when in self test mode All other values are reserved for future use. Note that when in debug mode you won't see the lines leading up to the `use SelfTest': they've already been compiled by the time SelfTest gets to check PERL_SELF_TEST_DEBUG. Don't bother trying to get them back by moving SelfTest before the `package' line: that will only make SelfTest never self test unless PERL_SELF_TEST is set. LIMITATIONS SelfTest does not police POD, especially the rule that a blank line with no whitespace must precede and follow pod directive paragraphs. This means that SelfTest will find your tests and execute them when more careful POD scanners will not, which is bad from a portability point of view. You need Filter::Call::Util on your system to do self tests, though you do *not* need it just to use these modules. Filter::Util::Call requires a C compiler, so you'll need a binary distribution of it if you don't have an acceptable one. COPYRIGHT Copyright 2000, Barrie Slaymaker. No rights reserved :). AUTHOR Barrie Slaymaker <[EMAIL PROTECTED]>
