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

📦
version 1.000172 · 8 versions
, in ubuntu stonking

💖 App::Yath::Command::test — Run tests, bestie ✨

okay so first things first: the manual name is App::Yath::Command::test(3pm), and it's literally the Run tests command for yath. Periodt. 💅

📛 NAME

App::Yath::Command::test — Run tests 🏃‍♀️💨

📖 DESCRIPTION

okay so this yath command? It's literally the default command, bestie. It runs all the test files for your current project. If you don't specify any test files, it goes looking for the 't' and 't2' directories, plus the 'test.pl' file. 👀

And when you give it directories? It's always recursive. No cap. 🌳

By default it adds 'lib', 'blib/arch' and 'blib/lib' to the perl path for you — and it does this after any -I's, okay? You can specify -l if you just want lib, or -b if you just want the blib paths. If you specify both -l and -b, both get added in the order you specify (and their order relative to any -I options is preserved too). If you don't specify either, they get added in this order: -I's, lib, blib/lib, blib/arch. You can also add --no-lib and --no-blib to avoid both. 🫶

Any command line argument that is not an option? That's treated as a test file or directory of test files to be run. Simple as that. ✨

If you wish to specify the ARGV for tests you may append them after '::'. This is mainly useful for Test::Class::Moose and similar tools. And EVERY test run will get the same ARGV. So like, no cap, same ARGV for everyone. 💀

🚀 USAGE

$ yath [YATH OPTIONS] test [COMMAND OPTIONS]

🛠️ YATH OPTIONS

👩‍💻 Developer

  • --dev-lib, --dev-lib=lib, -D, -D=lib, -Dlib, --no-dev-lib — Add paths to @INC before loading ANYTHING. This is what you use if you are developing yath or yath plugins to make sure the yath script finds the local code instead of the installed versions of the same code. You can provide an argument (-Dfoo) to provide a custom path, or you can just use -D without and arg to add lib, blib/lib and blib/arch. Can be specified multiple times ✨

🌍 Environment

  • --persist-dir ARG, --persist-dir=ARG, --no-persist-dir — Where to find persistence files. 📁
  • --persist-file ARG, --persist-file=ARG, --pfile ARG, --pfile=ARG, --no-persist-file — Where to find the persistence file. The default is /{system-tempdir}/project-yath-persist.json. If no project is specified then it will fall back to the current directory. If the current directory is not writable it will default to /tmp/yath-persist.json which limits you to one persistent runner on your system. iykyk 💛
  • --project ARG, --project=ARG, --project-name ARG, --project-name=ARG, --no-project — This lets you provide a label for your current project/codebase. This is best used in a .yath.rc file. This is necessary for a persistent runner. 🏷️

🔍 Finder Options

  • --finder MyFinder, --finder +Test2::Harness::Finder::MyFinder, --no-finder — Specify what Finder subclass to use when searching for files/processing the file list. Use the "+" prefix to specify a fully qualified namespace, otherwise Test2::Harness::Finder::XXX namespace is assumed. 🔎

🆘 Help and Debugging

  • --show-opts, --no-show-opts — Exit after showing what yath thinks your options mean. 👀
  • --version, -V, --no-version — Exit after showing a helpful usage message. 📜

🔌 Plugins

  • --no-scan-plugins, --no-no-scan-plugins — Normally yath scans for and loads all App::Yath::Plugin::* modules in order to bring in command-line options they may provide. This flag will disable that. This is useful if you have a naughty plugin that is loading other modules when it should not. 🙈
  • --plugins PLUGIN, --plugins +App::Yath::Plugin::PLUGIN, --plugins PLUGIN=arg1,arg2,..., --plugin PLUGIN, --plugin +App::Yath::Plugin::PLUGIN, --plugin PLUGIN=arg1,arg2,..., -pPLUGIN, --no-plugins — Load a yath plugin. Can be specified multiple times 💅

⚙️ COMMAND OPTIONS

📦 Collector Options

  • --max-open-jobs 18, --no-max-open-jobs — Maximum number of jobs a collector can process at a time, if more jobs are pending their output will be delayed until the earlier jobs have been processed. (Default: double the -j value) 🧵
  • --max-poll-events 1000, --no-max-poll-events — Maximum number of events to poll from a job before jumping to the next job. (Default: 1000) 📊

