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