Test::Kwalitee::Extra(3pm)

1Test::Kwalitee::Extra(3U)ser Contributed Perl DocumentatiToenst::Kwalitee::Extra(3)
2
3
4

NAME

6       Test::Kwalitee::Extra - Run Kwalitee tests including optional
7       indicators, especially, prereq_matches_use
8

VERSION

10       version v0.4.0
11

SYNOPSIS

13         # Simply use, with excluding indicators
14         use Test::Kwalitee::Extra qw(!has_example !metayml_declares_perl_version);
15
16         # Use with eval guard, with excluding class
17         use Test::More;
18         eval { require Test::Kwalitee::Extra; Test::Kwalitee::Extra->import(qw(!:optional)); };
19         plan( skip_all => "Test::Kwalitee::Extra not installed: $@; skipping") if $@;
20
21         # Typically, this test is limited to author test or release test
22         BEGIN { # limited to release test
23           unless ($ENV{RELEASE_TESTING}) { # or $ENV{AUTHOR_TESTING} for author test
24             require Test::More;
25             Test::More::plan(skip_all => 'these tests are for release candidate testing');
26           }
27         }
28         use Test::More;
29         eval { require Test::Kwalitee::Extra; Test::Kwalitee::Extra->import(qw(!:optional)); };
30         plan( skip_all => "Test::Kwalitee::Extra not installed: $@; skipping") if $@;
31
32         # Avoid network access
33         use Test::Kwalitee::Extra qw(!prereq_matches_use);
34         # or, when experimental enabled
35         use Test::Kwalitee::Extra qw(:experimental !prereq_matches_use !build_prereq_matches_use);
36

DESCRIPTION

38       CPANTS <http://cpants.cpanauthors.org/> checks Kwalitee indicators,
39       which is not quality but automatically-measurable indicators how good
40       your distribution is. Module::CPANTS::Analyse calcluates Kwalitee but
41       it is not directly applicable to your module test. CPAN has already had
42       Test::Kwalitee for the test module of Kwalitee. It is, however,
43       impossible to calculate "prereq_matches_use" indicator, because
44       dependent module Module::CPANTS::Analyse itself cannot calculate
45       "prereq_matches_use" indicator. It is marked as "needs_db" which means
46       pre-calculated module database is necessary, but only limited
47       information is needed to calculate the indicator. This module calculate
48       "prereq_matches_use" to query needed information to MetaCPAN site
49       <https://metacpan.org/> online.
50
51       For available indicators, see "INDICATORS" section.
52

OPTIONS

54       You can specify including or excluding an indicator or a tag like
55       Exporter. Valid tags are "core", "optional" and "experimental". For
56       indicators, see Module::CPANTS::Analyse.
57
58       Please NOTE that to specify tags are handled a bit differently from
59       Exporter. First, specifying an indicator is always superior to
60       specifying tags, even though specifying an indicator is prior to
61       specifying tags.
62
63       For example,
64
65         use Test::Kwalitee::Extra qw(!has_example :optional);
66
67       "!has_example" is in effect, that is "has_example" is excluded, even
68       though "has_example" is an "optional" indicator.
69
70       Second, default excluded indicators mentioned in "INDICATORS" section
71       are not included by specifying tags. For example, in the above example,
72       ":optional" does not enable "is_prereq". You can override it by
73       explicitly specifying the indicator:
74
75         use Test::Kwalitee::Extra qw(manifest_matches_dist);
76
77   SPECIAL TAGS
78       Some tags have special meanings.
79
80   ":no_plan"
81       If specified, do not call "Test::Builder::plan". You may need to
82       specify it, if this test is embedded into other tests.
83
84   ":minperlver" <"version">
85       "prereq_matches_use" indicator ignores core modules. What modules are
86       in core, however, is different among perl versions. If minimum perl
87       version is specified in META.yml or such a meta information, it is used
88       as minimum perl version. Otherewise, $], the version of the current
89       perl interpreter, is used.
90
91       If specified, this option overrides them.
92
93   ":retry" <"count">
94       The number of retry to query to MetaCPAN. This is related with
95       "prereq_matches_use" and "build_prereq_matches_use" indicators only.
96
97       Defaults to 5.
98

CAVEATS

