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.

perl v5.34.0                                       2022-06-13              Dist::Zilla::U...:KENTNL::dztest(3pm)