/ 
Test-Verbose-0.000_2
River stage zero No dependents
/ Test::Verbose

NAME

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

SYNOPSIS

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

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

FUNCTIONS

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

Shortcut for

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

METHODS

new

Takes a list of options:

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.

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

Looks for t/ 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,

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_source_file
$self->is_source_file;         ## tests $_
$self->is_source_file( $name );

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

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.

exec_make_test
$self->exec_make_test( @test_scripts );

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

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>