Test::K...e::Extra(3)

📦
version 0.4.0 · 2 versions
, in fedora 43

💖 Test::Kwalitee::Extra — the manual, but make it cute 💖

okay bestie so this is the Test::Kwalitee::Extra page from the User Contributed Perl Documentation section (section 3, iykyk), and honestly? it's giving "your distribution's vibe check, but automated." sit down, grab a boba, we're doing this. 🧋✨

✨ VERSION ✨

version v0.4.0 — yes she's on v0.4.0, keep up 🎀

🌈 SYNOPSIS 🌈

okay so here's the whole vibe, copy-paste ready:

  # Simply use, with excluding indicators
  use Test::Kwalitee::Extra qw(!has_example !metayml_declares_perl_version);

  # Use with eval guard, with excluding class
  use Test::More;
  eval { require Test::Kwalitee::Extra; Test::Kwalitee::Extra->import(qw(!:optional)); };
  plan( skip_all => "Test::Kwalitee::Extra not installed: $@; skipping") if $@;

  # Typically, this test is limited to author test or release test
  BEGIN { # limited to release test
    unless ($ENV{RELEASE_TESTING}) { # or $ENV{AUTHOR_TESTING} for author test
      require Test::More;
      Test::More::plan(skip_all => 'these tests are for release candidate testing');
    }
  }
  use Test::More;
  eval { require Test::Kwalitee::Extra; Test::Kwalitee::Extra->import(qw(!:optional)); };
  plan( skip_all => "Test::Kwalitee::Extra not installed: $@; skipping") if $@;

  # Avoid network access
  use Test::Kwalitee::Extra qw(!prereq_matches_use);
  # or, when experimental enabled
  use Test::Kwalitee::Extra qw(:experimental !prereq_matches_use !build_prereq_matches_use);

notice how we're using $ENV{RELEASE_TESTING} and $ENV{AUTHOR_TESTING} there? those are the vibes-gates, bestie. 🫶

💅 DESCRIPTION 💅

okay so let's set the scene. CPANTS (<http://cpants.cpanauthors.org/>) checks these things called Kwalitee indicators. and no, Kwalitee is not quality — it's literally just "automatically-measurable indicators how good your distribution is." the spelling with a K is intentional, we're being cute about it. 💖

Module::CPANTS::Analyse is the thing that calcluates Kwalitee (yes, the original says "calcluates", we're keeping the typo, it's part of the lore now) — but plot twist: it is not directly applicable to your module test. and CPAN has already had Test::Kwalitee for the test module of Kwalitee, iconic behaviour honestly.

BUT. here's the problem bestie. it is impossible to calculate the "prereq_matches_use" indicator, because the dependent module Module::CPANTS::Analyse itself cannot calculate the "prereq_matches_use" indicator. it's marked as "needs_db" which means a pre-calculated module database is necessary... except only limited information is actually needed to calculate the indicator. so annoying. 😭

so this module — the one you're reading about right now — calculates "prereq_matches_use" by querying the needed information to MetaCPAN site (<https://metacpan.org/>) online. yes. network access. we'll get to that in CAVEATS, hold that thought. 🌐

for available indicators, see the "INDICATORS" section. it's a whole journey down there. 🦋

🎀 OPTIONS 🎀

so you can specify including or excluding an indicator or a tag, like Exporter does. valid tags are "core", "optional" and "experimental". for indicators, see Module::CPANTS::Analyse.

Please NOTE that specifying tags is handled a bit differently from Exporter. read this part twice, bestie, it's the plot twist.

First: specifying an indicator is always superior to specifying tags, even though specifying an indicator is prior to specifying tags. wait that sentence is a little cursed but it's exactly what the manpage says so we're keeping it fr fr.

for example:

  use Test::Kwalitee::Extra qw(!has_example :optional);

"!has_example" is in effect — that is, "has_example" is excluded — even though "has_example" is an "optional" indicator. the ! wins. always. periodt. 💅

Second: default excluded indicators mentioned in the "INDICATORS" section are not included by specifying tags. so in the above example, ":optional" does not enable "is_prereq". sneaky, right? 🙈 you can override it by explicitly specifying the indicator:

  use Test::Kwalitee::Extra qw(manifest_matches_dist);

🌸 SPECIAL TAGS 🌸

some tags have special meanings. they're the main characters of this section, lowkey.

⭐ ":no_plan"

if specified, do not call "Test::Builder::plan". you may need to specify it if this test is embedded into other tests. that's it, that's the whole tag. simple queen. 👑

