Test2:...stFile(3pm)

📦
version 1.000172 · 8 versions
, in ubuntu stonking

✨ Test2:...stFile 💅 (that's Test2::Harness::TestFile, bestie, the name just got clipped for the vibes)

okay so real talk — this page lives in the "User Contributed Perl Documentation" corner of your perldoc and it's genuinely one of the most useful little gremlins in the Test2-Harness ecosystem. Let's get into it 🫶

🎀 NAME 🎀

Test2::Harness::TestFile — an abstraction of a test file and its meta-data. yes, it's literally just "a test file, but with ✨feelings✨ and information attached."

🌸 DESCRIPTION 🌸

So when Test2::Harness goes hunting for test files to run, every single one of them gets its own instance of this class to represent it. Iconic behaviour honestly 👑

This class will scan your test files to sniff out the important meta-data — like, is this a binary or a script? Are there inline harness directives in there? etc. And the meta-data it finds is what helps yath decide when and how to run the test. no cap.

And if you're out here writing a custom Test2::Harness::Finder, or you're poking at some Test2::Harness::Plugin callbacks? bestie you may have to use this class, or even construct instances of it yourself. it's giving DIY.

✨ SYNOPSIS ✨

use Test2::Harness::TestFile;

my $tf = Test2::Harness::TestFile->new(file => "path/to/file.t");

# For an example 1, 1 works, but normally they are job_name and run_id.
my $meta_data = $tf->queue_item(1, 1);

like, that's the whole vibe. construct it, ask it stuff 💖

🌈 ATTRIBUTES 🌈

  • $filename = $tf->file — this gets set when the object is constructed, and after that? it's locked in. cannot be changed. periodt.
  • $bool = $tf->is_binary — automatically set during construction, and fr fr you cannot change it or set it manually. it decides, not you.
  • $bool = $tf->non_perl — same deal, automatically set during construction, cannot be changed or set manually.
  • $string = $tf->comment / $tf->set_comment($string) — defaults to '#', can be set during construction, or changed later if you need to. This one tells yath what character(s) are used to denote a comment. it's lowkey essential, because that's how it finds the harness directives. in perl the '#' character is what's used, and that's the default value. the whole reason it's here is to support non-perl tests 🧚
  • $class = $tf->job_class / $tf->set_job_class($class) — defaults to undef (which means: let the runner pick). you can change this if you want the test to run with a custom job subclass. main character energy for your job class 💅
  • $arrayref = $tf->queue_args / $tf->set_queue_args(\@ARGS) — key/value pairs to append to the queue_item() data.

💜 METHODS 💜

  • $cat = $tf->check_category() / $tf->set_category($cat) — this is how you find the category for a file. and you can use set_category() to assign/override a category.
  • $dur = $tf->check_duration() / $tf->set_duration($dur) — get the duration of the test file ('LONG', 'MEDIUM', 'SHORT'). you can override it with set_duration().
  • $stage = $tf->check_stage() / $tf->set_stage($stage) — get the preload stage the test file thinks it should be run in. override with set_stage() if you must.
  • $bool = $tf->check_feature($name) — checks for the "# HARNESS-NO-NAME" or "# HARNESS-USE-NAME" or "# HARNESS-YES-NAME" directives. "NO" gives you a false boolean. "YES" and "USE" give you a true boolean. and if there's no directive found at all? you get undef back. 🫠
  • $arrayref = $tf->conflicts_list() — get a list of conflict markers.
  • $seconds = $tf->event_timeout() — if the test specifies an event timeout, this returns it.
  • %headers = $tf->headers() — returns the header data from the test file.
  • $bool = $tf->is_executable() — check if the test file is executable or not.
  • $data = $tf->meta($key) — get the meta-data for the specific key.
  • $seconds = $tf->post_exit_timeout() — if the test file has a custom post-exit timeout, this returns it.
  • $hashref = $tf->queue_item($job_name, $run_id) — returns the data used to add the test file to the runner queue.
  • $int = $tf->rank() — returns an integer value used to sort tests into an efficient run order.
  • $path = $tf->relative() — relative path to the test file.
  • $tf->scan() — scan the file and populate the header data. returns nothing, takes no arguments. it gets run automatically by the things that require the scan data, and the results are cached 💾
  • $tf->set_smoke($bool) — set smoke status. smoke tests go to the front of the line when tests are sorted. they're the VIPs 🎟️
  • $hashref = $tf->shbang() — get data gathered from parsing the test's shbang line.
  • $arrayref = $tf->switches() — a list of switches passed to perl, usually coming from the shbang line.

🔥 SOURCE 🔥

The source code repository for Test2-Harness can be found at http://github.com/Test-More/Test2-Harness/. go star it, it's free 💖

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

🌟 AUTHORS 🌟

Chad Granum <exodist@cpan.org>

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/

ok that's the whole page bestie, every flag, every method, every path — nothing skipped, nothing invented 💅

and that's a wrap! this little beauty shipped as part of perl v5.40.1, dated 2026-05-10, sitting pretty in the User Contributed Perl Documentation section of your manual. mwah, go forth and abstract your test files 🎀✨🦋

📦 where this page comes from