README
1NAME
2 Test::DiagINC - List modules and versions loaded if tests fail
3
4VERSION
5 version 0.008
6
7SYNOPSIS
8 # preferably load before anything else
9 use if $ENV{AUTOMATED_TESTING}, 'Test::DiagINC';
10 use Test::More;
11
12DESCRIPTION
13 Assuming you shipped your module to CPAN with working tests, test
14 failures from CPAN Testers <http://www.cpantesters.org/> might be due to
15 platform issues, Perl version issues or problems with dependencies. This
16 module helps you diagnose deep dependency problems by showing you
17 exactly what modules and versions were loaded during a test run.
18
19 When this module is loaded, it sets up an "END" block that will take
20 action if the program is about to exit with a non-zero exit code or if
21 $test_builder->is_passing is false by the time the "END" block is
22 reached. If that happens, this module prints out the names and version
23 numbers of non-local modules appearing in %INC at the end of the test.
24
25 For example:
26
27 $ perl -MTest::DiagINC -MTest::More -e 'fail("meh"); done_testing'
28 not ok 1 - meh
29 # Failed test 'meh'
30 # at -e line 1.
31 1..1
32 # Looks like you failed 1 test of 1.
33 # Listing modules and versions from %INC
34 # 5.018002 Config
35 # 5.68 Exporter
36 # 5.68 Exporter::Heavy
37 # 1.07 PerlIO
38 # 0.98 Test::Builder
39 # 0.98 Test::Builder::Module
40 # 0.003 Test::DiagINC
41 # 0.98 Test::More
42 # 1.22 overload
43 # 0.02 overloading
44 # 1.07 strict
45 # 1.03 vars
46 # 1.18 warnings
47 # 1.02 warnings::register
48
49 This module deliberately does not load any other modules during runtime,
50 instead delaying all loads until it needs to generate a failure report
51 in its "END" block. The only exception is loading strict and warnings
52 for self-check if and only if "RELEASE_TESTING" is true. Therefore an
53 empty invocation will look like this:
54
55 $ perl -MTest::DiagINC -e 'exit(1)'
56 # Listing modules from %INC
57 # 0.003 Test::DiagINC
58
59 NOTE: Because this module uses an "END" block, it is a good idea to load
60 it as early as possible, so the "END" block it installs will execute as
61 late as possible (see perlmod for details on how this works). While this
62 module does employ some cleverness to work around load order, it is
63 still a heuristic and is no substitute to loading this module early. A
64 notable side-effect is when a module is loaded in an "END" block
65 executing after the one installed by this library: such modules will be
66 "invisible" to us and will not be reported as part of the diagnostic
67 report.
68
69 Modules that appear to be sourced from below the current directory when
70 "Test::DiagINC" was loaded will be excluded from the report (e.g.
71 excludes local modules from "./", "lib/", "t/lib", and so on).
72
73 The heuristic of searching %INC for loaded modules may fail if the
74 module path loaded does not map to a package within the module file.
75
76 If "Test::More" is loaded, the output will go via the "diag" function.
77 Otherwise, it will just be sent to STDERR.
78
79SUPPORT
80 Bugs / Feature Requests
81 Please report any bugs or feature requests through the issue tracker at
82 <https://github.com/dagolden/Test-DiagINC/issues>. You will be notified
83 automatically of any progress on your issue.
84
85 Source Code
86 This is open source software. The code repository is available for
87 public review and contribution under the terms of the license.
88
89 <https://github.com/dagolden/Test-DiagINC>
90
91 git clone https://github.com/dagolden/Test-DiagINC.git
92
93AUTHOR
94 David Golden <dagolden@cpan.org>
95
96CONTRIBUTORS
97 * Peter Rabbitson <ribasushi@cpan.org>
98
99 * Roy Ivy III <rivy.dev@gmail.com>
100
101COPYRIGHT AND LICENSE
102 This software is Copyright (c) 2014 by David Golden.
103
104 This is free software, licensed under:
105
106 The Apache License, Version 2.0, January 2004
107
108