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/