1Test::Apocalypse(3) User Contributed Perl Documentation Test::Apocalypse(3)
2
6 Test::Apocalypse - Apocalypse's favorite tests bundled into a simple
7 interface
8
10 This document describes v1.006 of Test::Apocalypse - released October 25, 2014 as part of Test-Apocalypse.
11
13 #!/usr/bin/perl
14 use strict; use warnings;
15 use Test::More;
17 eval "use Test::Apocalypse";
18 if ( $@ ) {
19 plan skip_all => 'Test::Apocalypse required for validating the distribution';
20 } else {
21 is_apocalypse_here();
22 }
23
25 This module greatly simplifies common author tests for modules heading
26 towards CPAN. I was sick of copy/pasting the tons of t/foo.t scripts +
27 managing them in every distro. I thought it would be nice to bundle all
28 of it into one module and toss it on CPAN :) That way, every time I
29 update this module all of my dists would be magically updated!
30 This module respects the RELEASE_TESTING/AUTOMATED_TESTING env
32 variable, if it is not set it will skip the entire testsuite. Normally
33 end-users should not run it; but you can if you want to see how bad my
34 dists are, ha! The scheme is exactly the same as the one Alias proposed
35 in Test::XT and in his blog post,
36 <http://use.perl.org/use.perl.org/_Alias/journal/38822.html>.
37 This module uses Module::Pluggable to have custom "backends" that
39 process various tests. We wrap them in a hackish Test::Block block per-
40 plugin and it seems to work nicely. If you want to write your own, it
41 should be a breeze once you look at some of my plugins and see how it
42 works. ( more documentation to come )
43 Usage
45 In order to use this, you would need to be familiar with the "standard"
46 steps in order to fully exercise the testsuite. There are a few steps
47 we require, because our plugins need stuff to be prepared for them. For
48 starters, you would need a test file in your distribution similar to
49 the one in SYNOPSIS. Once that is done and added to your MANIFEST and
50 etc, you can do this:
51 perl Build.PL # sets up the dist ( duh, hah )
53 ./Build dist # makes the tarball ( so certain plugins can process it )
54 RELEASE_TESTING=1 ./Build test # runs the testsuite!
55
57 is_apocalypse_here()
58 This is the main entry point for this testsuite. By default, it runs
59 every plugin in the testsuite. You can enable/disable specific plugins
60 if you desire. It accepts a single argument: a hashref or a hash. It
61 can contain various options, but as of now it only supports two
62 options. If you try to use allow and deny at the same time, this module
63 will throw an exception.
64 allow
66 Setting "allow" to a string or a precompiled regex will run only the
68 plugins that match the regex. If passed a string, this module will
69 compile it via "qr/$str/i".
70 # run only the EOL test and disable all other tests
72 is_apocalypse_here( {
73 allow => qr/^EOL$/,
74 } );
75 # run all "dist" tests
77 is_apocalypse_here( {
78 allow => 'dist',
79 } );
80 deny
82 Setting "deny" to a string or a precompiled regex will not run the
84 plugins that match the regex. If passed a string, this module will
85 compile it via "qr/$str/i".
86 # disable Pod_Coverage test and enable all other tests
88 is_apocalypse_here( {
89 deny => qr/^Pod_Coverage$/,
90 } );
91 # disable all pod tests
93 is_apocalypse_here( {
94 deny => 'pod',
95 } );
96 plugins()
98 Since this module uses Module::Pluggable you can use this method on the
99 package to find out what plugins are available. Handy if you need to
100 know what plugins to skip, for example.
101 my @tests = Test::Apocalypse->plugins;
103
105 Automatically exports the "is_apocalypse_here" sub.
106
108 • Test::NoSmartComments
109 I don't use Smart::Comments but it might be useful? I LOVE BLOAT!
111 :)
112 • Better POD spelling checker?
114 Test::Spelling is ancient, and often blows up. There's a
116 Test::Pod::Spelling on CPAN but it is flaky too :(
117 • Document the way we do plugins so others can add to this testsuite
119 :)
120 • POD standards check
122 Do we have SYNOPSIS, ABSTRACT, SUPPORT, etc sections? ( PerlCritic
124 can do that! Need to investigate more... )
125 • Integrate Test::UniqueTestNames into the testsuite
127 This would be nice, but I'm not sure if I can actually force this
129 on other tests. Otherwise I'll be just making sure that the
130 Test::Apocalypse tests is unique, which is worthless to $dist
131 trying to clean itself up...
132 • META.yml checks
134 We should make sure that the META.yml includes the "repository",
136 "license", and other useful keys!
137 • Other AUTHORs
139 As always, we should keep up on the "latest" in the perl world and
141 look at other authors for what they are doing.
142 • indirect syntax
144 We should figure out how to use indirect.pm to detect this
146 deprecated method of coding. There's a Perl::Critic plugin for
147 this, yay!
148 • Test::PPPort
150 Already implemented as PPPort.pm but it's less invasive than my
152 version, ha!
153 • Test::DependentModules
155 This is a crazy test, but would help tremendously in finding
157 regressions in your code!
158 • Test::CleanNamespaces
160 I don't exclusively code in Moose, but this could be useful...
162 • no internet?
164 It would be nice to signal INTERNET_TESTING=0 or something zany
166 like that so this testsuite will skip the tests that need internet
167 access...
168 <Apocalypse> Is there a convention that signals no internet access? Similar to RELEASE_TESTING, AUTOMATED_TESTING, and etc?
170 <@rjbs> No.
171 <Apocalypse> mmm I ain't in the mood to invent it so I'll just bench it for now :(
172 <Apocalypse> however, if I was to invent it I would call it something like INTERNET_TESTING=0
173 <Apocalypse> Also, why does ILYAZ keep re-inventing the stuff? Use of uninitialized value $ENV{"PERL_RL_TEST_PROMPT_MINLEN"} in bitwise or (|) at test.pl line 33.
174 <@Alias> use LWP::Online ':skip_all';
175 <@Alias> Whack that in the relevant test scripts
176 <Apocalypse> Alias: Hmm, how can I control that at a distance? i.e. disabling inet if I had inet access?
177 <@Alias> You can't
178 <@Alias> It's a pragmatic test, tries to pull some huge site front pages and looks for copyright statements
179 <Apocalypse> At least it's a good start - thanks!
180 <@Alias> So it deals with proxies and airport wireless hijacking etc properly
181 <Apocalypse> Hah yeah I had to do the same thing at $work in the past, we put up a "special" page then had our software try to read it and if the content didn't match it complained :)
182 <@Alias> right
183 <@Alias> So yeah, it automates that
184 <@Alias> I wrote it while in an airport annoyed that something I wrote wasn't falling back on a minicpan properly
185 <Apocalypse> At least it'll be an improvement, but I still need to force no inet for testing... ohwell
186 <Apocalypse> Heh, it seems like us perl hackers do a lot of work while stranded at airports :)
187 <@Alias> If you can break LWP from the environment, that would work
188 <@Alias> Setting a proxy ENVthat is illegal etc
189 <Apocalypse> ah good thinking, I'll read up on the fine points of LWP env vars and try to screw it up
190 Modules that I considered but decided against using
192 • Test::Distribution
193 This module was a plugin in this testsuite but I don't need it. All
195 the functionality in it is already replicated in the plugins :)
196 • Test::Module::Used and Test::Dependencies
198 They were plugins in this testsuite but since I started coding with
200 Moose, they don't work! I've switched to my homebrew solution
201 utilizing Perl::PrereqScanner which works nicely for me.
202 • Test::MyDeps
204 Superseded by Test::DependentModules. Also, I don't want to waste a
206 lot of time on each testrun testing other modules!
207 • Test::NoTabs
209 I always use tabs! :(
211 • Test::CheckManifest
213 This was a buggy module that I dropped and is now using
215 Test::DistManifest
216 • Test::Dist
218 This is pretty much the same thing as this dist ;)
220 • Test::PureASCII
222 This rocks, as I don't care about unicode in my perl! ;)
224 • Test::LatestPrereqs
226 This looks cool but we need to fiddle with config files? My
228 OutdatedPrereqs test already covers it pretty well...
229 • Test::Pod::Content
231 This is useful, but not everyone has the same POD layout. It would
233 be too much work to try and generalize this...
234 • Test::GreaterVersion
236 Since I never use CPAN, this is non-functional for me. However, it
238 might be useful for someone?
239 • Test::Kwalitee
241 This dist rocks, but it doesn't print the info nor utilize the
243 extra metrics. My homebrew solution actually copied a lot of code
244 from this, so I have to give it props!
245 • Test::LoadAllModules
247 This is very similar to Test::UseAllModules but looks more
249 complicated. Also, I already have enough tests that do that ;)
250 • Test::ModuleReady
252 This looks like a nice module, but what it does is already covered
254 by the numerous tests in this dist...
255 • Test::PerlTidy
257 Br0ken install at this time... ( PerlCritic can do that! Need to
259 investigate more... ) Also, all it does is... run your module
260 through perltidy and compare the outputs. Not that useful imo
261 because I never could get perltidy to match my prefs :(
262 • Test::Install::METArequires
264 This looks like a lazy way to do auto_install and potentially
266 dangerous! Better to just use the prereq logic in
267 Build.PL/Makefile.PL
268 • Test::Perl::Metrics::Simple
270 This just tests your Cyclomatic complexity and was the starting
272 point for my homebrew solution.
273
275 Perldoc
276 You can find documentation for this module with the perldoc command.
277 perldoc Test::Apocalypse
279 Websites
281 The following websites have more information about this module, and may
282 be of help to you. As always, in addition to those websites please use
283 your favorite search engine to discover more resources.
284 • MetaCPAN
286 A modern, open-source CPAN search engine, useful to view POD in
288 HTML format.
289 <http://metacpan.org/release/Test-Apocalypse>
291 • Search CPAN
293 The default CPAN search engine, useful to view POD in HTML format.
295 <http://search.cpan.org/dist/Test-Apocalypse>
297 • RT: CPAN's Bug Tracker
299 The RT ( Request Tracker ) website is the default bug/issue
301 tracking system for CPAN.
302 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Apocalypse>
304 • AnnoCPAN
306 The AnnoCPAN is a website that allows community annotations of Perl
308 module documentation.
309 <http://annocpan.org/dist/Test-Apocalypse>
311 • CPAN Ratings
313 The CPAN Ratings is a website that allows community ratings and
315 reviews of Perl modules.
316 <http://cpanratings.perl.org/d/Test-Apocalypse>
318 • CPAN Forum
320 The CPAN Forum is a web forum for discussing Perl modules.
322 <http://cpanforum.com/dist/Test-Apocalypse>
324 • CPANTS
326 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
328 of a distribution.
329 <http://cpants.perl.org/dist/overview/Test-Apocalypse>
331 • CPAN Testers
333 The CPAN Testers is a network of smokers who run automated tests on
335 uploaded CPAN distributions.
336 <http://www.cpantesters.org/distro/T/Test-Apocalypse>
338 • CPAN Testers Matrix
340 The CPAN Testers Matrix is a website that provides a visual
342 overview of the test results for a distribution on various
343 Perls/platforms.
344 <http://matrix.cpantesters.org/?dist=Test-Apocalypse>
346 • CPAN Testers Dependencies
348 The CPAN Testers Dependencies is a website that shows a chart of
350 the test results of all dependencies for a distribution.
351 <http://deps.cpantesters.org/?module=Test::Apocalypse>
353 Email
355 You can email the author of this module at "APOCAL at cpan.org" asking
356 for help with any problems you have.
357 Internet Relay Chat
359 You can get live help by using IRC ( Internet Relay Chat ). If you
360 don't know what IRC is, please read this excellent guide:
361 <http://en.wikipedia.org/wiki/Internet_Relay_Chat>. Please be courteous
362 and patient when talking to us, as we might be busy or sleeping! You
363 can join those networks/channels and get help:
364 • irc.perl.org
366 You can connect to the server at 'irc.perl.org' and join this
368 channel: #perl-help then talk to this person for help: Apocalypse.
369 • irc.freenode.net
371 You can connect to the server at 'irc.freenode.net' and join this
373 channel: #perl then talk to this person for help: Apocal.
374 • irc.efnet.org
376 You can connect to the server at 'irc.efnet.org' and join this
378 channel: #perl then talk to this person for help: Ap0cal.
379 Bugs / Feature Requests
381 Please report any bugs or feature requests by email to
382 "bug-test-apocalypse at rt.cpan.org", or through the web interface at
383 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Apocalypse>. You
384 will be automatically notified of any progress on the request by the
385 system.
386 Source Code
388 The code is open to the world, and available for you to hack on. Please
389 feel free to browse it and play with it, or whatever. If you want to
390 contribute patches, please send me a diff or prod me to pull from your
391 repository :)
392 <https://github.com/apocalypse/perl-test-apocalypse>
394 git clone git://github.com/apocalypse/perl-test-apocalypse.git
396
398 Apocalypse <APOCAL@cpan.org>
399 CONTRIBUTORS
401 • Apocalypse <apoc@blackhole.(none)>
402 • Apocalypse <apoc@satellite.(none)>
404 • Apocalypse <perl@0ne.us>
406 • Ryan Niebur <ryanryan52@gmail.com>
408
410 Thanks to jawnsy@cpan.org for the prodding and help in getting this
411 package ready to be bundled into debian!
412
414 This software is copyright (c) 2014 by Apocalypse.
415 This is free software; you can redistribute it and/or modify it under
417 the same terms as the Perl 5 programming language system itself.
418 The full text of the license can be found in the LICENSE file included
420 with this distribution.
421
423 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
424 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
425 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
426 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
427 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
428 PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
429 OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU
430 ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
431 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
433 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
434 CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
435 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
436 ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
437 NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
438 SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
439 OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY
440 HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
441perl v5.38.0 2023-07-21 Test::Apocalypse(3)