Test::...GplArt(3pm)

📦
version 0.0306 · 2 versions
, in fedora 43

💖 Test::...GplArt 💖

okay bestie so this is the 3pm page for Test::...GplArt, and it lives in the User Contributed Perl Documentation section. it's the GPL/Artistic-licensed chunk of Test::Run::Core's code, and yes we are gonna read the WHOLE thing together. grab a snack 🍓

✨ NAME ✨

Test::Run::Core_GplArt — it's the GPL/Artistic-licensed code of Test::Run::Core. that's it, that's the name, slay 💅

🌸 SYNOPSIS 🌸

use Test::Run::Obj;

my $tester = Test::Run::Obj->new({'test_files' => \@test_files});
$tester->runtests();

🦋 DESCRIPTION 🦋

STOP! genuinely stop, bestie ✋ if all you wanna do is write a test script, consider using Test::Simple. Test::Run::Core is the module that reads the output from Test::Simple, Test::More and other modules based on Test::Builder. you do not need to know about Test::Run::Core to use those modules. no cap.

so what does it do? Test::Run::Core runs tests and expects the output from the test in a certain format. that format is called TAP, the Test Anything Protocol. it's defined in Test::Harness::TAP. iykyk 💜

"$tester-"runtests()> runs all the testscripts named as arguments and checks standard output for the expected strings in TAP format.

Test::Run::Obj is an applicative derived class of Test::Run::Core that gives you a programmer API for running and analyzing the output of TAP files. and if you're calling from the command line, go look at Test::Run::CmdLine. periodt.

💧 Taint mode 💧

Test::Run will honor the -T or -t in the #! line on your test files. so if you begin a test with:

#!perl -T

the test will be run with taint mode on. iconic. 🔥

😭 Failure 😭

when tests fail, analyze the summary report:

t/base..............ok
t/nonumbers.........ok
t/ok................ok
t/test-harness......ok
t/waterloo..........dubious
        Test returned status 3 (wstat 768, 0x300)
DIED. FAILED tests 1, 3, 5, 7, 9, 11, 13, 15, 17, 19
        Failed 10/20 tests, 50.00% okay
Failed Test  Stat Wstat Total Fail  Failed  List of Failed
-----------------------------------------------------------------------
t/waterloo.t    3   768    20   10  50.00%  1 3 5 7 9 11 13 15 17 19
Failed 1/5 test scripts, 80.00% okay. 10/44 subtests failed, 77.27% okay.

so in this lil scenario everything passed but t/waterloo.t. it failed 10 of 20 tests and exited with a non-zero status, indicating something dubious happened. 👀

the columns in the summary report mean:

  • Failed Test — the test file which failed.
  • Stat — if the test exited with non-zero, this is its exit status.
  • Wstat — the wait status of the test.
  • Total — total number of tests expected to run.
  • Fail — number which failed, either from not ok or because they never ran.
  • Failed — percentage of the total tests which failed.
  • List of Failed — a list of the tests which failed. successive failures may be abbreviated (ie. 15-20 to indicate that tests 15, 16, 17, 18, 19 and 20 failed).

🎀 Functions 🎀

Test::Run currently only has one interface function, here it is. one single function, main character energy fr fr 👑

runtests

my $allok = $self->runtests();

this runs all the given @test_files and divines whether they passed or failed based on their output to STDOUT (details above ⬆️). it prints out each individual test which failed along with a summary report and a how long it all took.

it returns true if everything was ok. otherwise it will die() with one of the messages in the DIAGNOSTICS section. so watch out 😭

💜 EXPORT 💜

None. nothing. zero. empty. as the youths say, no thoughts, head empty 🙈

⭐ DIAGNOSTICS ⭐

  • "All tests successful.\nFiles=%d, Tests=%d, %s" — if all tests are successful some statistics about the performance are printed. cute! 🌈
  • "FAILED tests %s\n\tFailed %d/%d tests, %.2f%% okay." — for any single script that has failing subtests, statistics like the above are printed.
  • "Test returned status %d (wstat %d)" — scripts that return a non-zero exit status, both "$? >> 8" and $? are printed in a message similar to the above.
  • "Failed 1 test, %.2f%% okay. %s"
  • "Failed %d/%d tests, %.2f%% okay. %s" — if not all tests were successful, the script dies with one of the above messages.
  • "FAILED--Further testing stopped: %s" — if a single subtest decides that further testing will not make sense, the script dies with this message.

🌈 ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS 🌈

Test::Run sets these before executing the individual tests.

  • HARNESS_ACTIVE — this is set to a true value. it allows the tests to determine if they are being executed through the harness or by any other means.
  • HARNESS_VERSION — this is the version of Test::Run.

🫶 EXAMPLE 🫶

TODO: FIXME

here's how Test::Run tests itself:

$ cd ~/src/devel/Test-Harness
$ perl -Mblib -e 'use Test::Run qw(&runtests $verbose);
  $verbose=0; runtests @ARGV;' t/*.t
Using /home/schwern/src/devel/Test-Harness/blib
t/base..............ok
t/nonumbers.........ok
t/ok................ok
t/test-harness......ok
All tests successful.
Files=4, Tests=24, 2 wallclock secs ( 0.61 cusr + 0.41 csys = 1.02 CPU)

ate. no crumbs. 💅

🧚 SEE ALSO 🧚

the included prove utility for running test scripts from the command line, Test and Test::Simple for writing test scripts, Benchmark for the underlying timing routines, and Devel::Cover for test coverage analysis. go read all of them bestie, they're all bangers 💖

💀 TODO 💀

the to-do list is LONG and honestly it's giving "group project where one person does everything" 😭 but here's every single item:

  • Provide a way of running tests quietly (ie. no printing) for automated validation of tests. This will probably take the form of a version of runtests() which rather than printing its output returns raw data on the state of the tests. (Partially done in Test::Run::Straps)
  • Document the format.
  • Fix HARNESS_COMPILE_TEST without breaking its core usage.
  • Figure a way to report test names in the failure summary.
  • Rework the test summary so long test names are not truncated as badly. (Partially done with new skip test styles)
  • Add option for coverage analysis.
  • Trap STDERR.
  • Implement Straps total_results()
  • Remember exit code
  • Completely redo the print summary code.
  • Implement Straps callbacks. (experimentally implemented)
  • Straps->analyze_file() not taint clean, don't know if it can be
  • Fix that damned VMS nit.
  • HARNESS_TODOFAIL to display TODO failures
  • Add a test for verbose.
  • Change internal list of test results to a hash.
  • Fix stats display when there's an overrun.
  • Fix so perls with spaces in the filename work.
  • Keeping whittling away at _run_all_tests()
  • Clean up how the summary is printed. Get rid of those damned formats.

🙈 BUGS 🙈

HARNESS_COMPILE_TEST currently assumes it's run from the Perl source directory.

please use the CPAN bug ticketing system at <http://rt.cpan.org/>. you can also mail bugs, fixes and enhancements to "<bug-test-harness" at "rt.cpan.org>".

Copyright 2002-2005 by Michael G Schwern "<schwern at pobox.com>", Andy Lester "<andy at petdance.com>".

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

see <http://www.perl.com/perl/misc/Artistic.html>.

and that's the whole page bestie, you read it all, I'm so proud 🥹 this was perl v5.42.0, dated 2025-07-25, and yes it's still out here in the Test::...GplArt(3pm) section of the User Contributed Perl Documentation. slay, mwah, go run some tests 💋✨

📦 where this page comes from