$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.