ExtUtils::TBone - a ``skeleton'' for writing ``t/*.t'' test files.


Include a copy of this module in your t directory (as t/ExtUtils/TBone.pm), and then write your t/*.t files like this:

    use ExtUtils::TBone;

    # Begin testing, and expect 3 tests in all:

    # Run some tests:    
           "Is that ok, or isn't it?"); 
           "Do they match?",
           This => $this,
           That => $that);

    # That last one could have also been written... 

    # End testing:


This module is intended for 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. Hopefully, bug reports which include the contents of this file will be easier for you to investigate.


Standard output

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

    ok 1
    not ok 2
    ok 3
    # END

Log file

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


    ** A message logged with msg().
    ** Another one.
    1: ok 1

    ** Yet another message.
    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. This allows you to scan a large file easily with ``grep'' (or, ahem, ``perl''). A blank line follows each test's record, for clarity.



new [ARGS...]
Class method, constructor. Create a new tester. Any arguments are sent to log_open().

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.

Doing tests

Instance method. Start testing. This outputs the 1..NUMTESTS line to the standard output.

Instance method. Indicate the end of testing. This outputs a ``# END'' line to the standard output.

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:


Or even better, like this:

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


    3: Does the user have a .forward file?
    3:   User: "alice"
    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"

Instance method. Convenience front end to ok(): test whether ASTRING eq BSTRING, and logs the operands as 'A' and 'B'.

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().

Instance method. Close the log file and stop logging. You shouldn't need to invoke this directly; the destructor does it.

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...

msg MESSAGE...
Instance method. Log a message to the log file. Lines are prefixed with ``** '' for clarity, and a terminating newline is forced.


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 '/'.

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.


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


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)

Version 1.116 (2000/03/23)
Cosmetic improvements only.

Version 1.112 (1999/05/12)

Version 1.111 (1999/04/18)
Now uses File::Basename to create ``typical'' logfile name, for portability.

Version 1.110 (1999/04/17)

Created: Friday-the-13th of February, 1998.


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.