App::Yath::Tester(3)

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/