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
164 "typical()".
165 log_close
167 Instance method. Close the log file and stop logging. You
168 shouldn't need to invoke this directly; the destructor does it.
169 log_warnings
171 Instance method. Invoking this redefines $SIG{__WARN__} to log to
172 STDERR and to the tester's log. This is automatically invoked when
173 using the "typical" constructor.
174 log MESSAGE...
176 Instance method. Log a message to the log file. No alterations
177 are made on the text of the message. See msg() for an alternative.
178 msg MESSAGE...
180 Instance method. Log a message to the log file. Lines are
181 prefixed with "** " for clarity, and a terminating newline is
182 forced.
183 Utilities
185 catdir DIR, ..., DIR
186 Class/instance method. Concatenate several directories into a path
187 ending in a directory. Lightweight version of the one in
188 "File::Spec"; this method dates back to a more-innocent time when
189 File::Spec was younger and less ubiquitous.
190 Paths are assumed to be absolute. To signify a relative path, the
192 first DIR must be ".", which is processed specially.
193 On Mac, the path does end in a ':'. On Unix, the path does not end
195 in a '/'.
196 catfile DIR, ..., DIR, FILE
198 Class/instance method. Like catdir(), but last element is assumed
199 to be a file. Note that, at a minimum, you must supply at least a
200 single DIR.
201
203 $Id: TBone.pm,v 1.124 2001/08/20 20:30:07 eryq Exp $
204
206 Version 1.124 (2001/08/20)
207 The terms-of-use have been placed in the distribution file
208 "COPYING". Also, small documentation tweaks were made.
209 Version 1.122 (2001/08/20)
211 Changed output of "END" to "# END"; apparently, "END" is not a
212 directive. Maybe it never was. Thanks to Michael G. Schwern for
213 the bug report.
214 The storyteller
216 need not say "the end" aloud;
217 Silence is enough.
218 Automatically invoke "log_warnings()" when constructing via
220 "typical()".
221 Version 1.120 (2001/08/17)
223 Added log_warnings() to support the logging of SIG{__WARN__}
224 messages to the log file (if any).
225 Version 1.116 (2000/03/23)
227 Cosmetic improvements only.
228 Version 1.112 (1999/05/12)
230 Added lightweight catdir() and catfile() (a la File::Spec) to
231 enhance portability to Mac environment.
232 Version 1.111 (1999/04/18)
234 Now uses File::Basename to create "typical" logfile name, for
235 portability.
236 Version 1.110 (1999/04/17)
238 Fixed bug in constructor that surfaced if no log was being used.
239 Created: Friday-the-13th of February, 1998.
241
243 Eryq (eryq@zeegee.com). President, ZeeGee Software Inc.
244 (http://www.zeegee.com).
245 Go to http://www.zeegee.com for the latest downloads and on-line
247 documentation for this module.
248 Enjoy. Yell if it breaks.
250perl v5.28.1 2001-08-20 ExtUtils::TBone(3)