NAME

       App::Yath::Tester - Tools for testing yath

DESCRIPTION

       This package provides utilities for running yath from within tests to verify its behavior.
       This is primarily used for integration testing of yath and for third party components.

SYNOPSIS

           use App::Yath::Tester qw/yath/;

           my $result = yath(
               # Command and arguments
               command => 'test',
               args    => ['-pMyPlugin', 'path/to/test', ...],

               # Exit code we expect from yath
               exit => 0,

               # Subtest to verify results
               test => sub {
                   my $result = shift;

                   # Redundant since we have the exit check above
                   is($result->{exit}, 0, "Verify exit");

                   is($result->{output}, $expected_output, "Got the expected output from yath");
               },
           );

EXPORTS

       There are 2 exports from this module.

   $result = yath(...)
           my $result = yath(
               # Command and arguments
               command => 'test',
               args    => ['-pMyPlugin', 'path/to/test', ...],

               # Exit code we expect from yath
               exit => 0,

               # Subtest to verify results
               test => sub {
                   my $result = shift;

                   # Redundant since we have the exit check above
                   is($result->{exit}, 0, "Verify exit");

                   is($result->{output}, $expected_output, "Got the expected output from yath");
               },
           );

       ARGUMENTS

       cmd => $command
       command => $command
           Either 'cmd' or 'command' can be used. This argument takes a string that should be a
           command name.

       cli => \@ARGS
       args => \@ARGS
           Either 'cli' or 'args' can be used. If none are provided an empty arrayref is used.
           This argument takes an arrayref of arguments to the yath command.

               $ yath [PRE_COMMAND] [COMMAND] [ARGS]

       pre => \@ARGS
       pre_command => \@ARGS
           Either 'pre' or 'pre_command' can be used. An empty arrayref is used if none are
           provided. These are arguments provided to yath BEFORE the command on the command line.

               $ yath [PRE_COMMAND] [COMMAND] [ARGS]

       env => \%ENV
           Provide custom environment variable values to set before running the yath command.

       encoding => $encoding_name
           If you expect your yath command's output to be in a specific encoding you can specify
           it here to make sure the "$result->{output}" text has been read properly.

       test => sub { ... }
       tests => sub { ... }
       subtest => sub { ... }
           These 3 arguments are all aliases for the same thing, only one should be used.  The
           codeblock will be called with $result as the onyl argument. The codeblock will be run
           as a subtest. If you specify the 'exit' argument that check will also happen in the
           same subtest.

               test => sub {
                   my $result = shift;

                   ... verify result ...
               },

       exit => $integer
           Verify that the yath command exited with the specified exit code. This check will be
           run in a subtest. If you specify a custom subtest then this check will appear to come
           from that subtest.

       debug => $integer
           Output debug info in realtime, depending on the $integer value this may include the
           output from the yath command being run.

               0 - No debugging
               1 - Output the command and other action being taken by the tool
               2 - Echo yath output as it happens

       inc => $bool
           This defaults to true.

           When true the tool will look for a directory next to your test file with an identical
           name except that '.t' or '.t2' will be stripped from it. If that directory exists it
           will be added as a dev-lib to the yath command.

           If your test file is 't/foo/bar.t' then your yath command will look like this:

               $ yath -D=t/foo/bar [PRE-COMMAND] [COMMAND] [ARGS]

       capture => $bool
           Defaults to true.

           When true the yath output will be captured and put into "$result->{output}".

       log => $bool
           Defaults to false.

           When true yath will be instructed to produce a log, the log will be accessible via
           "$result->{log}". "$result->{log}" will be an instance of
           Test2::Harness::Util::File::JSONL.

       no_app_path => $bool
           Default to false.

           Normally "-D=/path/to/lib" is added to the yath command where '/path/to/lib' is the
           path the the lib dir App::Yath was loaded from.  This normally insures the correct
           version of yath libraries is loaded.

           When this argument is set to true the path is not added.

       lib => [...]
           This poorly named argument allows you to inject command line argumentes between "perl"
           and "yath" in the command.

               perl [LIB] path/to/yath [PRE-COMMAND] [COMMAND] [ARGS]

       RESULT

       The result hashref may containt he following fields depending on the arguments passed into
       "yath()".

       exit => $integer
           Exit value returned from yath.

       output => $string
           The output produced by the yath command.

       log => $jsonl_object
           An instance of Test2::Harness::Util::File::JSONL opened from the log file produced by
           the yath command.

           Note: By default no logging is done, you must specify the "log => 1" argument to
           enable it.

   $path = make_example_dir()
       This will create a temporary directory with 't', 't2', and 'xt' subdirectories each of
       which will contain a single passing test.

SOURCE

       The source code repository for Test2-Harness can be found at
       http://github.com/Test-More/Test2-Harness/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2020 Chad Granum <exodist7@gmail.com>.

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

       See http://dev.perl.org/licenses/