Test::Kwalitee(3pm)

✨ NAME ✨

Test::Kwalitee — okay bestie, this is the manual page for Test::Kwalitee (that's the 3pm one, the Perl module docs), and it does exactly one iconic thing: it tests the Kwalitee of a distribution before you release it. Yes, Kwalitee with a K. We'll get there. 🦋

---

💖 VERSION 💖

version 1.28

That's the one you're reading right now, no cap.

---

🎀 SYNOPSIS 🎀

Drop this into a separate test file, like, its own little home:

use Test::More;
use strict;
use warnings;
BEGIN {
    plan skip_all => 'these tests are for release candidate testing'
        unless $ENV{RELEASE_TESTING};
}

use Test::Kwalitee 'kwalitee_ok';
kwalitee_ok();
done_testing;

The BEGIN block is doing the bouncer-at-the-door thing so it doesn't run for randos. 💅

---

🌸 DESCRIPTION 🌸

So. Kwalitee is an automatically-measurable gauge of how good your software is. It's very different from quality, which a computer genuinely cannot measure in a general sense. (And if you can measure quality, bestie, you've solved a hard problem in computer science. Go get your crown. 👑)

Over in CPAN world, the CPANTS project (that's CPAN Testing Service — and yes, it's also a funny acronym all on its own, love that for them) measures Kwalitee with several metrics. If you're planning to release a distribution to the CPAN — or honestly even just within your own organization — testing its Kwalitee before you create a release can help you improve your quality too. Two birds, one slay. 🐦🐦

Test::Kwalitee plus one short test file does all of this for you automatically. That's it. That's the whole pitch.

---

🌈 USAGE 🌈

Make a test file like the one in the synopsis. Run it. It will run all of the potential Kwalitee tests on the current distribution, if possible. And if any of them fail? It reports those as regular diagnostics. No drama, just data. ✨

Heads up: if you ship this test, it will not run for anyone else, because of that RELEASE_TESTING guard doing its job. You can omit the guard if you move the test to xt/release/ — that folder isn't run automatically by other users. 🫶

---

💅 FUNCTIONS 💅

kwalitee_ok

With no arguments at all, it runs all standard metrics. Full send.

But say you only want a handful of tests? Just pass their name(s) to the kwalitee_ok function, like so:

kwalitee_ok(qw( use_strict has_tests ));

And to disable a test, pass its name with a leading minus (-):

kwalitee_ok(qw( -use_strict has_readme ));

The little minus is giving "not that one, bestie". 🚫

---

🕰️ BACK-COMPATIBILITY MODE 🕰️

Old versions of this module ran tests directly via the import sub, like this:

use Test::Kwalitee;
# and that's it!

...but honestly? That's problematic if you need to do some setup first, because you'd have to do it inside a BEGIN block, or manually call import. Messy! 😭

The good news: that calling path is still available. For example:

use Test::Kwalitee tests => [ qw( use_strict has_tests ) ];

Old code, still thriving. We love a legacy queen. 👑

---

🔥 METRICS 🔥

Want the full list of every metric currently available on your system? Run the kwalitee-metrics command. You'll even get descriptions if you pass --verbose or -v. But as of Module::CPANTS::Analyse 0.97_03, the tests include:

• has_abstract_in_pod — Does the main module have a =head1 NAME section with a short description of the distribution?
• has_buildtool — Does the distribution have a build tool file?
• has_changelog — Does the distribution have a changelog?
• has_humanreadable_license — Is there a LICENSE section in documentation, and/or a LICENSE file present?
• has_license_in_source_file — Is there license information in any of the source files?
• has_manifest — Does the distribution have a MANIFEST?
• has_meta_yml — Does the distribution have a META.yml file?
• has_readme — Does the distribution have a README file?
• has_tests — Does the distribution have tests?
• manifest_matches_dist — Do the MANIFEST and distribution contents match?
• meta_json_conforms_to_known_spec — Does META.json conform to the recognised META.json specification? (For specs see CPAN::Meta::Spec)
• meta_json_is_parsable — Can the META.json be parsed?
• meta_yml_conforms_to_known_spec — Does META.yml conform to any recognised META.yml specification? (For specs see http://module-build.sourceforge.net/META-spec-current.html)
• meta_yml_is_parsable — Can the META.yml be parsed?
• no_broken_auto_install — Is the distribution using an old version of Module::Install? Versions of Module::Install prior to 0.89 do not detect correctly that CPAN/CPANPLUS shell is used.
• no_broken_module_install — Does the distribution use an obsolete version of Module::Install? Versions of Module::Install prior to 0.61 might not work on some systems at all. Additionally, if the Makefile.PL uses the auto_install() feature, you need at least version 0.64. Also, 1.04 is known to be broken. 💀
• no_symlinks — Does the distribution have no symlinks?
• use_strict — Does the distribution files all use strict?

Eighteen little checks standing between you and a chaotic release. Iconic behavior. 🌟

---

🫶 ACKNOWLEDGEMENTS 🫶

With thanks to CPANTS and Thomas Klausner, as well as test tester Chris Dolan. Genuinely so much love to them, this whole thing exists because of them. 💜

---

🦋 SEE ALSO 🦋

• kwalitee-metrics (in this distribution)
• Module::CPANTS::Analyse
• App::CPANTS::Lint
• Test::Kwalitee::Extra
• Dist::Zilla::Plugin::Test::Kwalitee
• Dist::Zilla::Plugin::Test::Kwalitee::Extra
• Dist::Zilla::App::Command::kwalitee

Go read them, they're the extended universe. 📚

---

💌 SUPPORT 💌

Found a bug? Bestie, tell someone! Bugs may be submitted through the RT bug tracker at https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Kwalitee (or, if email is more your vibe, bug-Test-Kwalitee@rt.cpan.org). 🐛

There's also a mailing list for users of this distribution, hanging out at http://lists.perl.org/list/perl-qa.html.

And there's an irc channel too, at #perl on irc.perl.org (irc://irc.perl.org/#perl-qa). Come say hi, the people there are lovely. 🌈

---

👑 AUTHORS 👑

• chromatic <chromatic@wgz.org>
• Karen Etheridge <ether@cpan.org>

---

🌟 CONTRIBUTORS 🌟

• David Steinbrunner <dsteinbrunner@pobox.com>
• Gavin Sherlock <sherlock@cpan.org>
• Kenichi Ishigaki <ishigaki@cpan.org>
• Nathan Haigh <nathanhaigh@ukonline.co.uk>
• Zoffix Znet <cpan@zoffix.com>
• Daniel Perrett <perrettdl@googlemail.com>

Every single one of them a legend, fr fr. 💖

---

📜 COPYRIGHT AND LICENSE 📜

This software is copyright (c) 2005 by chromatic.

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

---

Okay that's the whole page, you made it to the end, I'm so proud of you. 🥹 This was Test::Kwalitee version 1.28, from perl v5.36.0, dated 2022-12-06 — go forth and ship something with immaculate Kwalitee. Periodt. 💅✨🎀