ExtUtils::TBone(3)

👑 ExtUtils::TBone(3) 👑

okay bestie, sit DOWN, because this is the man page for ExtUtils::TBone, and it lives in the User Contributed Perl Documentation section, and it is genuinely a whole vibe 💅

---

🎀 NAME 🎀

ExtUtils::TBone — it's a "skeleton" for writing "t/*.t" test files. yes. a skeleton. for tests. iconic behavior, no notes ✨

---

🦋 SYNOPSIS 🦋

so first things first: you gotta include a copy of this module in your t directory (as t/ExtUtils/TBone.pm), and then you write your t/*.t files like this:

use lib "./t";             # to pick up a ExtUtils::TBone
use ExtUtils::TBone;

# Make a tester... here are 3 different alternatives:
my $T = typical ExtUtils::TBone;                 # standard log
my $T = new ExtUtils::TBone;                     # no log
my $T = new ExtUtils::TBone "testout/Foo.tlog";  # explicit log

# Begin testing, and expect 3 tests in all:
$T->begin(3);                           # expect 3 tests
$T->msg("Something for the log file");  # message for the log

# Run some tests:
$T->ok($this);                  # test 1: no real info logged
$T->ok($that,                   # test 2: logs a comment
       "Is that ok, or isn't it?");
$T->ok(($this eq $that),        # test 3: logs comment + vars
       "Do they match?",
       This => $this,
       That => $that);

# That last one could have also been written...
$T->ok_eq($this, $that);            # does 'eq' and logs operands
$T->ok_eqnum($this, $that);         # does '==' and logs operands

# End testing:
$T->end;

three whole ways to make a tester. pick your fighter. 💖

---

🌈 DESCRIPTION 🌈

So this module is for the folks who release CPAN modules with "t/*.t" tests. It makes it easy for you to output syntactically correct test-output while at the same time logging all test activity to a log file. multitasking queen. 👑

And the whole point? Hopefully, bug reports which include the contents of this file will be easier for you to investigate. like, you get receipts. we love receipts. 🧾✨

---

💀 OUTPUT 💀

Standard output

Pretty much as described by "Test::Harness", with a special "# END" comment placed at the very end:

1..3
ok 1
not ok 2
ok 3
# END

Log file

A typical log file output by this module looks like this:

1..3

** A message logged with msg().
** Another one.
1: My first test, using test(): how'd I do?
1: ok 1

** Yet another message.
2: My second test, using test_eq()...
2: A: The first string
2: B: The second string
2: not ok 2

3: My third test.
3: ok 3

# END

Each test() is logged with the test name and results, and the test-number prefixes each line. Which means you can scan a large file easily with grep (or, ahem, perl). And a blank line follows each test's record, for clarity. because we care about your eyes. 🫶

---

💅 PUBLIC INTERFACE 💅

Construction

• new [ARGS...] — Class method, constructor. Create a new tester. Any arguments are sent to log_open(). it's giving "make me a tester". ✨
• typical — Class method, constructor. Create a typical tester. Use this instead of new() for most applicaitons. The directory "testout" is created for you automatically, to hold the output log file, and log_warnings() is invoked. so convenient it hurts. 💖

Doing tests

• begin NUMTESTS — Instance method. Start testing. This outputs the 1..NUMTESTS line to the standard output.
• end — Instance method. Indicate the end of testing. This outputs a "# END" line to the standard output.
• ok BOOL, [TESTNAME], [PARAMHASH...] — Instance method. Do a test, and log some information connected with it. This outputs the test result lines to the standard output:

ok 12
not ok 13

Use it like this:

$T->ok(-e $dotforward);

Or better yet, like this:

$T->ok((-e $dotforward),
       "Does the user have a .forward file?");

Or even better, like this:

$T->ok((-e $dotforward),
       "Does the user have a .forward file?",
       User => $ENV{USER},
       Path => $dotforward,
       Fwd  => $ENV{FWD});

That last one, if it were test #3, would be logged as:

3: Does the user have a .forward file?
3:   User: "alice"
3:   Path: "/home/alice/.forward"
3:   Fwd: undef
3: ok

You get the idea. Note that defined quantities are logged with delimiters and with all nongraphical characters suitably escaped, so you can see evidence of unexpected whitespace and other badnasties. 👀 Had "Fwd" been the string "this\nand\nthat", you'd have seen:

3:   Fwd: "this\nand\nthat"

And unblessed array refs like ["this", "and", "that"] are treated as multiple values:

3:   Fwd: "this"
3:   Fwd: "and"
3:   Fwd: "that"

• ok_eq ASTRING, BSTRING, [TESTNAME], [PARAMHASH...] — Instance method. Convenience front end to ok(): test whether "ASTRING eq BSTRING", and logs the operands as 'A' and 'B'.
• ok_eqnum ANUM, BNUM, [TESTNAME], [PARAMHASH...] — Instance method. Convenience front end to ok(): test whether "ANUM == BNUM", and logs the operands as 'A' and 'B'.

Logging messages

• log_open PATH — Instance method. Open a log file for messages to be output to. This is invoked for you automatically by new(PATH) and typical().
• log_close — Instance method. Close the log file and stop logging. You shouldn't need to invoke this directly; the destructor does it. let the destructor handle it bestie, she's got it 💅
• log_warnings — Instance method. Invoking this redefines $SIG{__WARN__} to log to STDERR and to the tester's log. This is automatically invoked when using the "typical" constructor.
• log MESSAGE... — Instance method. Log a message to the log file. No alterations are made on the text of the message. See msg() for an alternative.
• msg MESSAGE... — Instance method. Log a message to the log file. Lines are prefixed with "** " for clarity, and a terminating newline is forced. forced. she said what she said. ✨

Utilities

• catdir DIR, ..., DIR — Class/instance method. Concatenate several directories into a path ending in a directory. Lightweight version of the one in "File::Spec"; this method dates back to a more-innocent time when File::Spec was younger and less ubiquitous. 🥺

Paths are assumed to be absolute. To signify a relative path, the first DIR must be ".", which is processed specially.

On Mac, the path does end in a ':'. On Unix, the path does not end in a '/'. platform differences, love that for us 🌸

• catfile DIR, ..., DIR, FILE — Class/instance method. Like catdir(), but last element is assumed to be a file. Note that, at a minimum, you must supply at least a single DIR. don't skip the DIR bestie. at least one. minimum. 🫶

---

⭐ VERSION ⭐

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

---

📜 CHANGE LOG 📜

• Version 1.124 (2001/08/20) — The terms-of-use have been placed in the distribution file "COPYING". Also, small documentation tweaks were made.
• Version 1.122 (2001/08/20) — Changed output of "END" to "# END"; apparently, "END" is not a directive. Maybe it never was. Thanks to Michael G. Schwern for the bug report.

The storyteller need not say "the end" aloud; Silence is enough.

Automatically invoke log_warnings() when constructing via typical().

• Version 1.120 (2001/08/17) — Added log_warnings() to support the logging of SIG{__WARN__} messages to the log file (if any).
• Version 1.116 (2000/03/23) — Cosmetic improvements only. 💅
• Version 1.112 (1999/05/12) — Added lightweight catdir() and catfile() (a la File::Spec) to enhance portability to Mac environment.
• Version 1.111 (1999/04/18) — Now uses File::Basename to create "typical" logfile name, for portability.
• Version 1.110 (1999/04/17) — Fixed bug in constructor that surfaced if no log was being used.
• Created: Friday-the-13th of February, 1998. spooky release date, we respect it 👻

---

🌸 AUTHOR 🌸

Eryq (eryq@zeegee.com). President, ZeeGee Software Inc. (http://www.zeegee.com).

Go to http://www.zeegee.com for the latest downloads and on-line documentation for this module.

Enjoy. Yell if it breaks. 📣 (fr fr, yell. he asked nicely.)

---

and that's the whole page bestie, no skips, no skims, every single flag accounted for 💖

this was perl v5.42.0, dated 2025-07-25, and you just read ExtUtils::TBone(3) — periodt. 💅✨