/ 
Test-StubGenerator-0.9.1
River stage zero No dependents
/ Test::StubGenerator

NAME

Test::StubGenerator - A simple module that analyzes a given source file and automatically generates t/*.t style tests for subroutines/methods it encounters.

VERSION

This documentation describes Test::StubGenerator version 0.9.0.

SYNOPSIS

use Test::StubGenerator;

my $stub = Test::StubGenerator->new(
  {
    file => '/path/to/MyModule.pm',
    tidy   => 1,
  }
);

print $stub->gen_testfile;

Or, from the command line (split for easier reading):

$ perl -MTest::StubGenerator -e '
> my $stub = Test::StubGenerator->new({ file => "Module.pm" });
> print $stub->gen_testfile;' > Module.t

DESCRIPTION

Test::StubGenerator is a module that attempts to analyze a given source file and automatically create testing stubs suitable for unit testing your code.

Test::StubGenerator make use of PPI in order to parse your code, looking for constructors and methods for modules (.pm), and subroutines for Perl script files (.pl).

Test::StubGenerator also runs the generated tests through Perl::Tidy before returning the text of the tests to you, though this can be disabled.

The idea for Test::StubGenerator grew out of a vim plugin I wrote that created test stub files in a very similar fashion. However, the line-based nature of vimscript quickly indicated that adding default parameters to the tests would prove to be an exercise in futility. As this was a feature I very much wanted to implement, I naturally turned to Perl, and PPI.

CONSTRUCTOR AND OPTIONS

$stub = Test::StubGenerator->new( { file => 'MyModule.pm' } );

Alternatively:

my %options = (
  file => '/path/to/Module.pm',
);

my $stub - Test::StubGenerator->new( \%options );

The full list of options:

file

Specify the path to the module or source code file for which you want to generate test stubs.

source

Alternatively, if the code for which you want to create tests is already in a scalar, pass a reference to that scalar as the named source argument.

tidy

Pass a true value to indicate that you'd like your generated tests run through Perl::Tidy before being returned. This is the default. Specify a false value to disable this feature. Note, this will by default use your ~/.perltidyrc file for formatting.

perltidyrc

If you have a particular perltidyrc file, specify its location in this option. Otherwise, the default is to use ~/.perltidyrc.

output

Pass a filename or an open filehandle to direct the output to. If this option isn't specified, then gen_testfile() returns the textual data directly.

out_dir

Specify a directory for which to save your generated test file.

METHODS

$stub->gen_testfile()

This is really the only method you need to know - after you've created a Test::StubGenerator object, simply call $teststub->gen_testfile().

DEPENDENCIES

Requires PPI and Perl::Tidy to be installed.

DIAGNOSTICS

"No code provided to Test::StubGenerator"

This means you've attempted to instantiate a new Test::StubGenerator object without specifying a file for Test::StubGenerator to analyze. Either pass a filename for Test::StubGenerator to analyze and create tests for, or a reference to a scalar containing the source code you wish to analyze.

"Unable to initialize PPI document"

This means that the source you've passed to Test::StubGenerator has major problems, and PPI is unable to parse it. At the very least, ensure your code can pass `perl -Mstrict -wc <filename>` before attempting to generate tests for it with Test::StubGenerator.

"No [ packages | subs ] found"

This is just a warning message indicating that Test::StubGenerator didn't find any of the items of the specified type in your code. The functionality that Test::StubGenerator supplies might be less than optimal if the code you're analyzing doesn't contain any subroutines. :)

"No output generated"

This means that Test::StubGenerator wasn't able to produce output in the desired format according to the options passed to the constructor. Possible issues are: 1) a directory doesn't exist, 2) you don't have permission to write to it, 3) the filesystem is full, 4) something is Very Broken.

"Can't call method "gen_testfile"..."

This probably means that you've trapped an exception with eval, but ignored it by not checking if $@ ($EVAL_ERROR) has been set, and your code has attempted to call gen_testfile() without ensuring that creating a Test::StubGenerator object has been sucessfully created and initialized.

"Can't open file for writing: Permission denied"

You have passed an output directory (out_dir) that you don't have permission to write to. Make sure you have the apropriate permission to the directory you wish to create test files in.

"Can't write to file '<filename>' in directory '<directory>'..."

This means that you have passed an output directory that doesn't exist. Please double check that any directory you specify in the named out_dir parameter to new() exist and are writeable by your effective user id.

SEE ALSO

PPI, Perl::Tidy

AUTHOR

Kent Cowgill, kent@c2group.net http://www.kentcowgill.org/

REQUESTS & BUGS

Please report any requests, suggestions, or bugs via the RT bug-tracking system at http://rt.cpan.org/.

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test::StubGenerator is the RT queue for Test::StubGenerator. Please check to see if your bug has already been reported.

ACKNOWLEDGEMENTS

Many thanks to the giants whose shoulders I stand upon, including Adam Kennedy, and Steve Hancock.

COPYRIGHT AND LICENSE

Copyright (c) 2007 by Kent Cowgill

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.