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
164           "typical()".
165
166       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
170       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
175       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
179       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
184   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
191           Paths are assumed to be absolute.  To signify a relative path, the
192           first DIR must be ".", which is processed specially.
193
194           On Mac, the path does end in a ':'.  On Unix, the path does not end
195           in a '/'.
196
197       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

VERSION

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

CHANGE LOG

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
210       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
215               The storyteller
216                  need not say "the end" aloud;
217               Silence is enough.
218
219           Automatically invoke "log_warnings()" when constructing via
220           "typical()".
221
222       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
226       Version 1.116   (2000/03/23)
227           Cosmetic improvements only.
228
229       Version 1.112   (1999/05/12)
230           Added lightweight catdir() and catfile() (a la File::Spec) to
231           enhance portability to Mac environment.
232
233       Version 1.111   (1999/04/18)
234           Now uses File::Basename to create "typical" logfile name, for
235           portability.
236
237       Version 1.110   (1999/04/17)
238           Fixed bug in constructor that surfaced if no log was being used.
239
240       Created: Friday-the-13th of February, 1998.
241

AUTHOR

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