🎨 Cover Options

  • --cover-aggregator ByTest, --cover-aggregator ByRun, --cover-aggregator +Custom::Aggregator, --cover-agg ByTest, --cover-agg ByRun, --cover-agg +Custom::Aggregator, --no-cover-aggregator — Choose a custom aggregator subclass. 🧮
  • --cover-class ARG, --cover-class=ARG, --no-cover-class — Choose a Test2::Plugin::Cover subclass. 🎭
  • --cover-dirs ARG, --cover-dirs=ARG, --cover-dir ARG, --cover-dir=ARG, --no-cover-dirs — NO DESCRIPTION - FIX ME 😭 (bestie literally no description, fix me). Can be specified multiple times
  • --cover-exclude-private, --no-cover-exclude-private, --cover-files, --no-cover-files — Use Test2::Plugin::Cover to collect coverage data for what files are touched by what tests. Unlike Devel::Cover this has very little performance impact (About 4% difference). 🔥
  • --cover-from path/to/log.jsonl, --cover-from http://example.com/coverage, --cover-from path/to/coverage.jsonl, --no-cover-from — This can be a test log, a coverage dump (old style json or new jsonl format), or a url to any of the previous. Tests will not be run if the file/url is invalid. 🚫
  • --cover-from-type json, --cover-from-type jsonl, --cover-from-type log, --no-cover-from-type — File type for coverage source. Usually it can be detected, but when it cannot be you should specify. "json" is old style single-blob coverage data, "jsonl" is the new by-test style, "log" is a logfile from a previous run. 📄
  • --cover-manager My::Coverage::Manager, --no-cover-manager — Coverage 'from' manager to use when coverage data does not provide one. 🧑‍💼
  • --cover-maybe-from path/to/log.jsonl, --cover-maybe-from http://example.com/coverage, --cover-maybe-from path/to/coverage.jsonl, --no-cover-maybe-from — This can be a test log, a coverage dump (old style json or new jsonl format), or a url to any of the previous. Tests will coninue if even if the coverage file/url is invalid. (Yes, it says coninue, not my typo, bestie 💀)
  • --cover-maybe-from-type json, --cover-maybe-from-type jsonl, --cover-maybe-from-type log, --no-cover-maybe-from-type — Same as "from_type" but for "maybe_from". Defaults to "from_type" if that is specified, otherwise auto-detect. 🔄
  • --cover-metrics, --no-cover-metrics, --cover-types ARG, --cover-types=ARG, --cover-type ARG, --cover-type=ARG, --no-cover-types — NO DESCRIPTION - FIX ME 😭 (again, bestie, no description). Can be specified multiple times
  • --cover-write, --cover-write=coverage.jsonl, --cover-write=coverage.json, --no-cover-write — Create a json or jsonl file of all coverage data seen during the run (This implies --cover-files). ✍️

🖥️ Display Options

  • --color, --no-color — Turn color on, default is true if STDOUT is a TTY. 🌈
  • --hide-runner-output, --no-hide-runner-output — Hide output from the runner, showing only test output. (See Also truncate_runner_output) 🙈
  • --no-final-table, --no-no-final-table — When printing final results, don't use table-style display. 📋
  • --no-wrap, --no-no-wrap — Do not do fancy text-wrapping, let the terminal handle it. 📏
  • --progress, --no-progress — Toggle progress indicators. On by default if STDOUT is a TTY. You can use --no-progress to disable the 'events seen' counter and buffered event pre-display. ⏳
  • --quiet, -q, --no-quiet — Be very quiet. Can be specified multiple times 🤫
  • --renderers +My::Renderer, --renderers Renderer=arg1,arg2,..., --renderer +My::Renderer, --renderer Renderer=arg1,arg2,..., --no-renderers — Specify renderers, (Default: "Formatter=Test2"). Use "+" to give a fully qualified module name. Without "+" "Test2::Harness::Renderer::" will be prepended to your argument. Can be specified multiple times. If the same key is listed multiple times the value lists will be appended together. 🎨
  • --show-times, -T, --no-show-times — Show the timing data for each job. ⏱️
  • --term-width 80, --term-width 200, --term-size 80, --term-size 200, --no-term-width — Alternative to setting $TABLE_TERM_SIZE. Setting this will override the terminal width detection to the number of characters specified. 📐
  • --truncate-runner-output, --no-truncate-runner-output — Only show runner output that was generated after the current command. This is only useful with a persistent runner. ✂️
  • --verbose, -v, --no-verbose — Be more verbose. Can be specified multiple times 🗣️

