NAME

Dist::Zilla::Util::Test::KENTNL::dztest - Shared dist testing logic for easy dzil things

VERSION

version 1.005014

SYNOPSIS

use Test::More;
use Test::DZil qw( simple_ini );
use Dist::Zilla::Util::Test::KENTNL qw( dztest );

my $test = dztest;

## utility method.
$test->add_file( 'dist.ini', simple_ini( .... ));

## build the dist
# 1x subtest
$test->build_ok;

## assert prereqs are identical to the hash
## extracting them from distmeta
# 1x subtest
$test->prereqs_deeply( { } );

## Test for specific log messages by regex
# 1x subtest
#  - tests there are messages
#  - each regex must match a message
my @list = (
  [ $regex, $indepdent_reason ],
  [ $regex ],
);
$test->has_messages( $reason, \@list );

## Test for any deep structure addressed
## By a Data::DPath expression
# 1x subtest
#   - asserts the expression returns a result
#   - compares the structure against the expected one.
$test->meta_path_deeply(
    '/author/*/[1]',
    [ 'E. Xavier Ample <example@example.org>' ],
    'The 1st author is the example author emitted by simple_ini'
);

## Test for a file existing on the build side
## and return it if it exists.
my $file = $test->test_has_built_file('dist.ini');

METHODS

add_file

Add a file to the scratch directory to be built.

# ->add_file( $path, $string );
# ->add_file( \@path, $string );
$test->add_file('dist.ini', simple_ini() );
$test->add_file('lib/Foo.pm', $content );
$test->add_file([ 'lib','Foo.pm' ], $content );

build_ok

Build the dist safely, and report ok if the dist builds ok, spewing file listings via note

BAIL_OUT is triggered if any of add_file don't arrive in the intended location.

prereqs_deeply

Demand distmeta prereqs exactly match those specified.

$test->prereqs_deeply( { hash } );

This is just a more memorable version of

$test->meta_path_deeply('/prereqs/', { });

has_messages

Test that there are messages, and all the given rules match messages.

$test->has_messages( 'Some descriptor', [
   [ $regex, $description ],
   [ $regex, $description ],
]);

meta_path_deeply

$test->meta_path_deeply( $expression, $expected_data, $reason );

Uses $expression as a Data::DPath expression to pick a LIST of nodes from distmeta, and compare that LIST vs $expected_data

# Matches only the first author.
$test->meta_path_deeply('/author/*/[1]', ['SomeAuthorName <wadef@wath>'], $reason );

# Matches all authors
$test->meta_path_deeply('/author/*/*', ['SomeAuthorName <wadef@wath>','Author2', ..], $reason );

test_has_built_file

Test ( as in, Test::More::ok ) that a file exists in the dzil build output directory.

Also returns it if it exists.

$test->test_has_built_file('dist.ini');  # ok/fail

my $object = test->test_has_built_file('dist.ini'); # ok/fail + return

create_plugin

Create an instance of the named plugin and return it.

my $t = dztest();
$t->add_file('dist.ini', simple_ini( ... ));
my $plugin = $t->create_plugin('GatherDir' => { ignore_dotfiles => 1 });
# poke at $plugin here

Note: This lets you test plugins outside the requirement of inter-operating with dzil phases, but has the downside of not interacting with dzil phases, or even being *seen* by dzil phases.

But this is OK if you want to directly test a modules interface instead of doing it through the proxy of dzil

You can also subsequently create many such objects without requiring a dzil build penalty.

source_file

Re-fetch content added with add_file.

You probably want built_file.

$test->source_file( $path  );
$test->source_file( \@path );

Returns undef if the file does not exist.

if ( my $content = $test->source_file('dist.ini') ) {
  print $content->slurp_raw;
}

safe_build

Ensure the distribution is built safely, returns exceptions or undef.

if ( $test->safe_build ) {
  say "Failed build";
}

safe_configure

Construct the internal builder object safely. Returns exceptions or undef.

if( $test->configure ) { say "configure failed" }

built_file

Returns the named file if it exists in the build, undef otherwise.

my $file = $test->built_file('dist.ini');

note_tempdir_files

Recursively walk tempdir and note its contents.

note_builddir_files

Recursively walk builddir(output) and note its contents.

has_message

Assert there are messages, and this single message exists:

$test->has_message( $regex, $description );

run_command

Execute a Dist::Zilla command in the constructed scratch directory.

$test->run_command(['build','foo']);

The syntax is technically:

$test->run_command( $argv, $arg );

But I'm yet to work out the meaning of the latter.

ATTRIBUTES

configure

Construct the internal builder object.

$test->configure;

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric <kentnl@cpan.org>.

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

cpanm Dist::Zilla::Util::Test::KENTNL

perl -MCPAN -e shell
install Dist::Zilla::Util::Test::KENTNL