--- name: "App::Yath::Tester" section: "3pm" platform: "linux" package: "libtest2-harness-perl" version: "1.000158-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/App::Yath::Tester" --- # App::Yath::Tester(3pm) Tools for testing yath ## 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 \ ## AUTHORS - Chad Granum \ ## COPYRIGHT Copyright 2020 Chad Granum \. 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/*