🔍 Finder Options

  • --changed path/to/file, --no-changed — Specify one or more files as having been changed. Can be specified multiple times 🔄
  • --changed-only, --no-changed-only — Only search for tests for changed files (Requires a coverage data source, also requires a list of changes either from the --changed option, or a plugin that implements changed_files() or changed_diff()). 🔍
  • --changes-diff path/to/diff.diff, --no-changes-diff — Path to a diff file that should be used to find changed files for use with --changed-only. This must be in the same format as git diff -W --minimal -U1000000. 📝
  • --changes-exclude-file path/to/file, --no-changes-exclude-file — Specify one or more files to ignore when looking at changes. Can be specified multiple times 🚫
  • --changes-exclude-loads, --no-changes-exclude-loads — Exclude coverage tests which only load changed files, but never call code from them. (default: off) 📂
  • --changes-exclude-nonsub, --no-changes-exclude-nonsub — Exclude changes outside of subroutines (perl files only) (default: off). 🧩
  • --changes-exclude-opens, --no-changes-exclude-opens — Exclude coverage tests which only open() changed files, but never call code from them. (default: off) 🚪
  • --changes-exclude-pattern '(apple|pear|orange)', --no-changes-exclude-pattern — Ignore files matching this pattern when looking for changes. Your pattern will be inserted unmodified into a $file =~ m/$pattern/ check. Can be specified multiple times 🍎🍐🍊
  • --changes-filter-file path/to/file, --no-changes-filter-file — Specify one or more files to check for changes. Changes to other files will be ignored. Can be specified multiple times 🎯
  • --changes-filter-pattern '(apple|pear|orange)', --no-changes-filter-pattern — okay so when you're only running tests for files that changed, this narrows down WHICH files even get checked. Only files matching your pattern get looked at, periodt. Your pattern gets dropped unmodified into a $file =~ m/$pattern/ check, so write it like a real regex bestie. 💅

Can be specified multiple times.

  • --changes-include-whitespace, --no-changes-include-whitespace — count changed lines that are whitespace only as actual changes (default: off). Turn it on if you're the kind of icon who cares about trailing spaces fr fr.
  • --changes-plugin Git, --changes-plugin +App::Yath::Plugin::Git, --no-changes-plugin — which plugin gets to figure out what files changed. That's it, that's the whole job. 🌸
  • --default-at-search ARG, --default-at-search=ARG, --no-default-at-search — the default file/dir search to use when AUTHOR_TESTING is set. Defaults to ./xt. This AT search only kicks in if you didn't name any files on the command line, so if you typed stuff it's like… ignored, bestie. ✨

Can be specified multiple times.

  • --default-search ARG, --default-search=ARG, --no-default-search — the default file/dir search, defaults to ./t, ./t2, and test.pl. Same rule: it's only used if you didn't specify files at the command line. 🦋

Can be specified multiple times.

  • --durations file.json, --durations http://example.com/durations.json, --no-durations — point at a json file or url that holds a hash where the keys are relative test filenames and the values are 'SHORT', 'MEDIUM', or 'LONG'. This overrides the durations written in the file headers. And no cap: if the durations file or url doesn't work, an exception will be thrown. 😭
  • --durations-threshold ARG, --durations-threshold=ARG, --Dt ARG, --Dt=ARG, --no-durations-threshold — only go fetch duration data if you're running at least this many tests. Default is (-j value + 1). 👑
  • --exclude-file t/nope.t, --no-exclude-file — exclude a file from testing. Not today, t/nope.t. 🙈

Can be specified multiple times.

  • --exclude-list file.txt, --exclude-list http://example.com/exclusions.txt, --no-exclude-list — point at a file or url that has a newline-separated list of test file names to exclude. Start a line with a # and it gets commented out (this exists for compatibility with Test2::Aggregate list files, iykyk). 📋

Can be specified multiple times.

  • --exclude-pattern t/nope.t, --no-exclude-pattern — exclude a pattern from testing, matched using m/$PATTERN/. ✂️

Can be specified multiple times.

  • --extension ARG, --extension=ARG, --ext ARG, --ext=ARG, --no-extension — tell it which filename extensions count as valid tests. Default: t and t2. 💖

