NAME
    ExtUtils::TBone - a "skeleton" for writing "t/*.t" test files.

SYNOPSIS
    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 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;   

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

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

PUBLIC INTERFACE
  Construction

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

    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.

  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.

    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.

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

    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.

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.

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.