1CPAN::Reporter(3) User Contributed Perl Documentation CPAN::Reporter(3)
2
6 CPAN::Reporter - Adds CPAN Testers reporting to CPAN.pm
7
9 version 1.2018
10
12 From the CPAN shell:
13 cpan> install Task::CPAN::Reporter
15 cpan> reload cpan
16 cpan> o conf init test_report
17 Installing Task::CPAN::Reporter will pull in additional dependencies
19 that new CPAN Testers will need.
20 Advanced CPAN Testers with custom Test::Reporter::Transport setups may
22 wish to install only CPAN::Reporter, which has fewer dependencies.
23
25 The CPAN Testers project captures and analyzes detailed results from
26 building and testing CPAN distributions on multiple operating systems
27 and multiple versions of Perl. This provides valuable feedback to
28 module authors and potential users to identify bugs or platform
29 compatibility issues and improves the overall quality and value of
30 CPAN.
31 One way individuals can contribute is to send a report for each module
33 that they test or install. CPAN::Reporter is an add-on for the CPAN.pm
34 module to send the results of building and testing modules to the CPAN
35 Testers project. Full support for CPAN::Reporter is available in
36 CPAN.pm as of version 1.92.
37
39 Installation
40 The first step in using CPAN::Reporter is to install it using whatever
41 version of CPAN.pm is already installed. CPAN.pm will be upgraded as a
42 dependency if necessary.
43 cpan> install CPAN::Reporter
45 If CPAN.pm was upgraded, it needs to be reloaded.
47 cpan> reload cpan
49 Configuration
51 If upgrading from a very old version of CPAN.pm, users may be prompted
52 to renew their configuration settings, including the 'test_report'
53 option to enable CPAN::Reporter.
54 If not prompted automatically, users should manually initialize
56 CPAN::Reporter support. After enabling CPAN::Reporter, CPAN.pm will
57 automatically continue with interactive configuration of CPAN::Reporter
58 options.
59 cpan> o conf init test_report
61 Users will need to enter an email address in one of the following
63 formats:
64 johndoe@example.com
66 John Doe <johndoe@example.com>
67 "John Q. Public" <johnqpublic@example.com>
68 Users that are new to CPAN::Reporter should accept the recommended
70 values for other configuration options.
71 Users will be prompted to create a Metabase profile file that uniquely
73 identifies their test reports. See "The Metabase" below for details.
74 After completing interactive configuration, be sure to commit (save)
76 the CPAN configuration changes.
77 cpan> o conf commit
79 See CPAN::Reporter::Config for advanced configuration settings.
81 The Metabase
83 CPAN::Reporter sends test reports to a server known as the Metabase.
85 This requires an active Internet connection and a profile file. To
86 create the profile, users will need to run "metabase-profile" from a
87 terminal window and fill the information at the prompts. This will
88 create a file called "metabase_id.json" in the current directory. That
89 file should be moved to the ".cpanreporter" directory inside the user's
90 home directory.
91 Users with an existing metabase profile file (e.g. from another
93 machine), should copy it into the ".cpanreporter" directory instead of
94 creating a new one. Profile files may be located outside the
95 ".cpanreporter" directory by following instructions in
96 CPAN::Reporter::Config.
97 Default Test Comments
99 This module puts default text into the "TESTER COMMENTS" section,
101 typically, "none provided" if doing interactive testing, or, if doing
102 smoke testing that sets C<$ENV{AUTOMATED_TESTING}> to a true value,
103 "this report is from an automated smoke testing program and was not
104 reviewed by a human for accuracy." If C<CPAN::Reporter> is configured
105 to allow editing of the report, this can be edited during submission.
106 If you wish to override the default comment, you can create a file
108 named C<comment.txt> in the configuration directory (typically
109 ".cpanreporter" under the user's home directory), with the default
110 comment you would like to appear.
111 Note that if your test is an automated smoke test
113 (C<$ENV{AUTOMATED_TESTING}> is set to a true value), the smoke test
114 notice ("this report is from an automated smoke testing program and was
115 not reviewed by a human for accuracy") is included along with a blank
116 line before your C<comment.txt>, so that it is always possible to
117 distinguish automated tests from non-automated tests that use this
118 module.
119 Using CPAN::Reporter
121 Once CPAN::Reporter is enabled and configured, test or install modules
122 with CPAN.pm as usual.
123 For example, to test the File::Marker module:
125 cpan> test File::Marker
127 If a distribution's tests fail, users will be prompted to edit the
129 report to add additional information that might help the author
130 understand the failure.
131
133 CPAN::Reporter will assign one of the following grades to the report:
134 · "pass" -- distribution built and tested correctly
136 · "fail" -- distribution failed to test correctly
138 · "unknown" -- distribution failed to build, had no test suite or
140 outcome was inconclusive
141 · "na" --- distribution is not applicable to this platform and/or
143 version of Perl
144 In returning results of the test suite to CPAN.pm, "pass" and "unknown"
146 are considered successful attempts to "make test" or "Build test" and
147 will not prevent installation. "fail" and "na" are considered to be
148 failures and CPAN.pm will not install unless forced.
149 An error from Makefile.PL/Build.PL or make/Build will also be graded as
151 "unknown" and a failure will be signaled to CPAN.pm.
152 If prerequisites specified in "Makefile.PL" or "Build.PL" are not
154 available, no report will be generated and a failure will be signaled
155 to CPAN.pm.
156
158 CPAN::Reporter includes information in the test report about
159 environment variables and special Perl variables that could be
160 affecting test results in order to help module authors interpret the
161 results of the tests. This includes information about paths, terminal,
162 locale, user/group ID, installed toolchain modules (e.g.
163 ExtUtils::MakeMaker) and so on.
164 These have been intentionally limited to items that should not cause
166 harmful personal information to be revealed -- it does not include your
167 entire environment. Nevertheless, please do not use CPAN::Reporter if
168 you are concerned about the disclosure of this information as part of
169 your test report.
170 Users wishing to review this information may choose to edit the report
172 prior to sending it.
173
175 Using command_timeout on Linux may cause problems. See
176 <https://rt.cpan.org/Ticket/Display.html?id=62310>
177 Please report any bugs or feature using the CPAN Request Tracker. Bugs
179 can be submitted through the web interface at
180 <http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Reporter>
181 When submitting a bug or request, please include a test-file or a patch
183 to an existing test-file that illustrates the bug or desired feature.
184
186 Information about CPAN::Testers:
187 · CPAN::Testers -- overview of CPAN Testers architecture stack
189 · <http://www.cpantesters.org> -- project home with all reports
191 · <http://wiki.cpantesters.org> -- documentation and wiki
193 Additional Documentation:
195 · CPAN::Reporter::Config -- advanced configuration settings
197 · CPAN::Reporter::FAQ -- hints and tips
199
201 Bugs / Feature Requests
202 Please report any bugs or feature requests through the issue tracker at
203 <https://github.com/cpan-testers/CPAN-Reporter/issues>. You will be
204 notified automatically of any progress on your issue.
205 Source Code
207 This is open source software. The code repository is available for
208 public review and contribution under the terms of the license.
209 <https://github.com/cpan-testers/CPAN-Reporter>
211 git clone https://github.com/cpan-testers/CPAN-Reporter.git
213
215 David Golden <dagolden@cpan.org>
216
218 · Alexandr Ciornii <alexchorny@gmail.com>
219 · Breno G. de Oliveira <garu@cpan.org>
221 · Christian Walde <walde.christian@googlemail.com>
223 · Ed J <mohawk2@users.noreply.github.com>
225 · Joel Maslak <jmaslak@antelope.net>
227 · Kent Fredric <kentfredric@gmail.com>
229 · Matthew Musgrove <mr.muskrat@gmail.com>
231 · Patrice Clement <monsieurp@gentoo.org>
233 · Reini Urban <rurban@cpanel.net>
235 · Scott Wiersdorf <scott@perlcode.org>
237 · Slaven Rezic <slaven@rezic.de>
239
241 This software is Copyright (c) 2006 by David Golden.
242 This is free software, licensed under:
244 The Apache License, Version 2.0, January 2004
246perl v5.30.0 2019-07-26 CPAN::Reporter(3)