NAME

Test::Perl::ToPerl6::Transformer - A framework for testing your custom Transformers

SYNOPSIS

use Test::Perl::ToPerl6::Transformer qw< all_transformers_ok >;

# Assuming .run files are inside 't' directory...
all_transformers_ok()

# Or if your .run files are in a different directory...
all_transformers_ok( '-test-directory' => 'run' );

# And if you just want to run tests for some polices...
all_transformers_ok( -transformers => ['Some::Transformer', 'Another::Transformer'] );

# If you want your test program to accept short Transformer names as
# command-line parameters...
#
# You can then test a single transformer by running
# "perl -Ilib t/transformer-test.t My::Transformer".
my %args = @ARGV ? ( -transformers => [ @ARGV ] ) : ();
all_transformers_ok(%args);

DESCRIPTION

This module provides a framework for function-testing your custom Perl::ToPerl6::Transformer modules. Transformer testing usually involves feeding it a string of Perl code and checking its behavior. In the old days, those strings of Perl code were mixed directly in the test script. That sucked.

NOTE: This module is alpha code -- interfaces and implementation are subject to major changes. This module is an integral part of building and testing Perl::ToPerl6 itself, but you should not write any code against this module until it has stabilized.

IMPORTABLE SUBROUTINES

all_transformers_ok('-test-directory' => $path, -transformers => \@transformer_names)

Loads all the *.run files beneath the -test-directory and runs the tests. If -test-directory is not specified, it defaults to t/. -transformers is an optional reference to an array of shortened Transformer names. If -transformers specified, only the tests for Transformers that match one of the m/$TRANSFORMER_NAME/imx will be run.

CREATING THE *.run FILES

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.

BUGS AND CAVEATS AND TODO ITEMS

Add transformer_ok() method for running subtests in just a single TODO file.

Can users mark this entire test as TODO or SKIP, using the normal mechanisms?

Allow us to specify the nature of the failures, and which one. If there are 15 lines of code, and six of them fail, how do we know they're the right six?

Consolidate code from Perl::ToPerl6::TestUtils and possibly deprecate some functions there.

Write unit tests for this module.

Test that we have a t/*/*.run for each lib/*/*.pm

AUTHOR

Jeffrey Goff <drforr@pobox.com>

AUTHOR EMERITUS

Andy Lester, Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2015 Jeffrey Goff, all rights reserved.

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.