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

NAME

6       Test::Apocalypse - Apocalypse's favorite tests bundled into a simple
7       interface
8

VERSION

10         This document describes v1.006 of Test::Apocalypse - released October 25, 2014 as part of Test-Apocalypse.
11

SYNOPSIS

13               #!/usr/bin/perl
14               use strict; use warnings;
15
16               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

DESCRIPTION

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
31       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
38       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
44   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
52               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

Methods

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
65       allow
66
67       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
71               # run only the EOL test and disable all other tests
72               is_apocalypse_here( {
73                       allow   => qr/^EOL$/,
74               } );
75
76               # run all "dist" tests
77               is_apocalypse_here( {
78                       allow   => 'dist',
79               } );
80
81       deny
82
83       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
87               # disable Pod_Coverage test and enable all other tests
88               is_apocalypse_here( {
89                       deny    => qr/^Pod_Coverage$/,
90               } );
91
92               # disable all pod tests
93               is_apocalypse_here( {
94                       deny    => 'pod',
95               } );
96
97   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
102               my @tests = Test::Apocalypse->plugins;
103

EXPORT

105       Automatically exports the "is_apocalypse_here" sub.
106

MORE IDEAS

108       •   Test::NoSmartComments
109
110           I don't use Smart::Comments but it might be useful? I LOVE BLOAT!
111           :)
112
113       •   Better POD spelling checker?
114
115           Test::Spelling is ancient, and often blows up. There's a
116           Test::Pod::Spelling on CPAN but it is flaky too :(
117
118       •   Document the way we do plugins so others can add to this testsuite
119           :)
120
121       •   POD standards check
122
123           Do we have SYNOPSIS, ABSTRACT, SUPPORT, etc sections? ( PerlCritic
124           can do that! Need to investigate more... )
125
126       •   Integrate Test::UniqueTestNames into the testsuite
127
128           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
133       •   META.yml checks
134
135           We should make sure that the META.yml includes the "repository",
136           "license", and other useful keys!
137
138       •   Other AUTHORs
139
140           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
143       •   indirect syntax
144
145           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
149       •   Test::PPPort
150
151           Already implemented as PPPort.pm but it's less invasive than my
152           version, ha!
153
154       •   Test::DependentModules
155
156           This is a crazy test, but would help tremendously in finding
157           regressions in your code!
158
159       •   Test::CleanNamespaces
160
161           I don't exclusively code in Moose, but this could be useful...
162
163       •   no internet?
164
165           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
169                   <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
191   Modules that I considered but decided against using
192       •   Test::Distribution
193
194           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
197       •   Test::Module::Used and Test::Dependencies
198
199           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
203       •   Test::MyDeps
204
205           Superseded by Test::DependentModules. Also, I don't want to waste a
206           lot of time on each testrun testing other modules!
207
208       •   Test::NoTabs
209
210           I always use tabs! :(
211
212       •   Test::CheckManifest
213
214           This was a buggy module that I dropped and is now using
215           Test::DistManifest
216
217       •   Test::Dist
218
219           This is pretty much the same thing as this dist ;)
220
221       •   Test::PureASCII
222
223           This rocks, as I don't care about unicode in my perl! ;)
224
225       •   Test::LatestPrereqs
226
227           This looks cool but we need to fiddle with config files? My
228           OutdatedPrereqs test already covers it pretty well...
229
230       •   Test::Pod::Content
231
232           This is useful, but not everyone has the same POD layout. It would
233           be too much work to try and generalize this...
234
235       •   Test::GreaterVersion
236
237           Since I never use CPAN, this is non-functional for me. However, it
238           might be useful for someone?
239
240       •   Test::Kwalitee
241
242           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
246       •   Test::LoadAllModules
247
248           This is very similar to Test::UseAllModules but looks more
249           complicated. Also, I already have enough tests that do that ;)
250
251       •   Test::ModuleReady
252
253           This looks like a nice module, but what it does is already covered
254           by the numerous tests in this dist...
255
256       •   Test::PerlTidy
257
258           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
263       •   Test::Install::METArequires
264
265           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
269       •   Test::Perl::Metrics::Simple
270
271           This just tests your Cyclomatic complexity and was the starting
272           point for my homebrew solution.
273

SUPPORT

275   Perldoc
276       You can find documentation for this module with the perldoc command.
277
278         perldoc Test::Apocalypse
279
280   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
285       •   MetaCPAN
286
287           A modern, open-source CPAN search engine, useful to view POD in
288           HTML format.
289
290           <http://metacpan.org/release/Test-Apocalypse>
291
292       •   Search CPAN
293
294           The default CPAN search engine, useful to view POD in HTML format.
295
296           <http://search.cpan.org/dist/Test-Apocalypse>
297
298       •   RT: CPAN's Bug Tracker
299
300           The RT ( Request Tracker ) website is the default bug/issue
301           tracking system for CPAN.
302
303           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Apocalypse>
304
305       •   AnnoCPAN
306
307           The AnnoCPAN is a website that allows community annotations of Perl
308           module documentation.
309
310           <http://annocpan.org/dist/Test-Apocalypse>
311
312       •   CPAN Ratings
313
314           The CPAN Ratings is a website that allows community ratings and
315           reviews of Perl modules.
316
317           <http://cpanratings.perl.org/d/Test-Apocalypse>
318
319       •   CPAN Forum
320
321           The CPAN Forum is a web forum for discussing Perl modules.
322
323           <http://cpanforum.com/dist/Test-Apocalypse>
324
325       •   CPANTS
326
327           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
328           of a distribution.
329
330           <http://cpants.perl.org/dist/overview/Test-Apocalypse>
331
332       •   CPAN Testers
333
334           The CPAN Testers is a network of smokers who run automated tests on
335           uploaded CPAN distributions.
336
337           <http://www.cpantesters.org/distro/T/Test-Apocalypse>
338
339       •   CPAN Testers Matrix
340
341           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
345           <http://matrix.cpantesters.org/?dist=Test-Apocalypse>
346
347       •   CPAN Testers Dependencies
348
349           The CPAN Testers Dependencies is a website that shows a chart of
350           the test results of all dependencies for a distribution.
351
352           <http://deps.cpantesters.org/?module=Test::Apocalypse>
353
354   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
358   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
365       •   irc.perl.org
366
367           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
370       •   irc.freenode.net
371
372           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
375       •   irc.efnet.org
376
377           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
380   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
387   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
393       <https://github.com/apocalypse/perl-test-apocalypse>
394
395         git clone git://github.com/apocalypse/perl-test-apocalypse.git
396

AUTHOR

398       Apocalypse <APOCAL@cpan.org>
399
400   CONTRIBUTORS
401       •   Apocalypse <apoc@blackhole.(none)>
402
403       •   Apocalypse <apoc@satellite.(none)>
404
405       •   Apocalypse <perl@0ne.us>
406
407       •   Ryan Niebur <ryanryan52@gmail.com>
408

ACKNOWLEDGEMENTS

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
416       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
419       The full text of the license can be found in the LICENSE file included
420       with this distribution.
421

DISCLAIMER OF WARRANTY

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
432       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.
441
442
443
444perl v5.38.0                      2023-07-21               Test::Apocalypse(3)
Impressum