Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.