| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Test::Builder::Tester 3perl" |
| 58 |
.TH Test::Builder::Tester 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Test::Builder::Tester \- test testsuites that have been built with |
| 65 |
Test::Builder |
| 66 |
.SH SYNOPSIS |
| 67 |
.IX Header "SYNOPSIS" |
| 68 |
.Vb 2 |
| 69 |
\& use Test::Builder::Tester tests => 1; |
| 70 |
\& use Test::More; |
| 71 |
\& |
| 72 |
\& test_out("not ok 1 \- foo"); |
| 73 |
\& test_fail(+1); |
| 74 |
\& fail("foo"); |
| 75 |
\& test_test("fail works"); |
| 76 |
.Ve |
| 77 |
.SH DESCRIPTION |
| 78 |
.IX Header "DESCRIPTION" |
| 79 |
A module that helps you test testing modules that are built with |
| 80 |
Test::Builder. |
| 81 |
.PP |
| 82 |
The testing system is designed to be used by performing a three step |
| 83 |
process for each test you wish to test. This process starts with using |
| 84 |
\&\f(CW\*(C`test_out\*(C'\fR and \f(CW\*(C`test_err\*(C'\fR in advance to declare what the testsuite you |
| 85 |
are testing will output with Test::Builder to stdout and stderr. |
| 86 |
.PP |
| 87 |
You then can run the test(s) from your test suite that call |
| 88 |
Test::Builder. At this point the output of Test::Builder is |
| 89 |
safely captured by Test::Builder::Tester rather than being |
| 90 |
interpreted as real test output. |
| 91 |
.PP |
| 92 |
The final stage is to call \f(CW\*(C`test_test\*(C'\fR that will simply compare what you |
| 93 |
predeclared to what Test::Builder actually outputted, and report the |
| 94 |
results back with a "ok" or "not ok" (with debugging) to the normal |
| 95 |
output. |
| 96 |
.SS Functions |
| 97 |
.IX Subsection "Functions" |
| 98 |
These are the six methods that are exported as default. |
| 99 |
.IP test_out 4 |
| 100 |
.IX Item "test_out" |
| 101 |
.PD 0 |
| 102 |
.IP test_err 4 |
| 103 |
.IX Item "test_err" |
| 104 |
.PD |
| 105 |
Procedures for predeclaring the output that your test suite is |
| 106 |
expected to produce until \f(CW\*(C`test_test\*(C'\fR is called. These procedures |
| 107 |
automatically assume that each line terminates with "\en". So |
| 108 |
.Sp |
| 109 |
.Vb 1 |
| 110 |
\& test_out("ok 1","ok 2"); |
| 111 |
.Ve |
| 112 |
.Sp |
| 113 |
is the same as |
| 114 |
.Sp |
| 115 |
.Vb 1 |
| 116 |
\& test_out("ok 1\enok 2"); |
| 117 |
.Ve |
| 118 |
.Sp |
| 119 |
which is even the same as |
| 120 |
.Sp |
| 121 |
.Vb 2 |
| 122 |
\& test_out("ok 1"); |
| 123 |
\& test_out("ok 2"); |
| 124 |
.Ve |
| 125 |
.Sp |
| 126 |
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 |
| 127 |
been called, all further output from Test::Builder will be |
| 128 |
captured by Test::Builder::Tester. This means that you will not |
| 129 |
be able perform further tests to the normal output in the normal way |
| 130 |
until you call \f(CW\*(C`test_test\*(C'\fR (well, unless you manually meddle with the |
| 131 |
output filehandles) |
| 132 |
.IP test_fail 4 |
| 133 |
.IX Item "test_fail" |
| 134 |
Because the standard failure message that Test::Builder produces |
| 135 |
whenever a test fails will be a common occurrence in your test error |
| 136 |
output, and because it has changed between Test::Builder versions, rather |
| 137 |
than forcing you to call \f(CW\*(C`test_err\*(C'\fR with the string all the time like |
| 138 |
so |
| 139 |
.Sp |
| 140 |
.Vb 1 |
| 141 |
\& test_err("# Failed test ($0 at line ".line_num(+1).")"); |
| 142 |
.Ve |
| 143 |
.Sp |
| 144 |
\&\f(CW\*(C`test_fail\*(C'\fR exists as a convenience function that can be called |
| 145 |
instead. It takes one argument, the offset from the current line that |
| 146 |
the line that causes the fail is on. |
| 147 |
.Sp |
| 148 |
.Vb 1 |
| 149 |
\& test_fail(+1); |
| 150 |
.Ve |
| 151 |
.Sp |
| 152 |
This means that the example in the synopsis could be rewritten |
| 153 |
more simply as: |
| 154 |
.Sp |
| 155 |
.Vb 4 |
| 156 |
\& test_out("not ok 1 \- foo"); |
| 157 |
\& test_fail(+1); |
| 158 |
\& fail("foo"); |
| 159 |
\& test_test("fail works"); |
| 160 |
.Ve |
| 161 |
.IP test_diag 4 |
| 162 |
.IX Item "test_diag" |
| 163 |
As most of the remaining expected output to the error stream will be |
| 164 |
created by Test::Builder's \f(CW\*(C`diag\*(C'\fR function, Test::Builder::Tester |
| 165 |
provides a convenience function \f(CW\*(C`test_diag\*(C'\fR that you can use instead of |
| 166 |
\&\f(CW\*(C`test_err\*(C'\fR. |
| 167 |
.Sp |
| 168 |
The \f(CW\*(C`test_diag\*(C'\fR function prepends comment hashes and spacing to the |
| 169 |
start and newlines to the end of the expected output passed to it and |
| 170 |
adds it to the list of expected error output. So, instead of writing |
| 171 |
.Sp |
| 172 |
.Vb 1 |
| 173 |
\& test_err("# Couldn\*(Aqt open file"); |
| 174 |
.Ve |
| 175 |
.Sp |
| 176 |
you can write |
| 177 |
.Sp |
| 178 |
.Vb 1 |
| 179 |
\& test_diag("Couldn\*(Aqt open file"); |
| 180 |
.Ve |
| 181 |
.Sp |
| 182 |
Remember that Test::Builder's diag function will not add newlines to |
| 183 |
the end of output and test_diag will. So to check |
| 184 |
.Sp |
| 185 |
.Vb 1 |
| 186 |
\& Test::Builder\->new\->diag("foo\en","bar\en"); |
| 187 |
.Ve |
| 188 |
.Sp |
| 189 |
You would do |
| 190 |
.Sp |
| 191 |
.Vb 1 |
| 192 |
\& test_diag("foo","bar") |
| 193 |
.Ve |
| 194 |
.Sp |
| 195 |
without the newlines. |
| 196 |
.IP test_test 4 |
| 197 |
.IX Item "test_test" |
| 198 |
Actually performs the output check testing the tests, comparing the |
| 199 |
data (with \f(CW\*(C`eq\*(C'\fR) that we have captured from Test::Builder against |
| 200 |
what was declared with \f(CW\*(C`test_out\*(C'\fR and \f(CW\*(C`test_err\*(C'\fR. |
| 201 |
.Sp |
| 202 |
This takes name/value pairs that effect how the test is run. |
| 203 |
.RS 4 |
| 204 |
.IP "title (synonym 'name', 'label')" 4 |
| 205 |
.IX Item "title (synonym 'name', 'label')" |
| 206 |
The name of the test that will be displayed after the \f(CW\*(C`ok\*(C'\fR or \f(CW\*(C`not |
| 207 |
ok\*(C'\fR. |
| 208 |
.IP skip_out 4 |
| 209 |
.IX Item "skip_out" |
| 210 |
Setting this to a true value will cause the test to ignore if the |
| 211 |
output sent by the test to the output stream does not match that |
| 212 |
declared with \f(CW\*(C`test_out\*(C'\fR. |
| 213 |
.IP skip_err 4 |
| 214 |
.IX Item "skip_err" |
| 215 |
Setting this to a true value will cause the test to ignore if the |
| 216 |
output sent by the test to the error stream does not match that |
| 217 |
declared with \f(CW\*(C`test_err\*(C'\fR. |
| 218 |
.RE |
| 219 |
.RS 4 |
| 220 |
.Sp |
| 221 |
As a convenience, if only one argument is passed then this argument |
| 222 |
is assumed to be the name of the test (as in the above examples.) |
| 223 |
.Sp |
| 224 |
Once \f(CW\*(C`test_test\*(C'\fR has been run test output will be redirected back to |
| 225 |
the original filehandles that Test::Builder was connected to |
| 226 |
(probably STDOUT and STDERR,) meaning any further tests you run |
| 227 |
will function normally and cause success/errors for Test::Harness. |
| 228 |
.RE |
| 229 |
.IP line_num 4 |
| 230 |
.IX Item "line_num" |
| 231 |
A utility function that returns the line number that the function was |
| 232 |
called on. You can pass it an offset which will be added to the |
| 233 |
result. This is very useful for working out the correct text of |
| 234 |
diagnostic functions that contain line numbers. |
| 235 |
.Sp |
| 236 |
Essentially this is the same as the \f(CW\*(C`_\|_LINE_\|_\*(C'\fR macro, but the |
| 237 |
\&\f(CWline_num(+3)\fR idiom is arguably nicer. |
| 238 |
.PP |
| 239 |
In addition to the six exported functions there exists one |
| 240 |
function that can only be accessed with a fully qualified function |
| 241 |
call. |
| 242 |
.IP color 4 |
| 243 |
.IX Item "color" |
| 244 |
When \f(CW\*(C`test_test\*(C'\fR is called and the output that your tests generate |
| 245 |
does not match that which you declared, \f(CW\*(C`test_test\*(C'\fR will print out |
| 246 |
debug information showing the two conflicting versions. As this |
| 247 |
output itself is debug information it can be confusing which part of |
| 248 |
the output is from \f(CW\*(C`test_test\*(C'\fR and which was the original output from |
| 249 |
your original tests. Also, it may be hard to spot things like |
| 250 |
extraneous whitespace at the end of lines that may cause your test to |
| 251 |
fail even though the output looks similar. |
| 252 |
.Sp |
| 253 |
To assist you \f(CW\*(C`test_test\*(C'\fR can colour the background of the debug |
| 254 |
information to disambiguate the different types of output. The debug |
| 255 |
output will have its background coloured green and red. The green |
| 256 |
part represents the text which is the same between the executed and |
| 257 |
actual output, the red shows which part differs. |
| 258 |
.Sp |
| 259 |
The \f(CW\*(C`color\*(C'\fR function determines if colouring should occur or not. |
| 260 |
Passing it a true or false value will enable or disable colouring |
| 261 |
respectively, and the function called with no argument will return the |
| 262 |
current setting. |
| 263 |
.Sp |
| 264 |
To enable colouring from the command line, you can use the |
| 265 |
Text::Builder::Tester::Color module like so: |
| 266 |
.Sp |
| 267 |
.Vb 1 |
| 268 |
\& perl \-Mlib=Text::Builder::Tester::Color test.t |
| 269 |
.Ve |
| 270 |
.Sp |
| 271 |
Or by including the Test::Builder::Tester::Color module directly in |
| 272 |
the PERL5LIB. |
| 273 |
.SH BUGS |
| 274 |
.IX Header "BUGS" |
| 275 |
Test::Builder::Tester does not handle plans well. It has never done anything |
| 276 |
special with plans. This means that plans from outside Test::Builder::Tester |
| 277 |
will effect Test::Builder::Tester, worse plans when using Test::Builder::Tester |
| 278 |
will effect overall testing. At this point there are no plans to fix this bug |
| 279 |
as people have come to depend on it, and Test::Builder::Tester is now |
| 280 |
discouraged in favor of \f(CWTest2::API::intercept()\fR. See |
| 281 |
<https://github.com/Test\-More/test\-more/issues/667> |
| 282 |
.PP |
| 283 |
Calls \f(CW\*(C`Test::Builder\->no_ending\*(C'\fR turning off the ending tests. |
| 284 |
This is needed as otherwise it will trip out because we've run more |
| 285 |
tests than we strictly should have and it'll register any failures we |
| 286 |
had that we were testing for as real failures. |
| 287 |
.PP |
| 288 |
The color function doesn't work unless Term::ANSIColor is |
| 289 |
compatible with your terminal. Additionally, Win32::Console::ANSI |
| 290 |
must be installed on windows platforms for color output. |
| 291 |
.PP |
| 292 |
Bugs (and requests for new features) can be reported to the author |
| 293 |
though GitHub: |
| 294 |
<https://github.com/Test\-More/test\-more/issues> |
| 295 |
.SH AUTHOR |
| 296 |
.IX Header "AUTHOR" |
| 297 |
Copyright Mark Fowler <[email protected]> 2002, 2004. |
| 298 |
.PP |
| 299 |
Some code taken from Test::More and Test::Catch, written by |
| 300 |
Michael G Schwern <[email protected]>. Hence, those parts |
| 301 |
Copyright Micheal G Schwern 2001. Used and distributed with |
| 302 |
permission. |
| 303 |
.PP |
| 304 |
This program is free software; you can redistribute it |
| 305 |
and/or modify it under the same terms as Perl itself. |
| 306 |
.SH MAINTAINERS |
| 307 |
.IX Header "MAINTAINERS" |
| 308 |
.IP "Chad Granum <[email protected]>" 4 |
| 309 |
.IX Item "Chad Granum <[email protected]>" |
| 310 |
.SH NOTES |
| 311 |
.IX Header "NOTES" |
| 312 |
Thanks to Richard Clamp <[email protected]> for letting |
| 313 |
me use his testing system to try this module out on. |
| 314 |
.SH "SEE ALSO" |
| 315 |
.IX Header "SEE ALSO" |
| 316 |
Test::Builder, Test::Builder::Tester::Color, Test::More. |