ZeeGee Software

ExtUtils::TBone 1.121


Top NAME

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


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


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


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


Top PUBLIC INTERFACE


Top Construction

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

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


Top Doing tests

Top begin NUMTESTS
Instance method. Start testing.

Top end
Instance method. End testing.

Top ok BOOL, [TESTNAME], [PARAMHASH...]
Instance method. Do a test, and log some information connected with it. 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"

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

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


Top Logging messages

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

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

Top log_warnings
Instance method. Redefine $SIG{__WARN__} to log to STDERR and to the log.

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

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


Top Utilities

Top catdir DIR, ..., DIR
Class/instance method. Concatenate several directories into a path ending in a directory. Lightweight version of the one in the (very new) File::Spec.

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

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


Top VERSION

$Id: TBone.pm,v 1.121 2001/08/17 01:56:59 eryq Exp $


Top CHANGE LOG

Top Version 1.120 (2001/08/17)
Added log_warnings() to support the logging of SIG{__WARN__} messages to the log file (if any).

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

Top Version 1.112 (1999/05/12)
Added lightweight catdir() and catfile() (a la File::Spec) to enhance portability to Mac environment.

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

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


Top AUTHOR

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


Generated Fri Aug 17 10:46:09 2001 by cvu_pod2html