1Test::Kwalitee(3)     User Contributed Perl Documentation    Test::Kwalitee(3)
2
3
4

NAME

6       Test::Kwalitee - Test the Kwalitee of a distribution before you release
7       it
8

VERSION

10       version 1.28
11

SYNOPSIS

13       In a separate test file:
14
15         use Test::More;
16         use strict;
17         use warnings;
18         BEGIN {
19             plan skip_all => 'these tests are for release candidate testing'
20                 unless $ENV{RELEASE_TESTING};
21         }
22
23         use Test::Kwalitee 'kwalitee_ok';
24         kwalitee_ok();
25         done_testing;
26

DESCRIPTION

28       Kwalitee is an automatically-measurable gauge of how good your software
29       is.  That's very different from quality, which a computer really can't
30       measure in a general sense.  (If you can, you've solved a hard problem
31       in computer science.)
32
33       In the world of the CPAN, the CPANTS project (CPAN Testing Service;
34       also a funny acronym on its own) measures Kwalitee with several
35       metrics.  If you plan to release a distribution to the CPAN -- or even
36       within your own organization -- testing its Kwalitee before creating a
37       release can help you improve your quality as well.
38
39       "Test::Kwalitee" and a short test file will do this for you
40       automatically.
41

USAGE

43       Create a test file as shown in the synopsis.  Run it.  It will run all
44       of the potential Kwalitee tests on the current distribution, if
45       possible.  If any fail, it will report those as regular diagnostics.
46
47       If you ship this test, it will not run for anyone else, because of the
48       "RELEASE_TESTING" guard. (You can omit this guard if you move the test
49       to xt/release/, which is not run automatically by other users.)
50

FUNCTIONS

52   kwalitee_ok
53       With no arguments, runs all standard metrics.
54
55       To run only a handful of tests, pass their name(s) to the "kwalitee_ok"
56       function:
57
58         kwalitee_ok(qw( use_strict has_tests ));
59
60       To disable a test, pass its name with a leading minus ("-"):
61
62         kwalitee_ok(qw( -use_strict has_readme ));
63

BACK-COMPATIBILITY MODE

65       Previous versions of this module ran tests directly via the "import"
66       sub, like so:
67
68           use Test::Kwalitee;
69           # and that's it!
70
71       ...but this is problematic if you need to perform some setup first, as
72       you would need to do that in a "BEGIN" block, or manually call
73       "import". This is messy!
74
75       However, this calling path is still available, e.g.:
76
77         use Test::Kwalitee tests => [ qw( use_strict has_tests ) ];
78

METRICS

80       The list of each available metric currently available on your system
81       can be obtained with the "kwalitee-metrics" command (with descriptions,
82       if you pass "--verbose" or "-v", but as of Module::CPANTS::Analyse
83       0.97_03, the tests include:
84
85       •   has_abstract_in_pod
86
87           Does the main module have a "=head1 NAME" section with a short
88           description of the distribution?
89
90       •   has_buildtool
91
92           Does the distribution have a build tool file?
93
94       •   has_changelog
95
96           Does the distribution have a changelog?
97
98       •   has_humanreadable_license
99
100           Is there a "LICENSE" section in documentation, and/or a LICENSE
101           file present?
102
103       •   has_license_in_source_file
104
105           Is there license information in any of the source files?
106
107       •   has_manifest
108
109           Does the distribution have a MANIFEST?
110
111       •   has_meta_yml
112
113           Does the distribution have a META.yml file?
114
115       •   has_readme
116
117           Does the distribution have a README file?
118
119       •   has_tests
120
121           Does the distribution have tests?
122
123       •   manifest_matches_dist
124
125           Do the MANIFEST and distribution contents match?
126
127       •   meta_json_conforms_to_known_spec
128
129           Does META.json conform to the recognised META.json specification?
130           (For specs see CPAN::Meta::Spec)
131
132       •   meta_json_is_parsable
133
134           Can the META.json be parsed?
135
136       •   meta_yml_conforms_to_known_spec
137
138           Does META.yml conform to any recognised META.yml specification?
139           (For specs see
140           <http://module-build.sourceforge.net/META-spec-current.html>)
141
142       •   meta_yml_is_parsable
143
144           Can the META.yml be parsed?
145
146       •   no_broken_auto_install
147
148           Is the distribution using an old version of Module::Install?
149           Versions of Module::Install prior to 0.89 do not detect correctly
150           that "CPAN"/"CPANPLUS" shell is used.
151
152       •   no_broken_module_install
153
154           Does the distribution use an obsolete version of Module::Install?
155           Versions of Module::Install prior to 0.61 might not work on some
156           systems at all. Additionally if the Makefile.PL uses the
157           auto_install() feature, you need at least version 0.64. Also, 1.04
158           is known to be broken.
159
160       •   no_symlinks
161
162           Does the distribution have no symlinks?
163
164       •   use_strict
165
166           Does the distribution files all use strict?
167

ACKNOWLEDGEMENTS

169       With thanks to CPANTS and Thomas Klausner, as well as test tester Chris
170       Dolan.
171

SEE ALSO

173       •   kwalitee-metrics (in this distribution)
174
175       •   Module::CPANTS::Analyse
176
177       •   App::CPANTS::Lint
178
179       •   Test::Kwalitee::Extra
180
181       •   Dist::Zilla::Plugin::Test::Kwalitee
182
183       •   Dist::Zilla::Plugin::Test::Kwalitee::Extra
184
185       •   Dist::Zilla::App::Command::kwalitee
186

SUPPORT

188       Bugs may be submitted through the RT bug tracker
189       <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Kwalitee> (or
190       bug-Test-Kwalitee@rt.cpan.org <mailto:bug-Test-Kwalitee@rt.cpan.org>).
191
192       There is also a mailing list available for users of this distribution,
193       at <http://lists.perl.org/list/perl-qa.html>.
194
195       There is also an irc channel available for users of this distribution,
196       at "#perl" on "irc.perl.org" <irc://irc.perl.org/#perl-qa>.
197

AUTHORS

199       •   chromatic <chromatic@wgz.org>
200
201       •   Karen Etheridge <ether@cpan.org>
202

CONTRIBUTORS

204       •   David Steinbrunner <dsteinbrunner@pobox.com>
205
206       •   Gavin Sherlock <sherlock@cpan.org>
207
208       •   Kenichi Ishigaki <ishigaki@cpan.org>
209
210       •   Nathan Haigh <nathanhaigh@ukonline.co.uk>
211
212       •   Zoffix Znet <cpan@zoffix.com>
213
214       •   Daniel Perrett <perrettdl@googlemail.com>
215
217       This software is copyright (c) 2005 by chromatic.
218
219       This is free software; you can redistribute it and/or modify it under
220       the same terms as the Perl 5 programming language system itself.
221
222
223
224perl v5.38.0                      2023-07-21                 Test::Kwalitee(3)
Impressum