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

NAME

Test::Uses

SYNOPSIS

use Test::More tests => $Num_Tests;
use Test::Uses;

uses_ok($myperlfile, 'strict', "$myperlfile is properly strict");
uses_ok($myperlfile, 'File::Spec', "$myperlfile uses File::Spec");
uses_ok($myperlfile, qr/^Test::/, "$myperlfile actually does some testing");
uses_ok($myperlfile, { -avoids => [qr/^Win32::/], 
                    -uses => ['strict', qr/^Test::/] },
  "$myperlfile does all sorts of stuff, and avoids Win32 modules");

avoids_ok($myperlfile, qr/^Win32::/, "Quick way of saying }
avoids_ok($myperlfile, ['bytes', qr/^Win32::/], "Quick way of saying we avoid grubby stuff

DESCRIPTION

This is a test helper module, so it is designed to be used in cooperation with other test modules, such as Test::Simple and Test::More.

The module helps you check through a bunch of code for references to modules you either (a) want to use, or (b) want to avoid. The module reads and parses the file (using PPI, and, therefore, dependencies of the file are not checked). the syntactic check has some advantages. Because no actual code is loaded, it is safe to use as a test.

One of the best reasons for using this, is to handle code where your production environment may limit use of modules. This test allows you to avoid modules that you know are going to cause problems, by adding test cases which fail when people write code that uses them.

Because pragmas are invoked similarly, you can also detect use of "bad" pragmas.

Note that a pragma turned off (e.g., "no bytes") still counts as using the pragma, and will be found as a use by this module. This seemed more sensible to me, as in virtually all cases, using "no" loads the component and requires it to function, and this is generally what you are trying to find using these tests.

Test::Uses is not the same as Test::use::ok or Test::More::use_ok, which checks that these modules can be use()d successfully.

FUNCTIONS

uses_ok($filename, $module, $testname);

This test succeeds of the passed file does use this particular module. This looks for a use statement referring to this module. The module specification can be one of the following:

  • A string module name

  • A regular expression value, based on the qr// quoting

  • An arrayref of multiple values, all of which should be satisfied

  • A hashref of specifications, keyed by -uses and -avoids. All the -uses specifications must be met, and none of the -avoids specifications must be present

avoids_ok($filename, $module, $testname);

A convenient shortcut for:

uses_ok($filename, {-avoids => $module}, $testname);

TODO

This module is based on PPI, and uses it to parse the text. This might well change at some point.

  • Add some handling for require, at least when the cases are obvious

  • Add some handling for test cases, such as use_ok

AUTHOR

Stuart Watt <stuart@morungos.com>

COPYRIGHT

Copyright 2010 by the authors.

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

SEE ALSO

PPI is used to parse the module.