App::Y...status(3pm)
π App::Yath::Command::status π
okay so real quick, before we dive in β this page is filed under App::Y...status(3pm), which is the fancy manual-name for App::Yath::Command::status, and it lives in the User Contributed Perl Documentation corner of the 3pm section. That's the whole header, we're done with the boring part, let's go π«Ά
πΈ NAME πΈ
App::Yath::Command::status β Status info and process lists for the runner
β¨ DESCRIPTION β¨
This command hands you the health details and a full process list for the runner. Like a vibe check but for your test runner, no cap. π
π¦ USAGE π¦
$ yath [YATH OPTIONS] status [COMMAND OPTIONS]
π YATH OPTIONS π
π οΈ Developer
--dev-lib,--dev-lib=lib,-D,-D=lib,-Dlib,--no-dev-libβ Adds paths to@INCbefore loading ANYTHING. This is the one you reach for when you're developing yath or yath plugins, because it makes sure the yath script finds your local code instead of the installed versions of that same code. You can pass an argument (-Dfoo) to give a custom path, or just rawdog-Dwith no arg to addlib,blib/libandblib/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. And if the current directory is not writable, it defaults to/tmp/yath-persist.jsonβ which limits you to one persistent runner on your system. One. Single. Runner. π--project ARG,--project=ARG,--project-name ARG,--project-name=ARG,--no-projectβ This lets you provide a label for your current project/codebase. Best used in a.yath.rcfile. 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 theTest2::Harness::Finder::XXXnamespace is assumed (iykyk).
π 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 allApp::Yath::Plugin::*modules in order to bring in command-line options they may provide. This flag disables that. Super useful if you have a naughty plugin that is loading other modules when it should not, and we do not stan that behaviour π«--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 π
π 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 aTest2::Plugin::Coversubclass.--cover-dirs ARG,--cover-dirs=ARG,--cover-dir ARG,--cover-dir=ARG,--no-cover-dirsβ NO DESCRIPTION - FIX ME. (bestie, I'm not gatekeeping, the docs literally say that π)
Can be specified multiple times.
--cover-exclude-private,--no-cover-exclude-private,--cover-files,--no-cover-filesβ UseTest2::Plugin::Coverto collect coverage data for what files are touched by what tests. UnlikeDevel::Cover, this has very little performance impact (About 4% difference). Yes, 4%. Basically free. Obsessed.--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.--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.
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 Alsotruncate_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-progressto 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--changedoption, or a plugin that implementschanged_files()orchanged_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 asgit 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 onlyopen()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β Specify a pattern for change checking. When only running tests for changed files this will limit which files are checked for changes. Only files that match this pattern will be checked. Your pattern will be inserted unmodified into a$file =~ m/$pattern/check.
Can be specified multiple times.
--changes-include-whitespace,--no-changes-include-whitespaceβ Include changed lines that are whitespace only (default: off)--changes-plugin Git,--changes-plugin +App::Yath::Plugin::Git,--no-changes-pluginβ What plugin should be used to detect changed files.--default-at-search ARG,--default-at-search=ARG,--no-default-at-searchβ Specify the default file/dir search when'AUTHOR_TESTING'is set. Defaults to'./xt'. The default AT search is only used if no files were specified at the command line.
Can be specified multiple times.
--default-search ARG,--default-search=ARG,--no-default-searchβ Specify the default file/dir search. defaults to'./t','./t2', and'test.pl'. The default search is only used if no files were specified at the command line.
Can be specified multiple times.
--durations file.json,--durations http://example.com/durations.json,--no-durationsβ point this at a json file or a url holding a hash where the keys are relative test filenames and the values are'SHORT','MEDIUM', or'LONG'β¨ It overrides the durations listed up in the file headers. If that durations file or url doesn't work? an exception gets thrown, no hesitation, no mercy π--durations-threshold ARG,--durations-threshold=ARG,--Dt ARG,--Dt=ARG,--no-durations-thresholdβ only bother fetching duration data if you're running at least this many tests. Default is-jvalue + 1 πΈ--exclude-file t/nope.t,--no-exclude-fileβ exclude a file from testing. You can say it multiple times π«Ά--exclude-list file.txt,--exclude-list http://example.com/exclusions.txt,--no-exclude-listβ point at a file or url with a newline separated list of test file names to exclude. Start a line with a#and it gets commented out (for compatibility with Test2::Aggregate list files, cute). Also repeatable as many times as your heart desires β¨--exclude-pattern t/nope.t,--no-exclude-patternβ exclude a pattern, matched usingm/$PATTERN/. Repeatable, multiple times, go off π--extension ARG,--extension=ARG,--ext ARG,--ext=ARG,--no-extensionβ tell it which test filename extensions are valid. Default:tandt2π Repeatable.--maybe-durations file.json,--maybe-durations http://example.com/durations.json,--no-maybe-durationsβ literally the same vibe as--durations: a json file or url with a hash of relative test filenames as keys and'SHORT','MEDIUM', or'LONG'as values, overriding the durations in the file headers. And yeah, if the file or url doesn't work, an exception gets thrown π--no-long,--no-no-longβ do NOT run tests that have their duration flag set to'LONG'π ββοΈ--only-long,--no-only-longβ ONLY run the tests whose duration flag is'LONG'π--rerun,--rerun=path/to/log.jsonl,--rerun=plugin_specific_string,--no-rerunβ re-run tests from a previous run, from a log file (or the last log file). Plugins can intercept this, like YathUIDB, which grabs a run UUID and derives the 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 the tests from a previous run, from a log file (or the last log file). Same plugin intercept situation: YathUIDB can grab a run UUID and derive tests to re-run 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). Yep, plugins can intercept β YathUIDB, run UUID, derives tests to re-run, you know the drill π--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 to run π― Repeatable, 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 this, such as YathUIDB, grabbing a run UUID and deriving tests to re-run from it π¦--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 π Repeatable, 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 it, like YathUIDB, which will grab a run UUID and derive 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. Usually you can just list these as plain command line arguments without the--searchprefix. Repeatable, multiple times πΈ--show-changed-files,--no-show-changed-filesβ print out a list of changed files, if any get found π
π Formatter Options π
--formatter ARG,--formatter=ARG,--no-formatterβ NO DESCRIPTION - FIX ME π (I'm not making anything up, bestie, the docs literally say that.)--qvf,--no-qvfβ [Q]uiet, but [V]erbose on [F]ailure π Hide all output from tests when they pass, except for saying they passed. But if a test fails? ALL output from the test gets verbosely dumped out. Iconic.--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 the files changed by all commits on the current branch, from most recent, stopping when you hit a commit that's also present in the history of the branch/commit you named as the change base π
π οΈ Help and Debugging π οΈ
--dummy,-d,--no-dummyβ a dummy run, it does not actually execute anything π
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, with stdin forwarded to it π§--keep-dirs,--keep_dir,-k,--no-keep-dirsβ do not delete directories when you're done. Super useful if you want to go inspect the directories used for the various commands π--procname-prefix ARG,--procname-prefix=ARG,--no-procname-prefixβ add a prefix to all proc names (as seen byps) π·οΈ--summary,--summary=/path/to/summary.json,--no-summaryβ write out a summary json file. If you don't give a path,'summary.json'gets used. The.jsonextension is 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.bz2prefix is added to the log file name for you π--gzip,--gz,--gzip_log,-G,--no-gzipβ use gzip compression when writing the log. This implies-Ltoo. And the.gzprefix gets added to the log file name for you π--log,-L,--no-logβ turn on logging π«Ά--log-dir ARG,--log-dir=ARG,--no-log-dirβ specify a log directory. It'll fall back to the system temp dir if needed π--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 the 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's set, or else"%!P%Y-%m-%d~%H:%M:%S~%!U~%!p.jsonl". This is a string where percent-escape sequences get replaced as per POSIX::strftime. These special escape sequences also get replaced: (%!P: project name followed by a~, if a project is defined, otherwise an 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, this is who it'll be from βοΈ--notify-email-owner,--no-notify-email-ownerβ email the owner of broken test files upon failure. Add# HARNESS-META-OWNER foo@example.comto the top of a test file to give it an owner π«Ά--notify-no-batch-email,--no-notify-no-batch-emailβ normally owner failures get sent as a single batch at the end of testing. Toggle this to send failures as they happen, live, no chill π€--notify-no-batch-slack,--no-notify-no-batch-slackβ same thing but for slack: usually owner failures are one batch at the end of testing. Toggle it and they go out as they happen π¨--notify-slack '#foo',--notify-slack '@bar',--no-notify-slackβ send results to a slack channel and/or user π¬
Can be specified multiple times
--notify-slack-fail '#foo',--notify-slack-fail '@bar',--no-notify-slack-failβ send failing results to a slack channel and/or user π
Can be specified multiple times
--notify-slack-owner,--no-notify-slack-ownerβ send slack notifications to the slack channels/users listed in test meta-data when tests fail π--notify-slack-url https://hooks.slack.com/...,--no-notify-slack-urlβ specify an API endpoint for slack webhook integrations π--notify-text ARG,--notify-text=ARG,--message ARG,--message=ARG,--msg ARG,--msg=ARG,--no-notify-textβ add a custom text snippet to your email/slack notifications π--notify-text-module ARG,--notify-text-module=ARG,--message_module ARG,--message_module=ARG,--no-notify-text-moduleβ use the specified module to generate messages for emails and/or slack π§
π Run Options π
--author-testing,-A,--no-author-testingβ this one sets theAUTHOR_TESTINGenvironment to true, so the author-only bits wake up and stretch π«Ά--dbi-profiling,--no-dbi-profilingβ pulls inTest2::Plugin::DBIProfileto gather up database profiling data, because we love receipts β¨--env-var VAR=VAL,-EVAR=VAL,-E VAR=VAL,--no-env-varβ sets environment variables that get set whenever each test runs. Can be specified multiple times, so stack those babies up π--event-uuids,--uuids,--no-event-uuidsβ usesTest2::Plugin::UUIDinside tests (default: on) πΈ--fields name:details,--fields JSON_STRING,-f name:details,-f JSON_STRING,--no-fieldsβ adds custom data to the harness run. Can be specified multiple times, go off π--input ARG,--input=ARG,--no-inputβ the input string that gets used as standard input for ALL tests. See also:--input-fileπ--input-file ARG,--input-file=ARG,--no-input-fileβ uses the file you name as standard input for ALL tests π--io-events,--no-io-eventsβ usesTest2::Plugin::IOEventsinside 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β gives people one or more links they can follow to see more about this run. Can be specified multiple times, share the lore π--load ARG,--load=ARG,--load-module ARG,--load-module=ARG,-m ARG,-m=ARG,--no-loadβ loads a module in each test (after fork). Heads up bestie, the"import"method is NOT called. Can be specified multiple times π§--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β loads a module in each test (after fork), and this timeImportis called. Can be specified multiple times. If the same key shows up multiple times, the value lists get appended together π¦--mem-usage,--no-mem-usageβ usesTest2::Plugin::MemUsageinside tests (default: on) π--retry ARG,--retry=ARG,-r ARG,-r=ARG,--no-retryβ runs any jobs that failed a second time. NOTE:--retry=1means failing tests will be attempted twice! not me doing the math on that π--retry-isolated,--retry-iso,--no-retry-isolatedβ if true, then any job retries get done in isolation (as though-j1was set) π--run-id,--id,--no-run-idβ sets a specific run-id. (Default: a UUID) β--test-args ARG,--test-args=ARG,--no-test-argsβ arguments to pass in as@ARGVfor all tests that are run. You can hand these over easier using the'::'argument separator. Can be specified multiple times π―--stream,--no-streamβ uses the stream formatter (default is on) π--tap,--TAP,----no-stream,--no-tapβ so like, the TAP format is lossy and clunky π¬Test2::Harnessnormally uses a newer streaming format to receive test results. There are old/legacy tests where this causes problems, and in that case setting--TAPor--no-streamcan help. (and yes, that flag is literally written----no-streamwith four dashes, that's not me being chaotic, that's the actual page π)
π YathUI Options π
--yathui-api-key ARG,--yathui-api-key=ARG,--no-yathui-api-keyβ your Yath-UI API key. Not necessary if your Yath-UI instance is set to single-user π--yathui-coverage,--no-yathui-coverageβ polls coverage data from Yath-UI to figure out which tests should be run for the files that changed π--yathui-durations,--no-yathui-durationsβ polls duration data from Yath-UI to help order tests efficiently β±οΈ--yathui-grace,--no-yathui-graceβ normally if yath can't connect to yath-ui it throws an error. Use this to make it fail gracefully instead. You still get a warning, but things keep going π«Ά--yathui-long-duration 10,--no-yathui-long-durationβ minimum duration length, in seconds, before a test goes from MEDIUM to LONG π--yathui-medium-duration 5,--no-yathui-medium-durationβ minimum duration length, in seconds, before a test goes from SHORT to MEDIUM π--yathui-mode summary,--yathui-mode qvf,--yathui-mode qvfd,--yathui-mode complete,--no-yathui-modeβ sets the upload mode (default'qvfd') π€--yathui-project ARG,--yathui-project=ARG,--no-yathui-projectβ the Yath-UI project your test results belong to ποΈ--yathui-retry,--no-yathui-retryβ how many times to try an operation before giving up. Can be specified multiple times π--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β Yath-UI url π
π NO CATEGORY - FIX ME π
--check-reload-state,--no-check-reload-stateβ aborts the run if there are unfixes reload errors, and pops up a confirmation dialogue for unfixed reload warnings π¨
π 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 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/
okay that's literally the whole page bestie, you made it to the end π this was written up by the Perl documentation crew, perl v5.40.1, dated 2026-05-10, and it's the App::Y...status(3pm) page β now go forth and run your tests, no cap πβ¨
π¦ where this page comes from
- ubuntu stonking: libtest2-harness-perl 1.000172-1 Β· Artistic-1.0-Perl OR GPL-1.0-or-later
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms