More docs about running tests and the test suite.

Update perlhack.pod in various places.
Add 'test_harness' as a .PHONY dependency in the Makefile.

p4raw-id: //depot/perl@19206

diff --git a/Makefile.SH b/Makefile.SH
index 64ca7ad..32856e0 100644 (file)
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -1004,7 +1004,7 @@ makedepend: makedepend.SH config.sh
        test_tty test-tty _test_tty test_notty test-notty _test_notty \
        utest ucheck test.utf8 check.utf8 test.torture torturetest \
        test.third check.third utest.third ucheck.third test_notty.third \
-       test.deparse test_notty.deparse \
+       test.deparse test_notty.deparse test_harness \
        minitest coretest
 
 # Cannot delegate rebuilding of t/perl to make

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 6e5d5f5..43f8d3f 100644 (file)
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1719,6 +1719,18 @@ modules hanging around in here that need to be moved out into F<lib/>.
 Testing features of how perl actually runs, including exit codes and
 handling of PERL* environment variables.
 
+=item F<t/uni/>
+
+Tests for the core support of Unicode.
+
+=item F<t/win32/>
+
+Windows-specific tests.
+
+=item F<t/x2p>
+
+A test suite for the s2p converter.
+
 =back
 
 The core uses the same testing style as the rest of Perl, a simple
@@ -1795,7 +1807,7 @@ F<perl3.log.testname>.
 =item test.torture torturetest
 
 Run all the usual tests and some extra tests.  As of Perl 5.8.0 the
-only extra tests are Abigail's JAPHs, t/japh/abigail.t.
+only extra tests are Abigail's JAPHs, F<t/japh/abigail.t>.
 
 You can also run the torture test with F<t/harness> by giving
 C<-torture> argument to F<t/harness>.
@@ -1804,6 +1816,58 @@ C<-torture> argument to F<t/harness>.
 
 Run all the tests with -Mutf8.  Not all tests will succeed.
 
+=item test_harness
+
+Run the test suite with the F<t/harness> controlling program, instead of
+F<t/TEST>. F<t/harness> is more sophisticated, and uses the
+L<Test::Harness> module, thus using this test target supposes that perl
+mostly works. The main advantage for our purposes is that it prints a
+detailed summary of failed tests at the end.
+
+=back
+
+=head2 Running tests by hand
+
+You can run part of the test suite by hand by using one the following
+commands from the F<t/> directory :
+
+    ./perl -I../lib TEST list-of-.t-files
+
+or
+
+    ./perl -I../lib harness list-of-.t-files
+
+(if you don't specify test scripts, the whole test suite will be run.)
+
+You can run an individual test by a command similar to
+
+    ./perl -I../lib patho/to/foo.t
+
+except that the harnesses set up some environment variables that may
+affect the execution of the test :
+
+=over 4 
+
+=item PERL_CORE=1
+
+indicates that we're running this test part of the perl core test suite.
+This is useful for modules that have a dual life on CPAN.
+
+=item PERL_DESTRUCT_LEVEL=2
+
+is set to 2 if it isn't set already (see L</PERL_DESTRUCT_LEVEL>)
+
+=item PERL
+
+(used only by F<t/TEST>) if set, overrides the path to the perl executable
+that should be used to run the tests (the default being F<./perl>).
+
+=item PERL_SKIP_TTY_TEST
+
+if set, tells to skip the tests that need a terminal. It's actually set
+automatically by the Makefile, but can also be forced artificially by
+running 'make test_notty'.
+
 =back
 
 =head1 EXTERNAL TOOLS FOR DEBUGGING PERL

diff --git a/t/README b/t/README
index a20b481..c129720 100644 (file)
--- a/t/README
+++ b/t/README
@@ -26,6 +26,6 @@ That is, they should not require Config.pm nor should they require any
 extensions to have been built.  TEST will abort if any tests in the
 t/base/ directory fail.
 
-Tests in the t/comp/, t/cmd/, t/run/, t/io/, and t/op/ directories should
-also be runnable by miniperl and not require Config.pm, but failures
-to comply will not cause TEST to abort like for t/base/.
+Tests in the t/comp/, t/cmd/, t/run/, t/io/, t/op/ and t/uni/ directories
+should also be runnable by miniperl and not require Config.pm, but
+failures to comply will not cause TEST to abort like for t/base/.