NAME

Perl::ToPerl6::TestUtils - Utility functions for testing new Transformers.

INTERFACE SUPPORT

This is considered to be a public module. Any changes to its interface will go through a deprecation cycle.

SYNOPSIS

    use Perl::ToPerl6::TestUtils qw(transform ptransform ftransform);

    my $code = '<<END_CODE';
    package Foo::Bar;
    $foo = frobulator();
    $baz = $foo ** 2;
    1;
    END_CODE

    # Critique code against all loaded transformers...
    my $perl_mogrify_config = { -necessity => 2 };
    my $transformation_count = transform( \$code, $perl_mogrify_config);

    # Critique code against one transformer...
    my $custom_transformer = 'Miscellanea::ProhibitFrobulation'
    my $transformation_count = ptransform( $custom_transformer, \$code );

    # Critique code against one filename-related transformer...
    my $custom_transformer = 'Modules::RequireFilenameMatchesPackage'
    my $transformation_count = ftransform( $custom_transformer, \$code, 'Foo/Bar.pm' );

DESCRIPTION

This module is used by Perl::ToPerl6 only for self-testing. It provides a few handy subroutines for testing new Perl::ToPerl6::Transformer modules. Look at the test programs that ship with Perl::ToPerl6 for more examples of how to use these subroutines.

EXPORTS

block_perlmogrifyrc()

If a user has a ~/.perlmogrifyrc file, this can interfere with testing. This handy method disables the search for that file -- simply call it at the top of your .t program. Note that this is not easily reversible, but that should not matter.

transform_with_transformations( $code_string_ref, $config_ref )

Test a block of code against the specified Perl::ToPerl6::Config instance (or undef for the default). Returns the transformations that occurred.

transform( $code_string_ref, $config_ref )

Test a block of code against the specified Perl::ToPerl6::Config instance (or undef for the default). Returns the number of transformations that occurred.

ptransform_with_transformations( $transformer_name, $code_string_ref, $config_ref )

Like transform_with_transformations(), but tests only a single transformer instead of the whole bunch.

ptransform( $transformer_name, $code_string_ref, $config_ref )

Like transform(), but tests only a single transformer instead of the whole bunch.

ftransform_with_transformations( $transformer_name, $code_string_ref, $filename, $config_ref )

Like ptransform_with_transformations(), but pretends that the code was loaded from the specified filename. This is handy for testing transformers like Modules::RequireFilenameMatchesPackage which care about the filename that the source derived from.

The $filename parameter must be a relative path, not absolute. The file and all necessary subdirectories will be created via File::Temp and will be automatically deleted.

ftransform( $transformer_name, $code_string_ref, $filename, $config_ref )

Like ptransform(), but pretends that the code was loaded from the specified filename. This is handy for testing transformers like Modules::RequireFilenameMatchesPackage which care about the filename that the source derived from.

The $filename parameter must be a relative path, not absolute. The file and all necessary subdirectories will be created via File::Temp and will be automatically deleted.

subtests_in_tree( $dir )

Searches the specified directory recursively for .run files. Each one found is parsed and a hash-of-list-of-hashes is returned. The outer hash is keyed on transformer short name, like Modules::RequireEndWithOne. The inner hash specifies a single test to be handed to ptransform() or ftransform(), including the code string, test name, etc. See below for the syntax of the .run files.

should_skip_author_tests()

Answers whether author tests should run.

get_author_test_skip_message()

Returns a string containing the message that should be emitted when a test is skipped due to it being an author test when author tests are not enabled.

starting_points_including_examples()

Returns a list of the directories contain code that needs to be tested when it is desired that the examples be included.

bundled_transformer_names()

Returns a list of Transformer packages that come bundled with this package. This functions by searching MANIFEST for lib/Perl/ToPerl6/Transformer/*.pm and converts the results to package names.

names_of_transformers_willing_to_work( %configuration )

Returns a list of the packages of transformers that are willing to function on the current system using the specified configuration.

.run file information

Testing a transformer follows a very simple pattern:

    * Transformer name
        * Subtest name
        * Optional parameters
        * Number of failures expected
        * Optional exception expected
        * Optional filename for code

Each of the subtests for a transformer is collected in a single .run file, with test properties as comments in front of each code block that describes how we expect Perl::ToPerl6 to react to the code. For example, say you have a transformer called Variables::ProhibitVowels:

    (In file t/Variables/ProhibitVowels.run)

    ## name Basics
    ## failures 1
    ## cut

    my $vrbl_nm = 'foo';    # Good, vowel-free name
    my $wango = 12;         # Bad, pronouncable name


    ## name Sometimes Y
    ## failures 1
    ## cut

    my $yllw = 0;       # "y" not a vowel here
    my $rhythm = 12;    # But here it is

These are called "subtests", and two are shown above. The beauty of incorporating multiple subtests in a file is that the .run is itself a (mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's color-coding still works, and it is much easier to work with the code and the POD.

If you need to pass any configuration parameters for your subtest, do so like this:

    ## parms { allow_y => '0' }

Note that all the values in this hash must be strings because that's what Perl::ToPerl6 will hand you from a .perlmogrifyrc.

If it's a TODO subtest (probably because of some weird corner of PPI that we exercised that Adam is getting around to fixing, right?), then make a ##TODO entry.

    ## TODO Should pass when PPI 1.xxx comes out

If the code is expected to trigger an exception in the transformer, indicate that like so:

    ## error 1

If you want to test the error message, mark it with /.../ to indicate a like() test:

    ## error /Can't load Foo::Bar/

If the transformer you are testing cares about the filename of the code, you can indicate that ftransform should be used like so (see ftransform for more details):

    ## filename lib/Foo/Bar.pm

The value of parms will get evaled and passed to ptransform(), so be careful.

In general, a subtest document runs from the ## cut that starts it to either the next ## name or the end of the file. In very rare circumstances you may need to end the test document earlier. A second ## cut will do this. The only known need for this is in t/Miscellanea/RequireRcsKeywords.run, where it is used to prevent the RCS keywords in the file footer from producing false positives or negatives in the last test.

Note that nowhere within the .run file itself do you specify the transformer that you're testing. That's implicit within the filename.

AUTHOR

Chris Dolan <cdolan@cpan.org> and the rest of the Perl::ToPerl6 team.

COPYRIGHT

Copyright (c) 2005-2011 Chris Dolan.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.