=pod
=encoding UTF-8
=head1 NAME
Test::Kwalitee - Test the Kwalitee of a distribution before you release it
=head1 VERSION
version 1.28
=head1 SYNOPSIS
In a separate test file:
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;
=head1 DESCRIPTION
=for stopwords CPANTS
Kwalitee is an automatically-measurable gauge of how good your software is. That's very different from quality, which a computer really can't measure in a general sense. (If you can, you've solved a hard problem in computer science.)
In the world of the CPAN, the CPANTS project (CPAN Testing Service; also a funny acronym on its own) measures Kwalitee with several metrics. If you plan to release a distribution to the CPAN -- or even within your own organization -- testing its Kwalitee before creating a release can help you improve your quality as well.
CTest::Kwalitee and a short test file will do this for you automatically.
=head1 USAGE
Create a test file as shown in the synopsis. Run it. It will run all of the potential Kwalitee tests on the current distribution, if possible. If any fail, it will report those as regular diagnostics.
If you ship this test, it will not run for anyone else, because of the C<RELEASE_TESTING> guard. (You can omit this guard if you move the test to xt/release/, which is not run automatically by other users.)
=head1 FUNCTIONS
=head2 kwalitee_ok
With no arguments, runs all standard metrics.
To run only a handful of tests, pass their name(s) to the C<kwalitee_ok> function:
kwalitee_ok(qw( use_strict has_tests ));
To disable a test, pass its name with a leading minus (C<->):
kwalitee_ok(qw( -use_strict has_readme ));
=head1 BACK-COMPATIBILITY MODE
Previous versions of this module ran tests directly via the C sub, like so:
use Test::Kwalitee;
# and that's it!
...but this is problematic if you need to perform some setup first, as you would need to do that in a C block, or manually call C. This is messy!
However, this calling path is still available, e.g.:
use Test::Kwalitee tests => [ qw( use_strict has_tests ) ];
=head1 METRICS
The list of each available metric currently available on your system can be obtained with the C command (with descriptions, if you pass C<--verbose> or C<-v>, but as of LModule::CPANTS::Analyse 0.97_03, the tests include:
=over 4
=item *
has_abstract_in_pod
Does the main module have a C<=head1 NAME> section with a short description of the distribution?
=item *
has_buildtool
Does the distribution have a build tool file?
=for stopwords changelog
=item *
has_changelog
Does the distribution have a changelog?
=item *
has_humanreadable_license
Is there a C section in documentation, and/or a F file present?
=item *
has_license_in_source_file
Is there license information in any of the source files?
=item *
has_manifest
Does the distribution have a F?
=item *
has_meta_yml
Does the distribution have a F<META.yml> file?
=item *
has_readme
Does the distribution have a F file?
=item *
has_tests
Does the distribution have tests?
=item *
manifest_matches_dist
Do the F and distribution contents match?
=item *
meta_json_conforms_to_known_spec
Does META.json conform to the recognised META.json specification? (For specs see LCPAN::Meta::Spec)
=item *
meta_json_is_parsable
Can the F<META.json> be parsed?
=item *
meta_yml_conforms_to_known_spec
=for stopwords recognised
Does META.yml conform to any recognised META.yml specification? (For specs see Lhttp://module-build.sourceforge.net/META-spec-current.html)
=item *
meta_yml_is_parsable
Can the F<META.yml> be parsed?
=item *
no_broken_auto_install
Is the distribution using an old version of LModule::Install? Versions of LModule::Install prior to 0.89 do not detect correctly that C/C shell is used.
=item *
no_broken_module_install
Does the distribution use an obsolete version of LModule::Install? Versions of LModule::Install prior to 0.61 might not work on some systems at all. Additionally if the F<Makefile.PL> uses the C<auto_install()> feature, you need at least version 0.64. Also, 1.04 is known to be broken.
=item *
no_symlinks
Does the distribution have no symlinks?
=item *
use_strict
Does the distribution files all use strict?
=back
=head1 ACKNOWLEDGEMENTS
=for stopwords Klausner Dolan
With thanks to CPANTS and Thomas Klausner, as well as test tester Chris Dolan.
=head1 SEE ALSO
=over 4
=item *
L (in this distribution)
=item *
=item *
=item *
=item *
LDist::Zilla::Plugin::Test::Kwalitee
=item *
LDist::Zilla::Plugin::Test::Kwalitee::Extra
=item *
LDist::Zilla::App::Command::kwalitee
=back
=head1 SUPPORT
Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Kwalitee> (or L<[email protected]|mailto:[email protected]>).
There is also a mailing list available for users of this distribution, at Lhttp://lists.perl.org/list/perl-qa.html.
There is also an irc channel available for users of this distribution, at L<C<#perl> on C<irc.perl.org>|irc://irc.perl.org/#perl-qa>.
=head1 AUTHORS
=over 4
=item *
chromatic [email protected]
=item *
Karen Etheridge [email protected]
=back
=head1 CONTRIBUTORS
=for stopwords David Steinbrunner Gavin Sherlock Kenichi Ishigaki Nathan Haigh Zoffix Znet Daniel Perrett
=over 4
=item *
David Steinbrunner [email protected]
=item *
Gavin Sherlock [email protected]
=item *
Kenichi Ishigaki [email protected]
=item *
Nathan Haigh [email protected]
=item *
Zoffix Znet [email protected]
=item *
Daniel Perrett [email protected]
=back
=head1 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.
=cut