Can be specified multiple times.

  • --maybe-durations file.json, --maybe-durations http://example.com/durations.json, --no-maybe-durations — point at a json file or url with a hash of relative test filenames as keys and 'SHORT', 'MEDIUM', or 'LONG' as values. Overrides the durations listed in the file headers. An exception will be thrown if the durations file or url does not work. 🌈
  • --no-long, --no-no-long — do not run tests whose duration flag is set to 'LONG'. Bye bye long bois. 🏃‍♀️
  • --only-long, --no-only-long — only run tests whose duration flag is set to 'LONG'. Long bois only, we're committing. 🔥
  • --rerun, --rerun=path/to/log.jsonl, --rerun=plugin_specific_string, --no-rerun — re-run tests from a previous run, pulled from a log file (or the last log file). Plugins can intercept this — for example YathUIDB will grab a run UUID and derive which tests to re-run from that. 🌀
  • --rerun-all, --rerun-all=path/to/log.jsonl, --rerun-all=plugin_specific_string, --no-rerun-all — re-run all tests from a previous run, from a log file (or the last log file). Same deal: plugins can intercept, like YathUIDB grabbing a run UUID and deriving tests from it. 💫
  • --rerun-failed, --rerun-failed=path/to/log.jsonl, --rerun-failed=plugin_specific_string, --no-rerun-failed — re-run the failed tests from a previous run, from a log file (or the last log file). Plugins can intercept, e.g. YathUIDB grabbing a run UUID and deriving tests to re-run from that. 💀➡️✨
  • --rerun-missed, --rerun-missed=path/to/log.jsonl, --rerun-missed=plugin_specific_string, --no-rerun-missed — run the missed tests from a previously aborted/stopped run, from a log file (or the last log file). Plugins can intercept, like YathUIDB grabbing a run UUID and deriving tests to re-run from that. 🫶
  • --rerun-modes failed,missed,..., --rerun-modes all, --rerun-modes failed, --rerun-modes missed, --rerun-modes passed, --rerun-modes retried, --rerun-mode failed,missed,..., --rerun-mode all, --rerun-mode failed, --rerun-mode missed, --rerun-mode passed, --rerun-mode retried, --no-rerun-modes — pick which test categories you wanna run. Choose your fighter. 🥊

Can be specified multiple times.

  • --rerun-passed, --rerun-passed=path/to/log.jsonl, --rerun-passed=plugin_specific_string, --no-rerun-passed — re-run the passed tests from a previous run, from a log file (or the last log file). Plugins can intercept, like YathUIDB grabbing a run UUID and deriving tests to re-run from that. 🎀
  • --rerun-plugin Foo, --rerun-plugin +App::Yath::Plugin::Foo, --no-rerun-plugin — which plugin(s) should be used for rerun. It'll fall back to other plugins if the listed ones decline the value — this is just used to set an order of priority. 👑 (typo in the original, we keep it, no cap)

Can be specified multiple times.

  • --rerun-retried, --rerun-retried=path/to/log.jsonl, --rerun-retried=plugin_specific_string, --no-rerun-retried — re-run the retried tests from a previous run, from a log file (or the last log file). Plugins can intercept, such as YathUIDB grabbing a run UUID and deriving tests to re-run from that. 🔁
  • --search ARG, --search=ARG, --no-search — a list of tests and test directories to use instead of the default search paths. Lowkey though? Usually you just list these as plain command line arguments, no --search prefix needed. 🧚

Can be specified multiple times.

  • --show-changed-files, --no-show-changed-files — print out a list of changed files if any are found. 🔍

🎀 Formatter Options 🎀

  • --formatter ARG, --formatter=ARG, --no-formatter — NO DESCRIPTION - FIX ME 😭 the docs did us dirty here, that's literally all it says, no cap.
  • --qvf, --no-qvf — [Q]uiet, but [V]erbose on [F]ailure. It hides all output from tests when they pass (except saying they passed), but if a test fails then ALL output from that test gets verbosely dumped on you. Main character behavior honestly. 💅
  • --show-job-end, --no-show-job-end — show output when a job ends. (Default: on) 🏁
  • --show-job-info, --no-show-job-info — show the job configuration when a job starts. (Default: off, unless -vv) ⭐
  • --show-job-launch, --no-show-job-launch — show output for the start of a job. (Default: off unless -v) 🚀
  • --show-run-info, --no-show-run-info — show the run configuration when a run starts. (Default: off, unless -vv) 🌟