100       An optional indicator "prereq_matches_use" and an experimental
101       indicator "build_prereq_matches_use" require HTTP access to MetaCPAN
102       site <https://metacpan.org/>. If you want to avoid it, you can specify
103       excluded indicators like
104
105         # Avoid network access
106         use Test::Kwalitee::Extra qw(!prereq_matches_use);
107
108         # or, when experimental enabled
109         use Test::Kwalitee::Extra qw(:experimental !prereq_matches_use !build_prereq_matches_use);
110
111       Or mitigate wait by tentative failures to reduce retry counts like
112
113         # Try just one time for each query
114         use Test::Kwalitee::Extra qw(:retry 1);
115

INDICATORS

117       In Module::CPANTS::Analyse, "prereq_matches_use" requires CPANTS DB
118       setup by Module::CPANTS::ProcessCPAN. "is_prereq" really requires
119       information of prereq of other modules but "prereq_matches_use" only
120       needs mappings between modules and dists. So, this module query the
121       mappings to MetaCPAN by using MetaCPAN::Client.
122
123       Recently, Module::CPANTS::Analyse has been changed much. For actual
124       available indicators, please consult "Module::CPANTS::Kwalitee::*"
125       documentation. For default configuration, indicators are treated as
126       follows:
127
128       NOTES
129           (+) No longer available for Module::CPANTS::Analyse 0.88 or 0.90+.
130
131           (++)
132               No longer available for Module::CPANTS::Analyse 0.90+.
133
134           (+++)
135               No longer available for Module::CPANTS::Analyse 0.88 or 0.90+,
136               moved to Module::CPANTS::SiteKwalitee
137               <https://github.com/cpants/Module-CPANTS-SiteKwalitee>.
138
139           (++++)
140               No longer available for Module::CPANTS::Analyse 0.88 or 0.90+,
141               moved to Module::CPANTS::SiteKwalitee
142               <https://github.com/cpants/Module-CPANTS-SiteKwalitee> but
143               supported by this module.
144
145       Available indicators in core
146           •   has_readme
147
148           •   has_manifest
149
150           •   has_meta_yml
151
152           •   has_buildtool
153
154           •   has_changelog
155
156           •   no_symlinks
157
158           •   has_tests
159
160           •   buildtool_not_executable (++)
161
162           •   metayml_is_parsable
163
164           •   metayml_has_license (optional for 0.88 or 0.90+)
165
166           •   metayml_conforms_to_known_spec
167
168           •   proper_libs (for 0.87 or 0.89)
169
170           •   no_pod_errors (+)
171
172           •   has_working_buildtool (+)
173
174           •   has_better_auto_install (+)
175
176           •   use_strict
177
178           •   valid_signature (+++)
179
180           •   has_humanreadable_license (for 0.87 or 0.89) |
181               has_human_redable_license (for 0.88 or 0.90+)
182
183           •   no_cpants_errors (+)
184
185       Available indicators in optional
186           •   has_tests_in_t_dir
187
188           •   has_example (+)
189
190           •   no_stdin_for_prompting
191
192           •   metayml_conforms_spec_current
193
194           •   metayml_declares_perl_version
195
196           •   prereq_matches_use (++++)
197
198           •   use_warnings
199
200           •   has_test_pod (+)
201
202           •   has_test_pod_coverage (+)
203
204       Excluded indicators in core
205           Can not apply already unpacked dist
206               •   extractable (+)
207
208               •   extracts_nicely (+)
209
210               •   has_version (+)
211
212               •   has_proper_version (+)
213
214           Already dirty in test phase
215               •   manifest_matches_dist
216
217               •   no_generated_files (++)
218
219       Excluded indicators in optional
220           Can not apply already unpacked dist
221               •   proper_libs (for 0.88 or 0.90+)
222
223           Needs CPANTS DB
224               •   is_prereq (+++)
225
226       Indicators with special note in experimental
227           •   build_prereq_matches_use (++++)
228

AUTHOR

239       Yasutaka ATARASHI <yakex@cpan.org>
240

COPYRIGHT AND LICENSE

242       This software is copyright (c) 2017 by Yasutaka ATARASHI.
243
244       This is free software; you can redistribute it and/or modify it under
245       the same terms as the Perl 5 programming language system itself.
246
247
248
249perl v5.32.1                      2021-01-27          Test::Kwalitee::Extra(3)