There is an ongoing outage on the primary CPAN mirror. It is possible to work around the issue by using MetaCPAN as a mirror.

 / 
PPIx-Regexp-0.089
River stage three • 9 direct dependents • 169 total dependents
/ My::Module::Test

NAME

My::Module::Test - support for testing PPIx::Regexp

SYNOPSIS

use lib qw{ inc };
use My::Module::Test;

parse   ( '/foo/' );
value   ( failures => [], 0 );
klass   ( 'PPIx::Regexp' );
choose  ( child => 0 );
klass   ( 'PPIx::Regexp::Token::Structure' );
content ( '' );
# and so on

DETAILS

This module is private to the PPIx-Regexp module. Its contents can be changed without warning. This was always the intent, and this paragraph should have been included in the POD much earlier than it actually was.

This module exports various subroutines in support of testing PPIx::Regexp. Most of these are tests, with Test::More doing the dirty work. A few simply set up data for tests.

The whole test rig works by parsing (or tokenizing) a regular expression, followed by a series of unit tests on the results of the parse. Each set of unit tests is performed by selecting an object to test using the choose or navigate subroutine, followed by the tests to be performed on that object. A few tests do not test parse objects, but rather the state of the system as a whole.

The following subroutines are exported:

cache_count

cache_count( 1 );

This test compares the number of objects in the new_from_cache cache to its argument, succeeding if they are equal. If no argument is passed, the default is 0.

choose

choose( 2 );  # For tokenizer
choose( child => 1, child => 2, type => 0 ); # For full parse

This subroutine does not itself represent a test. It chooses an object from the parse tree for further testing. If testing a tokenizer, the argument is the token number (from 0) to select. If testing a full parse, the arguments are the navigation methods used to reach the object to be tested, starting from the PPIx::Regexp object. The arguments to the methods are passed in an array reference, but if there is a single argument it can be passed as a scalar, as in the example.

klass

klass( 'PPIx::Regexp::Token::Structure' );

This test checks to see if the current object is of the given class, and succeeds if it is. If the current object is undef, the test fails.

This test was class, but that tends to conflict with object systems.

content

content( '\N{LATIN SMALL LETTER A}' );

This test checks to see if the content method of the current object is equal to the given string. If the current object is undef, the test fails.

cmp_ok

This subroutine is exported from Test::More.

count

count( 42 );

This test checks the number of objects returned by an operation that returns more than one object. It succeeds if the number of objects returned is equal to the given number.

This test is valid only after tokenize, or a choose or navigate whose argument list ends in one of

children => []
finish => []
start => []
type => []

different

different( $o1, $o2, 'Test name' );

This test compares two things, succeeding if they are different. References are compared by reference address and scalars by value (numeric or string comparison as appropriate). If the first argument is omitted it defaults to the current object.

dump_result

dump_result( tokens => 1, <<'EOD', 'Test tokenization dump' );
... expected dump here ...
EOD

This test performs the specified dump on the current object and succeeds if the result matches the expectation. The name of the test is the last argument, and the expected result is the next-to-last argument. All other arguments are passed to PPIx::Regexp::Dumper.

Well, almost all other arguments are passed to the dumper. You can specify --notest to skip the test. In this case the result of the last operation is dumped. PPIx::Regexp::Dumper is used if appropriate; otherwise you get a YAML dump if that is available, or a Data::Dumper dump if not. If no dumper class can be found, a diagnostic is produced. You can also specify --test, but this is the default. This option is removed from the argument list before the test name (etc) is determined.

equals

equals( $o1, $o2, 'Test name' );

This test compares two things, succeeding if they are equal. References are compared by reference address and scalars by value (numeric or string comparison as appropriate). If the first argument is omitted it defaults to the current object.

format_want

is $got, $want, 'Want ' . format_want( $want );

This convenience subroutine formats the wanted result. If an ARRAY reference, the contents are enclosed in parentheses.

false

false( significant => [] );

This test succeeds if the given method, with the given arguments, called on the current object, returns a false value.

finis

finis();

This test should be last in a series, and no references to parse objects should be held when it is run. It checks the number of objects in the internal %parent hash, and succeeds if it is zero.

invocant

invocant();

Returns the current object.

navigate( snext_sibling => [] );

Like choose, this is not a test, but selects an object for testing. Unlike choose, selection starts from the current object, not the top of the parse tree.

parse

parse( 's/foo/bar/g' );

This test parses the given regular expression into a PPIx::Regexp object, and succeeds if a PPIx::Regexp object was in fact generated.

If you specify argument --notest, the parse is done but no test is performed. You would do this if you expected the parse to fail (e.g. you are testing error handling). You can also explicitly specify --test, but this is the default.

All other arguments are passed to the PPIx::Regexp constructor.

plan

This subroutine is exported from Test::More.

ppi

ppi( '$foo' );

This test calls the current object's ppi() method, and checks to see if the content of the returned PPI::Document is equal to the given string. If the current object is undef or does not have a ppi() method, the test fails.

raw_width

raw_width( 0, undef, "Some title" );

This tests invokes the raw_width() method on the current object. The arguments are the expected minimum width, the expected maximum width, and a test title. The title defaults to the class and content of the current object.

Two tests are actually run. The titles of these will have ' raw minimum width' and ' raw maximum width' appended. This subroutine returns true if both tests pass.

result

my $val = result();

This subroutine returns the result of the most recent operation that actually produces one. It should be called immediately after the operation, mostly because I have not documented all the subroutines that produce a result.

tokenize

tokenize( 'm/foo/smx' );

This test tokenizes the given regular expression into a PPIx::Regexp::Tokenizer object, and succeeds if a PPIx::Regexp::Tokenizer object was in fact generated.

If you specify argument --notest, the parse is done but no test is performed. You would do this if you expected the parse to fail (e.g. you are testing error handling). You can also explicitly specify --test, but this is the default.

If you specify argument --notokens, the tokenizer is built, but the tokens are not extracted. You would do this when you want a subsequent operation to call tokens(). You can also explicitly specify --tokens, but this is the default.

All other arguments are passed to the PPIx::Regexp::Tokenizer constructor.

true

true( significant => [] );

This test succeeds if the given method, with the given arguments, called on the current object, returns a true value.

value

value( max_capture_number => [], 3 );

This test succeeds if the given method, with the given arguments, called on the current object, returns the given value. If the wanted value is a reference, is_deeply() is used for the comparison; otherwise is() is used.

If the current object is undefined, the given method is called on the intended initial class, otherwise there would be no way to test the errstr() method.

The result of the method call is accessable via the result() subroutine.

An optional fourth argument specifies the name of the test. If this is omitted or specified as undef, a name is generated describing the arguments.

width

width( 0, undef, "Some title" );

This tests invokes the width() method on the current object. The arguments are the expected minimum width, the expected maximum width, and a test title. The title defaults to the class and content of the current object.

Two tests are actually run. The titles of these will have ' minimum width' and ' maximum width' appended. This subroutine returns true if both tests pass.

SUPPORT

Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=PPIx-Regexp, https://github.com/trwyant/perl-PPIx-Regexp/issues, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2009-2023, 2025 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.