🐙 Git Options 🐙

  • --git-change-base master, --git-change-base HEAD^, --git-change-base df22abe4, --no-git-change-base — find files changed by all commits in the current branch, starting from the most recent and stopping when it hits a commit that's also present in the history of the branch/commit you specified as the change base. Detecting those changed files fr fr. 🌿

🆘 Help and Debugging 🆘

  • --dummy, -d, --no-dummy — dummy run, do not actually execute anything. It's giving rehearsal, not performance. 🙈

Can also be set with the following environment variables: T2_HARNESS_DUMMY

  • --help, -h, --no-help — exit after showing help information. 🫶
  • --interactive, -i, --no-interactive — use interactive mode: 1 test at a time, and stdin gets forwarded to it. One on one time with your tests. 💖
  • --keep-dirs, --keep_dir, -k, --no-keep-dirs — do not delete directories when done. Super useful if you wanna go poke around the directories that the various commands used. 🔍
  • --procname-prefix ARG, --procname-prefix=ARG, --no-procname-prefix — add a prefix to all proc names (the ones you'd see in ps). 🏷️
  • --summary, --summary=/path/to/summary.json, --no-summary — write out a summary json file. If you don't give a path, 'summary.json' is used. The .json extension gets added automatically if you omit it. 📝

📜 Logging Options 📜

  • --bzip2, --bz2, --bzip2_log, -B, --no-bzip2 — use bzip2 compression when writing the log. This option implies -L. The .bz2 prefix is added to the log file name for you. 🗜️
  • --gzip, --gz, --gzip_log, -G, --no-gzip — use gzip compression when writing the log. This option implies -L. The .gz prefix is added to the log file name for you. 🗜️✨
  • --log, -L, --no-log — turn on logging. That's it. That's the whole vibe. 📖
  • --log-dir ARG, --log-dir=ARG, --no-log-dir — specify a log directory. If you don't, it'll fall back to the system temp dir. 📁
  • --log-file ARG, --log-file=ARG, -F ARG, -F=ARG, --no-log-file — specify the name of the log file. This option implies -L. 🗂️
  • --log-file-format ARG, --log-file-format=ARG, --lff ARG, --lff=ARG, --no-log-file-format — specify the format for automatically-generated log files. It gets overridden by --log-file if you gave one. This option implies -L. (Default: $YATH_LOG_FILE_FORMAT, if that is set, or else "%!P%Y-%m-%d~%H:%M:%S~%!U~%!p.jsonl"). It's a string where percent-escape sequences get replaced as per POSIX::strftime. The following special escape sequences also get replaced:
    • %!P : Project name followed by a ~, if a project is defined, otherwise empty string
    • %!U : the unique test run ID
    • %!p : the process ID
    • %!S : the number of seconds since local midnight UTC

Can also be set with the following environment variables: YATH_LOG_FILE_FORMAT, TEST2_HARNESS_LOG_FORMAT

📧 Notification Options 📧

  • --notify-email foo@example.com, --no-notify-email — email the test results to the specified email address(es). 💌

Can be specified multiple times.

  • --notify-email-fail foo@example.com, --no-notify-email-fail — email the failing results to the specified email address(es). 💔📩

Can be specified multiple times.

  • --notify-email-from foo@example.com, --no-notify-email-from — if any email gets sent at all, this is who it will be from. 🫶
  • --notify-email-owner, --no-notify-email-owner — email the owner of broken test files upon failure. Add `# HARNESS-META-OWNER foo@example.com` to the top of a test file to give it an owner. 🏷️
  • --notify-no-batch-email, --no-notify-no-batch-email — usually owner failures get sent as a single batch at the end of testing. Toggle this to send failures as they happen instead. ⚡
  • --notify-no-batch-slack, --no-notify-no-batch-slack — so normally when an owner test fails, all those failures get bundled up and sent as one single batch right at the end of the whole run. Flip this on and nope, they get yeeted out one by one the second they happen. real-time tea ☕
  • --notify-slack '#foo', --notify-slack '@bar', --no-notify-slack — send the results to a slack channel and/or a user. And yes bestie, you can drop this one more than once 💬
  • --notify-slack-fail '#foo', --notify-slack-fail '@bar', --no-notify-slack-fail — same vibe but only the failing results get sent to the slack channel and/or user. Also stackable, specify it as many times as you want 😭
  • --notify-slack-owner, --no-notify-slack-owner — when tests fail, ping the slack channels/users that were listed up in the test meta-data. like, tell the actual owner, not just the group chat 👑
  • --notify-slack-url https://hooks.slack.com/..., --no-notify-slack-url — point at a specific API endpoint so slack webhooks will actually work.
  • --notify-text ARG, --notify-text=ARG, --message ARG, --message=ARG, --msg ARG, --msg=ARG, --no-notify-text — tack a lil custom text snippet onto your email and/or slack notifications. your own little signature, if you will 💅
  • --notify-text-module ARG, --notify-text-module=ARG, --message_module ARG, --message_module=ARG, --no-notify-text-module — hand the job over to a specific module and let it generate the messages for the emails and/or slack. outsourcing, but make it chic.

✨ Run Options ✨

  • --author-testing, -A, --no-author-testing — this flips the AUTHOR_TESTING environment variable to true. author mode activated, no cap 🧚
  • --dbi-profiling, --no-dbi-profiling — bring in Test2::Plugin::DBIProfile so you can hoover up all that sweet sweet database profiling data.
  • --env-var VAR=VAL, -EVAR=VAL, -E VAR=VAL, --no-env-var — set environment variables that apply every time a test runs. stacking allowed, do it as many times as your heart desires 🌈
  • --event-uuids, --uuids, --no-event-uuids — pull in Test2::Plugin::UUID inside your tests (default: on).
  • --fields name:details, --fields JSON_STRING, -f name:details, -f JSON_STRING, --no-fields — add your own custom data to the harness run. specify it as many times as you like 💖
  • --input ARG, --input=ARG, --no-input — this is the input string that gets used as standard input for ALL the tests. see also: --input-file.
  • --input-file ARG, --input-file=ARG, --no-input-file — use the file you name as standard input for ALL the tests.
  • --io-events, --no-io-events — bring Test2::Plugin::IOEvents inside tests so every single print turns into a test2 event (default: off).
  • --link 'https://travis.work/builds/42', --link 'https://jenkins.work/job/42', --link 'https://buildbot.work/builders/foo/builds/42', --no-link — hand people one or more links they can follow to find out more about this run. stack 'em up, multiple times is fine 🔗
  • --load ARG, --load=ARG, --load-module ARG, --load-module=ARG, -m ARG, -m=ARG, --no-load — load a module inside every test (after the fork happens). heads up: the import method does not get called. and yep, multiple times works 🫶
  • --load-import Module, --load-import Module=import_arg1,arg2,..., --loadim Module, --loadim Module=import_arg1,arg2,..., -M Module, -M Module=import_arg1,arg2,..., --no-load-import — load a module in each test (after fork), and this time import is called. you can list it multiple times, and if the same key shows up more than once the value lists just get appended together. merger girlie behavior 💅
  • --mem-usage, --no-mem-usage — use Test2::Plugin::MemUsage inside tests (default: on).
  • --retry ARG, --retry=ARG, -r ARG, -r=ARG, --no-retry — run every job that failed a second time. ⚠️ NOTE: --retry=1 means your failing tests get attempted twice! read that twice bestie.
  • --retry-isolated, --retry-iso, --no-retry-isolated — if this is true then any job retries happen in isolation, like as though you'd set -j1. one at a time, no chaos 🙈
  • --run-id, --id, --no-run-id — set a specific run-id. (Default: a UUID)
  • --test-args ARG, --test-args=ARG, --no-test-args — arguments to pass in as @ARGV for every test that runs. you can also supply these the easier way using the '::' argument separator. multiple times = fine ✨
  • --stream, --no-stream — use the stream formatter (default is on).
  • --tap, --TAP, ----no-stream, --no-tap — okay so real talk: the TAP format is lossy and clunky 😭 Test2::Harness normally uses a newer streaming format to receive test results. but there are some old/legacy tests where that newer thing causes problems, and in those cases setting --TAP or --no-stream can save you.

🏃 Runner Options 🏃

  • --abort-on-bail, --no-abort-on-bail — if a bail-out shows up, abort all the testing (default: on).
  • --blib, -b, --no-blib — (Default: include if it exists) stick blib/lib and blib/arch into your module path.
  • --cover, --cover=-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl, --no-cover — use Devel::Cover to calculate test coverage. heads up, this disables forking. if you don't specify any args, these are the ones that get used:
-silent,1,+ignore,^t/,+ignore,^t2/,+ignore,^xt,+ignore,^test.pl
  • --dump-depmap, --no-dump-depmap — when you're using staged preload, dump the depmap for each stage out as json files.
  • --event-timeout SECONDS, --et SECONDS, --no-event-timeout — kill a test if no output shows up within the timeout period. (Default: 60 seconds). pro tip: drop the # HARNESS-NO-TIMEOUT comment at the top of a test file to disable timeouts on a per-test basis. this is the thing that stops a hung test from just hanging there forever, so like, respect it 💀
  • --fail-on-resource-skip, --no-fail-on-resource-skip — treat resource-skipped tests as failures instead of skips. when this is on, tests that would've been skipped because a resource wasn't available get marked as failing instead.
  • --include ARG, --include=ARG, -I ARG, -I=ARG, --no-include — add a directory to your include paths. multiple times allowed 💖
  • --job-count 4, --job-count 8:2, --jobs 4, --jobs 8:2, -j4, -j8:2, --no-job-count — set how many concurrent jobs run. add a :# if you also want to designate multiple slots per test. so 8:2 means 8 slots, but each test gets 2 slots, so 4 tests run concurrently. and tests can find their concurrency assignment sitting in the T2_HARNESS_MY_JOB_CONCURRENCY environment variable. (yes the original really does say "assignemnt", we're keeping it, character.) you can also set this with these environment variables: YATH_JOB_COUNT, T2_HARNESS_JOB_COUNT, HARNESS_JOB_COUNT.
  • --lib, -l, --no-lib — (Default: include if it exists) include lib in your module path.
  • --nytprof, --no-nytprof — use Devel::NYTProf on the tests. this sets addpid=1 for you. works with or without fork, so it's flexible like that 🦋
  • --post-exit-timeout SECONDS, --pet SECONDS, --no-post-exit-timeout — stop waiting post-exit once the timeout period passes. (Default: 15 seconds) so here's the thing: some tests fork and let the parent exit before they've written out all their output. if Test2::Harness spots an incomplete plan after the test exits, it keeps watching for more events until the timeout period runs out. drop the # HARNESS-NO-TIMEOUT comment at the top of a test file to disable timeouts per-test.
  • --preload-threshold ARG, --preload-threshold=ARG, --Pt ARG, --Pt=ARG, -W ARG, -W=ARG, --no-preload-threshold — only preload if at least N tests are gonna run. sometimes a full preload takes longer than just running the tests normally, so this lets you set a minimum number of test jobs that have to be happening before preload kicks in. no effect on a persistent runner. default is 0, which means always preload. always. all the time. periodt 🌟
  • --preloads ARG, --preloads=ARG, --preload ARG, --preload=ARG, -P ARG, -P=ARG, --no-preloads — preload a module before running tests. yes, multiple times, love that for you 💜
  • --resource-timeout SECONDS, --rt SECONDS, --no-resource-timeout — abort the entire test run if no tests have managed to start for SECONDS seconds while there are still pending tests and nothing running. super handy when a resource class is broken and keeps promising that a resource will become available, which means yath would otherwise never ever finish. (Default: 0, meaning no timeout.)
  • --resource Port, --resource +Test2::Harness::Runner::Resource::Port, -R Port, --no-resource — use a resource module to hand out resource assignments to individual tests. stackable, multiple times is fine ✨
  • --runner-id ARG, --runner-id=ARG, --no-runner-id — runner ID (usually a generated uuid).
  • --shared-jobs-config .sharedjobslots.yml, --shared-jobs-config relative/path/.sharedjobslots.yml, --shared-jobs-config /absolute/path/.sharedjobslots.yml, --no-shared-jobs-config — where to go looking for a shared slot config file. if you hand it a filename with no path on it, yath searches the current directory and every parent directory for that name. detective mode 🔍
  • --slots-per-job 2, -x2, --no-slots-per-job — sets how many slots each job will use (default 1). normally this gets set by the :# inside -j#:#. you can also set it with this environment variable: T2_HARNESS_JOB_CONCURRENCY.
  • --switch ARG, --switch=ARG, -S ARG, -S=ARG, --no-switch — pass the switch you name along to perl for every test. ⚠️ not compatible with preload. multiple times, sure 💅
  • --tlib, --no-tlib — (Default: off) include t/lib in your module path.
  • --unsafe-inc, --no-unsafe-inc — so perl is removing . from @INC as a security concern. this option keeps things from breaking for now (said with love and also a lil fear). you can also set it with this environment variable: PERL_USE_UNSAFE_INC.
  • --use-fork, --fork, --no-use-fork — (default: on, except on windows) normally tests run by forking, which is what makes stuff like preloading possible. turning this off kills that behavior globally (and it's not compatible with preloading). it's slower too, so honestly it's better to tag the misbehaving tests with the # HARNESS-NO-PRELOAD comment in their header and only disable forking for those tests. sacrifice not the many for the few 💀 you can also set this with these environment variables: !T2_NO_FORK, T2_HARNESS_FORK, !T2_HARNESS_NO_FORK, YATH_FORK, !YATH_NO_FORK.
  • --use-timeout, --timeout, --no-use-timeout — (default: on) turn timeouts on or off.

🌸 Workspace Options 🌸

  • --clear, -C, --no-clear — clear out the work directory if it's not already empty. fresh start energy 🧼
  • --tmp-dir ARG, --tmp-dir=ARG, --tmpdir ARG, --tmpdir=ARG, -t ARG, -t=ARG, --no-tmp-dir — use a specific temp directory (Default: use the system temp dir).
  • Can also be set with the following environment variables: T2_HARNESS_TEMP_DIR, YATH_TEMP_DIR, TMPDIR, TEMPDIR, TMP_DIR, TEMP_DIR
  • --workdir ARG, --workdir=ARG, -w ARG, -w=ARG, --no-workdir — sets the work directory, bestie. Default is a brand new temp directory, so if you don't say anything it'll just make one for you. 🗂️
    • Also settable with these environment variables: T2_WORKDIR, YATH_WORKDIR

✨ YathUI Options ✨

okay this whole block is about talking to your Yath-UI setup — it's the cute little dashboard situation, and every single one of these bad boys has a --no- version that turns it off. 💅

  • --yathui-api-key ARG, --yathui-api-key=ARG, --no-yathui-api-key — your Yath-UI API key. ngl you literally don't need this if your Yath-UI instance is set to single-user, so skip it if that's you. 🔑
  • --yathui-coverage, --no-yathui-coverage — polls coverage data from Yath-UI so it can figure out which tests should actually run for the files you changed. girl math, but for tests. 🧮
  • --yathui-durations, --no-yathui-durations — polls duration data from Yath-UI to help order your tests efficiently. fast ones first, main character energy. ⏱️
  • --yathui-grace, --no-yathui-grace — normally if yath can't connect to yath-ui it just throws an error. turn this on and it fails gracefully instead: you get a warning, but things keep going. very "we move" of it. 🫶
  • --yathui-long-duration 10, --no-yathui-long-duration — the minimum duration length, in seconds, before a test gets bumped from MEDIUM to LONG. default is 10. ⌛
  • --yathui-medium-duration 5, --no-yathui-medium-duration — the minimum duration length, in seconds, before a test goes from SHORT to MEDIUM. default is 5. ⏳
  • --yathui-mode summary, --yathui-mode qvf, --yathui-mode qvfd, --yathui-mode complete, --no-yathui-mode — picks the upload mode, and the default is 'qvfd'. ✨
  • --yathui-project ARG, --yathui-project=ARG, --no-yathui-project — the Yath-UI project your test results get filed under. 🏷️
  • --yathui-retry, --no-yathui-retry — how many times to try an operation before giving up. Can be specified multiple times, so you can be as stubborn as you want. 🔁
  • --yathui-upload, --no-yathui-upload — uploads the log to Yath-UI. 📤
  • --yathui-url http://my-yath-ui.com/..., --uri http://my-yath-ui.com/..., --no-yathui-url — the Yath-UI url. 🌐

🌈 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 royalty 👑

👑 MAINTAINERS 👑

  • Chad Granum <exodist@cpan.org>

💜 AUTHORS 💜

  • Chad Granum <exodist@cpan.org>

Copyright 2026 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!! you made it to the end, I'm so proud 🥹 this gorgeous thing came from perl v5.40.1, dated 2026-05-10, and it lives under the name App::Y...::test(3pm). go forth and run some tests, you absolute icon 🦋💖

📦 where this page comes from