NAME

Test::Output - Test the output to STDOUT and STDERR your tests produce

SYNOPSIS

use Test::Output;

my &test-code = sub {
    say 42;
    note 'warning!';
    say "After warning";
};

# Test code's output using exact match ('is')
output-is   &test-code, "42\nwarning!\nAfter warning\n", 'testing output';
stdout-is   &test-code, "42\nAfter warning\n",  'testing stdout';
stderr-is   &test-code, "warning!\n", 'testing stderr';

# Test code's output using regex ('like')
output-like &test-code, /42.+warning.+After/, 'testing output (regex)';
stdout-like &test-code, /42/, 'testing stdout (regex)';
stderr-like &test-code, /^ "warning!\n" $/, 'testing stderr (regex)';

# Test code's silentness
no-output { my $a = 42 }, 'did not generate any output';
no-stdout { my $a = 42 }, 'did not generate any output on STDOUT';
no-stderr { my $a = 42 }, 'did not generate any output on STDERR';

# Just capture code's output and do whatever you want with it
is output-from( &test-code ), "42\nwarning!\nAfter warning\n";
is stdout-from( &test-code ), "42\nAfter warning\n";
is stderr-from( &test-code ), "warning!\n";

DESCRIPTION

The Test::Output distribution provides a number of test subroutines that allow one to capture the output (STDOUT / STDERR / or both) of the execution of a Callable and evaluate that output for some criteria.

SELECTIVE IMPORTING

use Test::Output <output-is>;  # only import "output-is"

By default all functions are exported. But you can limit this to the functions you actually need by specifying the names in the use statement.

To prevent name collisions and/or import any subroutine with a more memorable name, one can use the "original-name:known-as" syntax. A semi-colon in a specified string indicates the name by which the subroutine is known in this distribution, followed by the name with which it will be known in the lexical context in which the use command is executed.

use Test::Output <output-is:ois>;  # import "output-is" as "oisp"
ois { say "foo" }, "foo\n", 'output matched';

EXPORTED SUBROUTINES

"is" tests

output-is

output-is { say 42; note 43; say 44 }, "42\n43\n44\n",
 'Merged output from STDOUT/STDERR looks fine!';

Uses is function from Test module to test whether the combined STDERR/STDOUT output from the execution of a Callable matches the given string. Takes an optional test description.

stdout-is

stdout-is { say 42; note 43; say 44 }, "42\n44\n",
  'STDOUT looks fine!';

Same as output-is, except tests STDOUT only.

stderr-is

stderr-is { say 42; note 43; say 44 }, "43\n",
  'STDERR looks fine!';

Same as output-is, except tests STDERR only.

"like" tests

output-like

output-like { say 42; note 43; say 44 }, /42 .+ 43 .+ 44/,
  'Merged output from STDOUT/STDERR matches the regex!';

Uses like function from Test module to test whether the combined STDERR / STDOUT output from the execution of a Callable matches the given Regex. Takes an optional test description.

stdout-like

stdout-like { say 42; note 43; say 44 }, /42 \n 44/,
  'STDOUT matches the regex!';

Same as output-like, except tests STDOUT only.

stderr-like

stderr-like { say 42; note 43; say 44 }, /^ 43\n $/,
  'STDERR matches the regex!';

Same as output-like, except tests STDERR only.

Output Capture

output-from

my $output = output-from { say 42; note 43; say 44 };
say "Captured $output from our program!";

is $output, "42\nwarning!\nAfter warning\n",
  'captured merged STDOUT/STDERR look fine';

Captures and returns merged STDOUT / STDERR output from the execution of a given Callable.

stdout-from

my $stdout = stdout-from { say 42; note 43; say 44 };
say "Captured $stdout from our program!";

is $stdout, "42\nAfter warning\n",
  'captured STDOUT looks fine';

Same as output-from, except captures STDOUT only.

stderr-from

my $stderr = stderr-from { say 42; note 43; say 44 };
say "Captured $stderr from our program!";

is $stderr, "warning\n",
  'captured STDERR looks fine';

Same as , except captures STDERR only.

test-output-verbosity

    sub test-output-verbosity (Bool :$on, Bool :$off) returns Str;

# turn verbosity on
test-output-verbosity(:on);

my $output = output-from { do-something-interactive() };
# test output will now displayed during the test

# turn verbosity off
test-output-verbosity(:off);

Display the code's output while the test code is executed. This can be very useful for author tests that require you to enter input based on the output.

You can switch verbosity on or off with the <:on> and <:off> named arguments.

CAVEATS

The Test::Output logic operates by changing the dynamic variables $*OUT and $*ERR, which is what Raku's standard output functions use. This logic does not apply to any output generated by external programs using run or shell: they have their own way of capturing output.

AUTHORS

Zoffix Znet
JJ Merelo
Elizabeth Mattijsen

Source can be located at: https://github.com/lizmat/Test-Output . Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.