[REPATCH] Re: [PATCH pod/perlhack.pod] When to use what test libraries

Message-ID: <20011107165249.I7346@blackrider>

p4raw-id: //depot/perl@12899

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 6f11044..66a8ea0 100644 (file)
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1531,47 +1531,42 @@ tests to the end. First, we'll test that the C<U> does indeed create
 Unicode strings.  
 
 t/op/pack.t has a sensible ok() function, but if it didn't we could
-write one easily.
+use the one from t/test.pl.
 
-    my $test = 1;
-    sub ok {
-        my($ok, $name) = @_;
-
-        # You have to do it this way or VMS will get confused.
-        print $ok ? "ok $test - $name\n" : "not ok $test - $name\n";
-
-        printf "# Failed test at line %d\n", (caller)[2] unless $ok;
-
-        $test++;
-        return $ok;
-    }
+ require './test.pl';
+ plan( tests => 159 );
 
 so instead of this:
 
  print 'not ' unless "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000);
  print "ok $test\n"; $test++;
 
-we can write the (somewhat) more sensible:
+we can write the more sensible (see L<Test::More> for a full
+explanation of is() and other testing functions).
 
- ok( "1.20.300.4000" eq sprintf "%vd", pack("U*",1,20,300,4000), 
+ is( "1.20.300.4000", sprintf "%vd", pack("U*",1,20,300,4000), 
                                        "U* produces unicode" );
 
 Now we'll test that we got that space-at-the-beginning business right:
 
- ok( "1.20.300.4000" eq sprintf "%vd", pack("  U*",1,20,300,4000),
+ is( "1.20.300.4000", sprintf "%vd", pack("  U*",1,20,300,4000),
                                        "  with spaces at the beginning" );
 
 And finally we'll test that we don't make Unicode strings if C<U> is B<not>
 the first active format:
 
- ok( v1.20.300.4000 ne  sprintf "%vd", pack("C0U*",1,20,300,4000),
+ isnt( v1.20.300.4000, sprintf "%vd", pack("C0U*",1,20,300,4000),
                                        "U* not first isn't unicode" );
 
-Mustn't forget to change the number of tests which appears at the top, or
-else the automated tester will get confused:
+Mustn't forget to change the number of tests which appears at the top,
+or else the automated tester will get confused.  This will either look
+like this:
 
- -print "1..156\n";
- +print "1..159\n";
+ print "1..156\n";
+
+or this:
+
+ plan( tests => 156 );
 
 We now compile up Perl, and run it through the test suite. Our new
 tests pass, hooray!
@@ -1717,7 +1712,7 @@ I<really> broken.
 =item F<t/cmd/>
 
 These test the basic control structures, C<if/else>, C<while>,
-subroutines, etc... 
+subroutines, etc.
 
 =item F<t/comp/>
 
@@ -1754,11 +1749,35 @@ The core uses the same testing style as the rest of Perl, a simple
 "ok/not ok" run through Test::Harness, but there are a few special
 considerations.
 
-For most libraries and extensions, you'll want to use the Test::More
-library rather than rolling your own test functions.  If a module test
-doesn't use Test::More, consider rewriting it so it does.  For the
-rest it's best to use a simple C<print "ok $test_num\n"> style to avoid
-broken core functionality from causing the whole test to collapse.
+There are three ways to write a test in the core.  Test::More,
+t/test.pl and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">.  The
+decision of which to use depends on what part of the test suite you're
+working on.  This is a measure to prevent a high-level failure (such
+as Config.pm breaking) from causing basic functionality tests to fail.
+
+=over 4 
+
+=item t/base t/comp
+
+Since we don't know if require works, or even subroutines, use ad hoc
+tests for these two.  Step carefully to avoid using the feature being
+tested.
+
+=item t/cmd t/run t/io t/op
+
+Now that basic require() and subroutines are tested, you can use the
+t/test.pl library which emulates the important features of Test::More
+while using a minimum of core features.
+
+You can also conditionally use certain libraries like Config, but be
+sure to skip the test gracefully if it's not there.
+
+=item t/lib ext lib
+
+Now that the core of Perl is tested, Test::More can be used.  You can
+also use the full suite of core modules in the tests.
+
+=back
 
 When you say "make test" Perl uses the F<t/TEST> program to run the
 test suite.  All tests are run from the F<t/> directory, B<not> the