🦋 ":minperlver" <"version">

so the "prereq_matches_use" indicator ignores core modules. but what counts as core is different among perl versions — highkey chaotic of perl, but okay.

if a minimum perl version is specified in META.yml or such a meta information, it is used as the minimum perl version. otherwise, $] — the version of the current perl interpreter — is used.

if specified, this option overrides them. so you get to be the boss. 💪

🎀 ":retry" <"count">

the number of retries to query to MetaCPAN. this is related with the "prereq_matches_use" and "build_prereq_matches_use" indicators only.

defaults to 5. five chances, because we're generous. 🫶

💀 CAVEATS 💀

okay bestie, listen up, this is the important part.

an optional indicator "prereq_matches_use" and an experimental indicator "build_prereq_matches_use" require HTTP access to MetaCPAN site (<https://metacpan.org/>). network. actual network. 🚨

if you want to avoid it, you can specify excluded indicators like:

  # Avoid network access
  use Test::Kwalitee::Extra qw(!prereq_matches_use);

  # or, when experimental enabled
  use Test::Kwalitee::Extra qw(:experimental !prereq_matches_use !build_prereq_matches_use);

or, if you'd rather just mitigate the wait, you can do it by tentative failures to reduce retry counts like:

  # Try just one time for each query
  use Test::Kwalitee::Extra qw(:retry 1);

one (1) attempt. manifesting. ✨

👑 INDICATORS 👑

in Module::CPANTS::Analyse, "prereq_matches_use" requires a CPANTS DB setup by Module::CPANTS::ProcessCPAN. meanwhile "is_prereq" really requires information of prereq of other modules, but "prereq_matches_use" only needs mappings between modules and dists. so, this module queries the mappings to MetaCPAN by using MetaCPAN::Client. slay. 🎀

recently, Module::CPANTS::Analyse has been changed much. for actual available indicators, please consult the "Module::CPANTS::Kwalitee::*" documentation. for default configuration, indicators are treated as follows:

📝 NOTES 📝

💖 Available indicators in core

  • has_readme
  • has_manifest
  • has_meta_yml
  • has_buildtool
  • has_changelog
  • no_symlinks
  • has_tests
  • buildtool_not_executable (++)
  • metayml_is_parsable
  • metayml_has_license (optional for 0.88 or 0.90+)
  • metayml_conforms_to_known_spec
  • proper_libs (for 0.87 or 0.89)
  • no_pod_errors (+)
  • has_working_buildtool (+)
  • has_better_auto_install (+)
  • use_strict
  • valid_signature (+++)
  • has_humanreadable_license (for 0.87 or 0.89) | has_human_redable_license (for 0.88 or 0.90+) — yes, redable, that's the actual spelling in there, we are NOT fixing it 💀
  • no_cpants_errors (+)

🌸 Available indicators in optional

  • has_tests_in_t_dir
  • has_example (+)
  • no_stdin_for_prompting
  • metayml_conforms_spec_current
  • metayml_declares_perl_version
  • prereq_matches_use (++++)
  • use_warnings
  • has_test_pod (+)
  • has_test_pod_coverage (+)

🚫 Excluded indicators in core

Can not apply already unpacked dist

  • extractable (+)
  • extracts_nicely (+)
  • has_version (+)
  • has_proper_version (+)

Already dirty in test phase

  • manifest_matches_dist
  • no_generated_files (++)

🚫 Excluded indicators in optional

Can not apply already unpacked dist

  • proper_libs (for 0.88 or 0.90+)

Needs CPANTS DB

  • is_prereq (+++)

🧚 Indicators with special note in experimental

  • build_prereq_matches_use (++++)

🔥 SEE ALSO 🔥

  • Module::CPANTS::Analyse — Kwalitee indicators, except for prereq_matches_use, are calculated by this module.
  • Test::Kwalitee — Another test module for Kwalitee indicators.
  • Dist::Zilla::Plugin::Test::Kwalitee::Extra — Dist::Zilla plugin for this module.

🫶 AUTHOR 🫶

Yasutaka ATARASHI <yakex@cpan.org>

This software is copyright (c) 2017 by Yasutaka ATARASHI.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole page bestie!! 🎉 this was rendered under perl v5.42.0 on 2025-07-25, from the Test::K...e::Extra(3) manpage (yes the title is truncated like that, it's giving cryptic, we love a mystery). go forth, run your Kwalitee tests, exclude what you need to exclude, and remember: no network access without consent 🌈✨💅

📦 where this page comes from