diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Test::Builder::Tester.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Test::Builder::Tester.3perl | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Test::Builder::Tester.3perl b/upstream/debian-unstable/man3/Test::Builder::Tester.3perl new file mode 100644 index 00000000..058d546d --- /dev/null +++ b/upstream/debian-unstable/man3/Test::Builder::Tester.3perl @@ -0,0 +1,316 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Test::Builder::Tester 3perl" +.TH Test::Builder::Tester 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Test::Builder::Tester \- test testsuites that have been built with +Test::Builder +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& use Test::Builder::Tester tests => 1; +\& use Test::More; +\& +\& test_out("not ok 1 \- foo"); +\& test_fail(+1); +\& fail("foo"); +\& test_test("fail works"); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A module that helps you test testing modules that are built with +Test::Builder. +.PP +The testing system is designed to be used by performing a three step +process for each test you wish to test. This process starts with using +\&\f(CW\*(C`test_out\*(C'\fR and \f(CW\*(C`test_err\*(C'\fR in advance to declare what the testsuite you +are testing will output with Test::Builder to stdout and stderr. +.PP +You then can run the test(s) from your test suite that call +Test::Builder. At this point the output of Test::Builder is +safely captured by Test::Builder::Tester rather than being +interpreted as real test output. +.PP +The final stage is to call \f(CW\*(C`test_test\*(C'\fR that will simply compare what you +predeclared to what Test::Builder actually outputted, and report the +results back with a "ok" or "not ok" (with debugging) to the normal +output. +.SS Functions +.IX Subsection "Functions" +These are the six methods that are exported as default. +.IP test_out 4 +.IX Item "test_out" +.PD 0 +.IP test_err 4 +.IX Item "test_err" +.PD +Procedures for predeclaring the output that your test suite is +expected to produce until \f(CW\*(C`test_test\*(C'\fR is called. These procedures +automatically assume that each line terminates with "\en". So +.Sp +.Vb 1 +\& test_out("ok 1","ok 2"); +.Ve +.Sp +is the same as +.Sp +.Vb 1 +\& test_out("ok 1\enok 2"); +.Ve +.Sp +which is even the same as +.Sp +.Vb 2 +\& test_out("ok 1"); +\& test_out("ok 2"); +.Ve +.Sp +Once \f(CW\*(C`test_out\*(C'\fR or \f(CW\*(C`test_err\*(C'\fR (or \f(CW\*(C`test_fail\*(C'\fR or \f(CW\*(C`test_diag\*(C'\fR) have +been called, all further output from Test::Builder will be +captured by Test::Builder::Tester. This means that you will not +be able perform further tests to the normal output in the normal way +until you call \f(CW\*(C`test_test\*(C'\fR (well, unless you manually meddle with the +output filehandles) +.IP test_fail 4 +.IX Item "test_fail" +Because the standard failure message that Test::Builder produces +whenever a test fails will be a common occurrence in your test error +output, and because it has changed between Test::Builder versions, rather +than forcing you to call \f(CW\*(C`test_err\*(C'\fR with the string all the time like +so +.Sp +.Vb 1 +\& test_err("# Failed test ($0 at line ".line_num(+1).")"); +.Ve +.Sp +\&\f(CW\*(C`test_fail\*(C'\fR exists as a convenience function that can be called +instead. It takes one argument, the offset from the current line that +the line that causes the fail is on. +.Sp +.Vb 1 +\& test_fail(+1); +.Ve +.Sp +This means that the example in the synopsis could be rewritten +more simply as: +.Sp +.Vb 4 +\& test_out("not ok 1 \- foo"); +\& test_fail(+1); +\& fail("foo"); +\& test_test("fail works"); +.Ve +.IP test_diag 4 +.IX Item "test_diag" +As most of the remaining expected output to the error stream will be +created by Test::Builder's \f(CW\*(C`diag\*(C'\fR function, Test::Builder::Tester +provides a convenience function \f(CW\*(C`test_diag\*(C'\fR that you can use instead of +\&\f(CW\*(C`test_err\*(C'\fR. +.Sp +The \f(CW\*(C`test_diag\*(C'\fR function prepends comment hashes and spacing to the +start and newlines to the end of the expected output passed to it and +adds it to the list of expected error output. So, instead of writing +.Sp +.Vb 1 +\& test_err("# Couldn\*(Aqt open file"); +.Ve +.Sp +you can write +.Sp +.Vb 1 +\& test_diag("Couldn\*(Aqt open file"); +.Ve +.Sp +Remember that Test::Builder's diag function will not add newlines to +the end of output and test_diag will. So to check +.Sp +.Vb 1 +\& Test::Builder\->new\->diag("foo\en","bar\en"); +.Ve +.Sp +You would do +.Sp +.Vb 1 +\& test_diag("foo","bar") +.Ve +.Sp +without the newlines. +.IP test_test 4 +.IX Item "test_test" +Actually performs the output check testing the tests, comparing the +data (with \f(CW\*(C`eq\*(C'\fR) that we have captured from Test::Builder against +what was declared with \f(CW\*(C`test_out\*(C'\fR and \f(CW\*(C`test_err\*(C'\fR. +.Sp +This takes name/value pairs that effect how the test is run. +.RS 4 +.IP "title (synonym 'name', 'label')" 4 +.IX Item "title (synonym 'name', 'label')" +The name of the test that will be displayed after the \f(CW\*(C`ok\*(C'\fR or \f(CW\*(C`not +ok\*(C'\fR. +.IP skip_out 4 +.IX Item "skip_out" +Setting this to a true value will cause the test to ignore if the +output sent by the test to the output stream does not match that +declared with \f(CW\*(C`test_out\*(C'\fR. +.IP skip_err 4 +.IX Item "skip_err" +Setting this to a true value will cause the test to ignore if the +output sent by the test to the error stream does not match that +declared with \f(CW\*(C`test_err\*(C'\fR. +.RE +.RS 4 +.Sp +As a convenience, if only one argument is passed then this argument +is assumed to be the name of the test (as in the above examples.) +.Sp +Once \f(CW\*(C`test_test\*(C'\fR has been run test output will be redirected back to +the original filehandles that Test::Builder was connected to +(probably STDOUT and STDERR,) meaning any further tests you run +will function normally and cause success/errors for Test::Harness. +.RE +.IP line_num 4 +.IX Item "line_num" +A utility function that returns the line number that the function was +called on. You can pass it an offset which will be added to the +result. This is very useful for working out the correct text of +diagnostic functions that contain line numbers. +.Sp +Essentially this is the same as the \f(CW\*(C`_\|_LINE_\|_\*(C'\fR macro, but the +\&\f(CWline_num(+3)\fR idiom is arguably nicer. +.PP +In addition to the six exported functions there exists one +function that can only be accessed with a fully qualified function +call. +.IP color 4 +.IX Item "color" +When \f(CW\*(C`test_test\*(C'\fR is called and the output that your tests generate +does not match that which you declared, \f(CW\*(C`test_test\*(C'\fR will print out +debug information showing the two conflicting versions. As this +output itself is debug information it can be confusing which part of +the output is from \f(CW\*(C`test_test\*(C'\fR and which was the original output from +your original tests. Also, it may be hard to spot things like +extraneous whitespace at the end of lines that may cause your test to +fail even though the output looks similar. +.Sp +To assist you \f(CW\*(C`test_test\*(C'\fR can colour the background of the debug +information to disambiguate the different types of output. The debug +output will have its background coloured green and red. The green +part represents the text which is the same between the executed and +actual output, the red shows which part differs. +.Sp +The \f(CW\*(C`color\*(C'\fR function determines if colouring should occur or not. +Passing it a true or false value will enable or disable colouring +respectively, and the function called with no argument will return the +current setting. +.Sp +To enable colouring from the command line, you can use the +Text::Builder::Tester::Color module like so: +.Sp +.Vb 1 +\& perl \-Mlib=Text::Builder::Tester::Color test.t +.Ve +.Sp +Or by including the Test::Builder::Tester::Color module directly in +the PERL5LIB. +.SH BUGS +.IX Header "BUGS" +Test::Builder::Tester does not handle plans well. It has never done anything +special with plans. This means that plans from outside Test::Builder::Tester +will effect Test::Builder::Tester, worse plans when using Test::Builder::Tester +will effect overall testing. At this point there are no plans to fix this bug +as people have come to depend on it, and Test::Builder::Tester is now +discouraged in favor of \f(CWTest2::API::intercept()\fR. See +<https://github.com/Test\-More/test\-more/issues/667> +.PP +Calls \f(CW\*(C`Test::Builder\->no_ending\*(C'\fR turning off the ending tests. +This is needed as otherwise it will trip out because we've run more +tests than we strictly should have and it'll register any failures we +had that we were testing for as real failures. +.PP +The color function doesn't work unless Term::ANSIColor is +compatible with your terminal. Additionally, Win32::Console::ANSI +must be installed on windows platforms for color output. +.PP +Bugs (and requests for new features) can be reported to the author +though GitHub: +<https://github.com/Test\-More/test\-more/issues> +.SH AUTHOR +.IX Header "AUTHOR" +Copyright Mark Fowler <mark@twoshortplanks.com> 2002, 2004. +.PP +Some code taken from Test::More and Test::Catch, written by +Michael G Schwern <schwern@pobox.com>. Hence, those parts +Copyright Micheal G Schwern 2001. Used and distributed with +permission. +.PP +This program is free software; you can redistribute it +and/or modify it under the same terms as Perl itself. +.SH MAINTAINERS +.IX Header "MAINTAINERS" +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.SH NOTES +.IX Header "NOTES" +Thanks to Richard Clamp <richardc@unixbeard.net> for letting +me use his testing system to try this module out on. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Test::Builder, Test::Builder::Tester::Color, Test::More. |