/ 
Test-Verbose-0.01
River stage zero No dependents
/ Test::Verbose

NAME

Test::Verbose - Run 'make TEST_VERBOSE=1' on one or more test files

SYNOPSIS

# from the command line.  man tv for more details.
$ tv lib/Foo.pm    # test this module
$ tv t/*.t         # run these tests

# from a module
use Test::Verbose qw( test_verbose );
test_verbose( @module_and_test_script_filenames );

For more control, you can use the object oriented interface.

See also the tv command.

DESCRIPTION

Given a list of test scripts, source file names, directories and/or package names, attempts to find and execute the appropriate test scripts.

This (via the associated tv command) is useful when developing code or test scripts: just map "tv %" to a key in your editor and press it frequently (where "%" is your editor's macro for "the file being edited).

Before doing anything, this module identifies the working directory for the project by scanning the current directory and it's ancestors, stopping at the first directory that contains a "t" directory.

If an explicitly named item (other than POD files) cannot be tested, an exception is thrown.

Here is how each name passed in is treated:

test script

An explicitly mentioned test script is selected, no source files need be parsed. Names of test scripts are recognized by ending in ".t" and, if they exist on the filesystem, by being a file (and not a directory).

source file

Source files ending in ".pl", ".pm", or ".pod" are run through podchecker, then perl -cw before any tests are run. This forces useful POD and does a quick shortcircuit syntax check of the source files before the possibly length make test gets run.

Source files are parsed (very naively) looking for package declarations and for test scripts listed in special POD comments:

=for test_script foo.t bar.t
    baz.t

Also, all test scripts are parsed looking for use and require statements and for POD that looks like:

=for file lib/Foo.pm

or

=for package Foo

. All test scripts pertaining to a given file and any packages in it are then selected.

Before any test scripts are run, source files are run through podchecker and through perl -cw. The former is to check POD, something normal test suites don't do, and the latter is because running make test ... for a distribution with a lot of modules can be slow and I want to give per-module feedback ASAP.

The paths listed in =for file must be paths relative to the project root and not contain "..". Hmmm, they can also be absolute paths, but why would you do that?

Names of source files are recognized by not ending in ".t" and not looking like a package name or, if they do look like a package name, by existing on the filesystem.

directory

Directories are travered looking for files with the extensions ".t", ".pm", ".pod", or ".pl". These are then treated as though they had been explicitly named. Note that this notion of "looks like a source file" differs from that used when a source file is explicitly passed (where any extension other than .t may be used).

package name

If a name looks like a legal package name (Contains only word characters and "::" digraphs) and does not exist on the filesystem, then it is assumed to be a package name. In this case, all explicitly mentioned source files and test script files are scanned as normal, as well as those found by scanning the main project directory and (only) it's lib and t subdirectories. Files found there are not selected, but are used to determine what tests to run for a package.

.tvrc file

If a .tvrc file is found in a project's root directory, it is run just before any tests. This allows you to set important env. vars:

$ENV{DBI_USER}="barries";
$ENV{DBI_PASS}="yuck";

$tv->pure_perl = 1;

This support is experimental but should be ok for now. Options set here may be overridden on the command line.

FUNCTIONS

test_verbose( @names );
test_verbose( @names, \%options );

Shortcut for

my $tv = Test::Verbose->new( %options )->test( @names );

METHODS

new

Takes a list of options:

Debug

Runs the test scripts directly using perl -d. Causes ExtUtils to be ignored.

Dir

What directory to look for t/ and run make(1) in. Undefined causes the instance to search for a directory containing a directory named "t" in the current directory and its parents.

JustPrint

Print out the command to be executed.

ExtUtils

Don't use make test TEST_VERBOSE=1 ..., use perl '-MExtUtils::Command::MM' -e 'test_harness(1,\'lib\')' ... instead. Useful if you don't have a Makefile.PL; might not work on all versions of perl.

load_rc

Scans for and loads the .tvrc file.

NOTE: may be expanded in the future to load multiple RC files.

So far, only a few attributes are available, will add more as I need to.

For 100% pure perl modules, a common .tvrc is:

$tv->pure_perl = 1;

. And a way to shush tv from printing out all the good news is:

$tv->quiet = 1;
dir
my $dir = $tv->dir;
$tv->dir( undef );   ## clear old setting
$tv->dir( "foo" );   ## prevent chdir( ".." ) searching
$tv->dir = "foo";

Looks for t/ or lib/ in the current directory or in any parent directory. chdir()s up the directory tree until t/ is found, then back to the directory it started in, so make sure you have permissions to chdir() up and back.

Passing a Dir => $dir option to new prevents this method for searching for a name,

pure_perl
$tv->pure_perl = 1;
print $tv->pure_perl;
quiet
$tv->quiet = 1;
double_quiet
$tv->double_quiet = 1;
triple_quiet
$tv->triple_quiet = 1;
is_test_script
$self->is_test_script;         ## tests $_
$self->is_test_script( $name );

Returns true if the name looks like the name of a test script (ends in .t). File does not need to exist.

Overload this to alter Test::Verbose's perceptions.

is_pod_file
$self->is_pod_file;         ## tests $_
$self->is_pod_file( $name );

Returns true if the name looks like the name of a pod file (ends in .pod). File does not need to exist, but must be a file if it does.

Overload this to alter Test::Verbose's perceptions.

is_source_file
$self->is_source_file;         ## tests $_
$self->is_source_file( $name );

Returns true if the name looks like the name of a source file (ends in .pm, .pod or .pl). File does not need to exist, but must be a file if it does.

This is only used when traversing directory trees, otherwise a file name (ie not a package) is assumed to be a source file if it is not a test file.

Overload this to alter Test::Verbose's perceptions.

is_package
$self->is_test_script; ## tests $_
$self->is_test_script( $name );

Returns trues if the name looks like the name of a package (contains only /\w/ and "::") and is not a name that exists (ie ! -e).

Overload this to alter Test::Verbose's perceptions.

unhandled
$self->unhandled( @_ );

die()s with any unhandled names.

Overload this to alter the default.

look_up_scripts
my @scripts = $tv->look_up_test_scripts( @_ );

Looks up the scripts for any names that don't look like test scripts.

die()s if a non-test script cannot be found.

use =for tv dont_test to prevent this error.

All test scripts returned will have the form "t/foo.t", and the result is sorted. No test script name will be returned more than once.

test
$self->test( @test_scripts );

chdir()s to $self-dir> and exec()s make test.

ASSumptions and LIMITATIONS

  • Test scripts with spaces in their filenames will screw up, since these are interpolated in to a single, space delimited make(1) variable like so:

    make test TEST_VERBOSE=1 "TEST_FILES=t/spaced out name.t"

  • Your make must be called "make". I will alter this assumption as soon as I need this on Win32 again. Feel free to submit patches.

  • Speaking of which, although this module has a nod to portability, it has not been tested on platforms other than Unix, so there be dragons there. They should be easy to fix, so please patch away.

  • The source code scanners look for /^\s*(use|require)\s+([\w:])/ (in test scripts) and /^\s*package\s+(\S+);/, and so are easily fooled.

COPYRIGHT

Copyright 2002 R. Barrie Slaymaker, All Rights Reserver

LICENSE

You may use this module under the terms of the BSD, GNU, or Artistic licenses.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>