1ExtUtils::TBone(3)    User Contributed Perl Documentation   ExtUtils::TBone(3)
2
3
4

NAME

6       ExtUtils::TBone - a "skeleton" for writing "t/*.t" test files.
7

SYNOPSIS

9       Include a copy of this module in your t directory (as
10       t/ExtUtils/TBone.pm), and then write your t/*.t files like this:
11
12           use lib "./t";             # to pick up a ExtUtils::TBone
13           use ExtUtils::TBone;
14
15           # Make a tester... here are 3 different alternatives:
16           my $T = typical ExtUtils::TBone;                 # standard log
17           my $T = new ExtUtils::TBone;                     # no log
18           my $T = new ExtUtils::TBone "testout/Foo.tlog";  # explicit log
19
20           # Begin testing, and expect 3 tests in all:
21           $T->begin(3);                           # expect 3 tests
22           $T->msg("Something for the log file");  # message for the log
23
24           # Run some tests:
25           $T->ok($this);                  # test 1: no real info logged
26           $T->ok($that,                   # test 2: logs a comment
27                  "Is that ok, or isn't it?");
28           $T->ok(($this eq $that),        # test 3: logs comment + vars
29                  "Do they match?",
30                  This => $this,
31                  That => $that);
32
33           # That last one could have also been written...
34           $T->ok_eq($this, $that);            # does 'eq' and logs operands
35           $T->ok_eqnum($this, $that);         # does '==' and logs operands
36
37           # End testing:
38           $T->end;
39

DESCRIPTION

41       This module is intended for folks who release CPAN modules with "t/*.t"
42       tests.  It makes it easy for you to output syntactically correct test-
43       output while at the same time logging all test activity to a log file.
44       Hopefully, bug reports which include the contents of this file will be
45       easier for you to investigate.
46

OUTPUT

48   Standard output
49       Pretty much as described by "Test::Harness", with a special "# END"
50       comment placed at the very end:
51
52           1..3
53           ok 1
54           not ok 2
55           ok 3
56           # END
57

Log file

59       A typical log file output by this module looks like this:
60
61           1..3
62
63           ** A message logged with msg().
64           ** Another one.
65           1: My first test, using test(): how'd I do?
66           1: ok 1
67
68           ** Yet another message.
69           2: My second test, using test_eq()...
70           2: A: The first string
71           2: B: The second string
72           2: not ok 2
73
74           3: My third test.
75           3: ok 3
76
77           # END
78
79       Each test() is logged with the test name and results, and the test-
80       number prefixes each line.  This allows you to scan a large file easily
81       with "grep" (or, ahem, "perl").  A blank line follows each test's
82       record, for clarity.
83

PUBLIC INTERFACE

85   Construction
86       new [ARGS...]
87           Class method, constructor.  Create a new tester.  Any arguments are
88           sent to log_open().
89
90       typical
91           Class method, constructor.  Create a typical tester.  Use this
92           instead of new() for most applicaitons.  The directory "testout" is
93           created for you automatically, to hold the output log file, and
94           log_warnings() is invoked.
95
96   Doing tests
97       begin NUMTESTS
98           Instance method.  Start testing.  This outputs the 1..NUMTESTS line
99           to the standard output.
100
101       end Instance method.  Indicate the end of testing.  This outputs a "#
102           END" line to the standard output.
103
104       ok BOOL, [TESTNAME], [PARAMHASH...]
105           Instance method.  Do a test, and log some information connected
106           with it.  This outputs the test result lines to the standard
107           output:
108
109               ok 12
110               not ok 13
111
112           Use it like this:
113
114               $T->ok(-e $dotforward);
115
116           Or better yet, like this:
117
118               $T->ok((-e $dotforward),
119                      "Does the user have a .forward file?");
120
121           Or even better, like this:
122
123               $T->ok((-e $dotforward),
124                      "Does the user have a .forward file?",
125                      User => $ENV{USER},
126                      Path => $dotforward,
127                      Fwd  => $ENV{FWD});
128
129           That last one, if it were test #3, would be logged as:
130
131               3: Does the user have a .forward file?
132               3:   User: "alice"
133               3:   Path: "/home/alice/.forward"
134               3:   Fwd: undef
135               3: ok
136
137           You get the idea.  Note that defined quantities are logged with
138           delimiters and with all nongraphical characters suitably escaped,
139           so you can see evidence of unexpected whitespace and other
140           badnasties.  Had "Fwd" been the string "this\nand\nthat", you'd
141           have seen:
142
143               3:   Fwd: "this\nand\nthat"
144
145           And unblessed array refs like ["this", "and", "that"] are treated
146           as multiple values:
147
148               3:   Fwd: "this"
149               3:   Fwd: "and"
150               3:   Fwd: "that"
151
152       ok_eq ASTRING, BSTRING, [TESTNAME], [PARAMHASH...]
153           Instance method.  Convenience front end to ok(): test whether
154           "ASTRING eq BSTRING", and logs the operands as 'A' and 'B'.
155
156       ok_eqnum ANUM, BNUM, [TESTNAME], [PARAMHASH...]
157           Instance method.  Convenience front end to ok(): test whether "ANUM
158           == BNUM", and logs the operands as 'A' and 'B'.
159
160   Logging messages
161       log_open PATH
162           Instance method.  Open a log file for messages to be output to.
163           This is invoked for you automatically by new(PATH) and typical().
164
165       log_close
166           Instance method.  Close the log file and stop logging.  You
167           shouldn't need to invoke this directly; the destructor does it.
168
169       log_warnings
170           Instance method.  Invoking this redefines $SIG{__WARN__} to log to
171           STDERR and to the tester's log.  This is automatically invoked when
172           using the "typical" constructor.
173
174       log MESSAGE...
175           Instance method.  Log a message to the log file.  No alterations
176           are made on the text of the message.  See msg() for an alternative.
177
178       msg MESSAGE...
179           Instance method.  Log a message to the log file.  Lines are
180           prefixed with "** " for clarity, and a terminating newline is
181           forced.
182
183   Utilities
184       catdir DIR, ..., DIR
185           Class/instance method.  Concatenate several directories into a path
186           ending in a directory.  Lightweight version of the one in
187           "File::Spec"; this method dates back to a more-innocent time when
188           File::Spec was younger and less ubiquitous.
189
190           Paths are assumed to be absolute.  To signify a relative path, the
191           first DIR must be ".", which is processed specially.
192
193           On Mac, the path does end in a ':'.  On Unix, the path does not end
194           in a '/'.
195
196       catfile DIR, ..., DIR, FILE
197           Class/instance method.  Like catdir(), but last element is assumed
198           to be a file.  Note that, at a minimum, you must supply at least a
199           single DIR.
200

VERSION

202       $Id: TBone.pm,v 1.124 2001/08/20 20:30:07 eryq Exp $
203

CHANGE LOG

205       Version 1.124   (2001/08/20)
206           The terms-of-use have been placed in the distribution file
207           "COPYING".  Also, small documentation tweaks were made.
208
209       Version 1.122   (2001/08/20)
210           Changed output of "END" to "# END"; apparently, "END" is not a
211           directive.  Maybe it never was.  Thanks to Michael G. Schwern for
212           the bug report.
213
214               The storyteller
215                  need not say "the end" aloud;
216               Silence is enough.
217
218           Automatically invoke log_warnings() when constructing via
219           typical().
220
221       Version 1.120   (2001/08/17)
222           Added log_warnings() to support the logging of SIG{__WARN__}
223           messages to the log file (if any).
224
225       Version 1.116   (2000/03/23)
226           Cosmetic improvements only.
227
228       Version 1.112   (1999/05/12)
229           Added lightweight catdir() and catfile() (a la File::Spec) to
230           enhance portability to Mac environment.
231
232       Version 1.111   (1999/04/18)
233           Now uses File::Basename to create "typical" logfile name, for
234           portability.
235
236       Version 1.110   (1999/04/17)
237           Fixed bug in constructor that surfaced if no log was being used.
238
239       Created: Friday-the-13th of February, 1998.
240

AUTHOR

242       Eryq (eryq@zeegee.com).  President, ZeeGee Software Inc.
243       (http://www.zeegee.com).
244
245       Go to http://www.zeegee.com for the latest downloads and on-line
246       documentation for this module.
247
248       Enjoy.  Yell if it breaks.
249
250
251
252perl v5.36.0                      2023-01-20                ExtUtils::TBone(3)
Impressum