This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[REPATCH] Re: [PATCH pod/perlhack.pod] When to use what test libraries
authorMichael G. Schwern <schwern@pobox.com>
Wed, 7 Nov 2001 16:52:49 +0000 (11:52 -0500)
committerJarkko Hietaniemi <jhi@iki.fi>
Thu, 8 Nov 2001 13:46:02 +0000 (13:46 +0000)
Message-ID: <20011107165249.I7346@blackrider>

p4raw-id: //depot/perl@12899

pod/perlhack.pod

index 6f11044..66a8ea0 100644 (file)
@@ -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
 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++;
 
 
 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:
 
                                        "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:
 
                                        "  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" );
 
                                        "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!
 
 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>,
 =item F<t/cmd/>
 
 These test the basic control structures, C<if/else>, C<while>,
-subroutines, etc... 
+subroutines, etc.
 
 =item F<t/comp/>
 
 
 =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.
 
 "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
 
 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