1ExtUtils::TBone(3) User Contributed Perl Documentation ExtUtils::TBone(3)
2
6 ExtUtils::TBone - a "skeleton" for writing "t/*.t" test files.
7
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 use lib "./t"; # to pick up a ExtUtils::TBone
13 use ExtUtils::TBone;
14 # 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 # 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 # 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 # 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 # End testing:
38 $T->end;
39
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
48 Standard output
49 Pretty much as described by "Test::Harness", with a special "# END"
50 comment placed at the very end:
51 1..3
53 ok 1
54 not ok 2
55 ok 3
56 # END
57
59 A typical log file output by this module looks like this:
60 1..3
62 ** A message logged with msg().
64 ** Another one.
65 1: My first test, using test(): how'd I do?
66 1: ok 1
67 ** 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 3: My third test.
75 3: ok 3
76 # END
78 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
85 Construction
86 new [ARGS...]
87 Class method, constructor. Create a new tester. Any arguments are
88 sent to log_open().
89 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 Doing tests
97 begin NUMTESTS
98 Instance method. Start testing. This outputs the 1..NUMTESTS line
99 to the standard output.
100 end Instance method. Indicate the end of testing. This outputs a "#
102 END" line to the standard output.
103 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 ok 12
110 not ok 13
111 Use it like this:
113 $T->ok(-e $dotforward);
115 Or better yet, like this:
117 $T->ok((-e $dotforward),
119 "Does the user have a .forward file?");
120 Or even better, like this:
122 $T->ok((-e $dotforward),
124 "Does the user have a .forward file?",
125 User => $ENV{USER},
126 Path => $dotforward,
127 Fwd => $ENV{FWD});
128 That last one, if it were test #3, would be logged as:
130 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 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 3: Fwd: "this\nand\nthat"
144 And unblessed array refs like ["this", "and", "that"] are treated
146 as multiple values:
147 3: Fwd: "this"
149 3: Fwd: "and"
150 3: Fwd: "that"
151 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 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 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 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 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 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 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 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 Paths are assumed to be absolute. To signify a relative path, the
191 first DIR must be ".", which is processed specially.
192 On Mac, the path does end in a ':'. On Unix, the path does not end
194 in a '/'.
195 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
202 $Id: TBone.pm,v 1.124 2001/08/20 20:30:07 eryq Exp $
203
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 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 The storyteller
215 need not say "the end" aloud;
216 Silence is enough.
217 Automatically invoke log_warnings() when constructing via
219 typical().
220 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 Version 1.116 (2000/03/23)
226 Cosmetic improvements only.
227 Version 1.112 (1999/05/12)
229 Added lightweight catdir() and catfile() (a la File::Spec) to
230 enhance portability to Mac environment.
231 Version 1.111 (1999/04/18)
233 Now uses File::Basename to create "typical" logfile name, for
234 portability.
235 Version 1.110 (1999/04/17)
237 Fixed bug in constructor that surfaced if no log was being used.
238 Created: Friday-the-13th of February, 1998.
240
242 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc.
243 (http://www.zeegee.com).
244 Go to http://www.zeegee.com for the latest downloads and on-line
246 documentation for this module.
247 Enjoy. Yell if it breaks.
249perl v5.38.0 2023-07-20 ExtUtils::TBone(3)