App::Y...:Tester(3pm)

💖 App::Yath::Tester — bestie's guide to testing yath 💖

(from the User Contributed Perl Documentation, and yes it's a 3pm page, we love a Perl module manual 🫶)

---

✨ NAME ✨

App::Yath::Tester — Tools for testing yath 🔥

---

🌸 DESCRIPTION 🌸

Okay so, this package is literally a lil toolbox of utilities that let you run yath from inside your tests, so you can vibe-check that it's actually behaving like it should. It's mostly used for integration testing of yath itself, and also for third party components. No cap. 👑

---

🎀 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. Two. Iconic behavior, truly. ✌️

$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 works, pick whichever speaks to you bestie. This one takes a string that should be a command name. 💫

• cli => \@ARGS
• args => \@ARGS

Either cli or args can be used — if you don't provide either one, an empty arrayref gets used instead, nbd. This argument takes an arrayref of arguments meant for 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 the arguments handed to yath BEFORE the command on the command line. Like, pre-game arguments. 🧚

$ yath [PRE_COMMAND] [COMMAND] [ARGS]

• env => \%ENV

Provide custom environment variable values to set before running the yath command. Give yath a whole lil wardrobe change. 👗

• encoding => $encoding_name

If you expect your yath command's output to be in a specific encoding, you can specify it here so the tool makes sure the $result->{output} text has been read properly. Gotta respect the encoding, fr fr. 🔤

• test => sub { ... }
• tests => sub { ... }
• subtest => sub { ... }

These 3 arguments are all aliases for the exact same thing, so only one should be used. The codeblock will be called with $result as the only argument. The codeblock will be run as a subtest. And if you also specify the exit argument, that check will happen in the same subtest too. Two birds, one subtest. 🐦

test => sub {
    my $result = shift;

    ... verify result ...
},

• exit => $integer

Verify that the yath command exited with the specified exit code. This check gets run in a subtest. And if you specified a custom subtest, then this check will appear to come from that subtest. Sneaky but cute. 🙈

• 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. So smart, so helpful. 🧠

So 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}. Catch it, hold it, keep it. 🫴

• log => $bool

Defaults to false.

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

• no_app_path => $bool

Defaults to false.

Normally -D=/path/to/lib is added to the yath command, where /path/to/lib is the path that 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. Just, like, raw-dogging the library path, be careful bestie 😭

• lib => [...]

This poorly named argument (their words, not mine 💀) lets you inject command line arguments between perl and yath in the command.

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

RESULT 🏆

The result hashref may contain the 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. Don't forget it or you'll be sitting there like "where's my log" 🫠

---

$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. A whole lil starter pack of green checkmarks. ✅✅✅

---

👑 SOURCE 👑

The source code repository for Test2-Harness can be found at http://github.com/Test-More/Test2-Harness/. Go star it, it's giving open source excellence. ⭐

---

🫶 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/

---

and that's the whole page bestie — this was perl v5.40.1, dated 2026-05-10, App::Y...:Tester(3pm) 💅 periodt, go write some tests 🎀