[perl5.git] / t / README

This is the perl test library.  To run the test suite, just type './TEST'
or 'make test' from the build directory above t/.  See also the section
"Special Make Test Targets" in pod/perlhack.pod to learn about other
specific test commands.

To add new tests, just look at the current tests and do likewise.
The library t/test.pl provides some utility functions that you can use
in most tests, except in the most basic ones.

If a test fails, run it by itself to see if it prints any informative
diagnostics.  If not, modify the test to print informative diagnostics.
If you put out extra lines with a '#' character on the front, you don't
have to worry about removing the extra print statements later since TEST
ignores lines beginning with '#'.

If you know that Perl is basically working but expect that some tests
will fail, you may want to use Test::Harness thusly:
        cd t
        ./perl harness
This method pinpoints failed tests automatically.

If you come up with new tests, please submit them to
https://github.com/Perl/perl5/issues.

Tests in the t/base/ directory must be runnable with plain miniperl alone.
That is, they should not assume that require works, let alone that they can
require Config.pm, strict or warnings.  This constraint is frustrating, but
necessary as they exist to sanity test the rest of the test framework.
TEST will abort if any tests in the t/base/ directory fail.

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/.

The comment in TEST explains the test bootstrapping order:

* base first, as TEST bails out if that can't run
* then comp, to validate that require works
* then run, to validate that -M works
* then we know we can -MTestInit for everything else, making life simpler

Tests in t/perf/ are designed to test performance and optimisations,
and also contain additional tools and files designed to run outside
of the test suite
Commit	Line	Data
a266333a RGS	1	This is the perl test library. To run the test suite, just type './TEST'
	2	or 'make test' from the build directory above t/. See also the section
	3	"Special Make Test Targets" in pod/perlhack.pod to learn about other
	4	specific test commands.
8d063cd8 LW	5
8d063cd8 LW	6	To add new tests, just look at the current tests and do likewise.
a266333a RGS	7	The library t/test.pl provides some utility functions that you can use
a266333a RGS	8	in most tests, except in the most basic ones.
8d063cd8 LW	9
	10	If a test fails, run it by itself to see if it prints any informative
	11	diagnostics. If not, modify the test to print informative diagnostics.
	12	If you put out extra lines with a '#' character on the front, you don't
	13	have to worry about removing the extra print statements later since TEST
	14	ignores lines beginning with '#'.
	15
774d564b	16	If you know that Perl is basically working but expect that some tests
774d564b	17	will fail, you may want to use Test::Harness thusly:
bd87065d	18	cd t
785aa5e3	19	./perl harness
774d564b	20	This method pinpoints failed tests automatically.
bbad3607	21
8166b4e0 DB	22	If you come up with new tests, please submit them to
8166b4e0 DB	23	https://github.com/Perl/perl5/issues.
b25e12d2	24
fc0b7d58 NC	25	Tests in the t/base/ directory must be runnable with plain miniperl alone.
	26	That is, they should not assume that require works, let alone that they can
	27	require Config.pm, strict or warnings. This constraint is frustrating, but
	28	necessary as they exist to sanity test the rest of the test framework.
	29	TEST will abort if any tests in the t/base/ directory fail.
bd87065d	30
244d9cb7 RGS	31	Tests in the t/comp/, t/cmd/, t/run/, t/io/, t/op/ and t/uni/ directories
	32	should also be runnable by miniperl and not require Config.pm, but
	33	failures to comply will not cause TEST to abort like for t/base/.
c7f294b6	34
fc0b7d58 NC	35	The comment in TEST explains the test bootstrapping order:
	36
	37	* base first, as TEST bails out if that can't run
	38	* then comp, to validate that require works
	39	* then run, to validate that -M works
	40	* then we know we can -MTestInit for everything else, making life simpler
	41
c7f294b6 DM	42	Tests in t/perf/ are designed to test performance and optimisations,
	43	and also contain additional tools and files designed to run outside
	44	of the test suite