| 1 |
NAME |
| 2 |
Test::Reporter - sends test results to [email protected] |
| 3 |
|
| 4 |
VERSION |
| 5 |
version 1.62 |
| 6 |
|
| 7 |
SYNOPSIS |
| 8 |
use Test::Reporter; |
| 9 |
|
| 10 |
my $reporter = Test::Reporter->new( |
| 11 |
transport => 'File', |
| 12 |
transport_args => [ '/tmp' ], |
| 13 |
); |
| 14 |
|
| 15 |
$reporter->grade('pass'); |
| 16 |
$reporter->distribution('Mail-Freshmeat-1.20'); |
| 17 |
$reporter->send() || die $reporter->errstr(); |
| 18 |
|
| 19 |
# or |
| 20 |
|
| 21 |
my $reporter = Test::Reporter->new( |
| 22 |
transport => 'File', |
| 23 |
transport_args => [ '/tmp' ], |
| 24 |
); |
| 25 |
|
| 26 |
$reporter->grade('fail'); |
| 27 |
$reporter->distribution('Mail-Freshmeat-1.20'); |
| 28 |
$reporter->comments('output of a failed make test goes here...'); |
| 29 |
$reporter->edit_comments(); # if you want to edit comments in an editor |
| 30 |
$reporter->send() || die $reporter->errstr(); |
| 31 |
|
| 32 |
# or |
| 33 |
|
| 34 |
my $reporter = Test::Reporter->new( |
| 35 |
transport => 'File', |
| 36 |
transport_args => [ '/tmp' ], |
| 37 |
grade => 'fail', |
| 38 |
distribution => 'Mail-Freshmeat-1.20', |
| 39 |
from => '[email protected] (Whoever Wherever)', |
| 40 |
comments => 'output of a failed make test goes here...', |
| 41 |
via => 'CPANPLUS X.Y.Z', |
| 42 |
); |
| 43 |
$reporter->send() || die $reporter->errstr(); |
| 44 |
|
| 45 |
DESCRIPTION |
| 46 |
Test::Reporter reports the test results of any given distribution to the |
| 47 |
CPAN Testers project. Test::Reporter has wide support for various |
| 48 |
perl5's and platforms. |
| 49 |
|
| 50 |
CPAN Testers no longer receives test reports by email, but reports still |
| 51 |
resemble an email message. This module has numerous legacy "features" |
| 52 |
left over from the days of email transport. |
| 53 |
|
| 54 |
Transport mechanism |
| 55 |
The choice of transport is set with the "transport" argument. CPAN |
| 56 |
Testers should usually install Test::Reporter::Transport::Metabase and |
| 57 |
use 'Metabase' as the "transport". See that module for necessary |
| 58 |
transport arguments. Advanced testers may wish to test on a machine |
| 59 |
different from the one used to send reports. Consult the CPAN Testers |
| 60 |
Wiki <http://wiki.cpantesters.org/> for examples using other transport |
| 61 |
classes. |
| 62 |
|
| 63 |
The legacy email-based transports have been split out into a separate |
| 64 |
Test::Reporter::Transport::Legacy distribution and methods solely |
| 65 |
related to email have been deprecated. |
| 66 |
|
| 67 |
ATTRIBUTES |
| 68 |
Required attributes |
| 69 |
* distribution |
| 70 |
|
| 71 |
Gets or sets the name of the distribution you're working on, for |
| 72 |
example Foo-Bar-0.01. There are no restrictions on what can be put |
| 73 |
here. |
| 74 |
|
| 75 |
* from |
| 76 |
|
| 77 |
Gets or sets the e-mail address of the individual submitting the |
| 78 |
test report, i.e. "John Doe <[email protected]>". |
| 79 |
|
| 80 |
* grade |
| 81 |
|
| 82 |
Gets or sets the success or failure of the distributions's 'make |
| 83 |
test' result. This must be one of: |
| 84 |
|
| 85 |
grade meaning |
| 86 |
----- ------- |
| 87 |
pass all tests passed |
| 88 |
fail one or more tests failed |
| 89 |
na distribution will not work on this platform |
| 90 |
unknown tests did not exist or could not be run |
| 91 |
|
| 92 |
Transport attributes |
| 93 |
* transport |
| 94 |
|
| 95 |
Gets or sets the transport type. The transport type argument is |
| 96 |
refers to a 'Test::Reporter::Transport' subclass. The default is |
| 97 |
'Null', which uses the Test::Reporter::Transport::Null class and |
| 98 |
does nothing when "send" is called. |
| 99 |
|
| 100 |
You can add additional arguments after the transport selection. |
| 101 |
These will be passed to the constructor of the lower-level |
| 102 |
transport. See "transport_args". |
| 103 |
|
| 104 |
$reporter->transport( |
| 105 |
'File', '/tmp' |
| 106 |
); |
| 107 |
|
| 108 |
This is not designed to be an extensible platform upon which to |
| 109 |
build transport plugins. That functionality is planned for the |
| 110 |
next-generation release of Test::Reporter, which will reside in the |
| 111 |
CPAN::Testers namespace. |
| 112 |
|
| 113 |
* transport_args |
| 114 |
|
| 115 |
Optional. Gets or sets transport arguments that will used in the |
| 116 |
constructor for the selected transport, as appropriate. |
| 117 |
|
| 118 |
Optional attributes |
| 119 |
* comments |
| 120 |
|
| 121 |
Gets or sets the comments on the test report. This is most commonly |
| 122 |
used for distributions that did not pass a 'make test'. |
| 123 |
|
| 124 |
* debug |
| 125 |
|
| 126 |
Gets or sets the value that will turn debugging on or off. Debug |
| 127 |
messages are sent to STDERR. 1 for on, 0 for off. Debugging |
| 128 |
generates very verbose output and is useful mainly for finding bugs |
| 129 |
in Test::Reporter itself. |
| 130 |
|
| 131 |
* dir |
| 132 |
|
| 133 |
Defaults to the current working directory. This method specifies the |
| 134 |
directory that write() writes test report files to. |
| 135 |
|
| 136 |
* timeout |
| 137 |
|
| 138 |
Gets or sets the timeout value for the submission of test reports. |
| 139 |
Default is 120 seconds. |
| 140 |
|
| 141 |
* via |
| 142 |
|
| 143 |
Gets or sets the value that will be appended to X-Reported-Via, |
| 144 |
generally this is useful for distributions that use Test::Reporter |
| 145 |
to report test results. This would be something like "CPANPLUS |
| 146 |
0.036". |
| 147 |
|
| 148 |
Deprecated attributes |
| 149 |
CPAN Testers no longer uses email for submitting reports. These |
| 150 |
attributes are deprecated. |
| 151 |
|
| 152 |
* address |
| 153 |
|
| 154 |
* mail_send_args |
| 155 |
|
| 156 |
* mx |
| 157 |
|
| 158 |
METHODS |
| 159 |
* new |
| 160 |
|
| 161 |
This constructor returns a Test::Reporter object. |
| 162 |
|
| 163 |
* perl_version |
| 164 |
|
| 165 |
Returns a hashref containing _archname, _osvers, and _myconfig based |
| 166 |
upon the perl that you are using. Alternatively, you may supply a |
| 167 |
different perl (path to the binary) as an argument, in which case |
| 168 |
the supplied perl will be used as the basis of the above data. Make |
| 169 |
sure you protect it from the shell in case there are spaces in the |
| 170 |
path: |
| 171 |
|
| 172 |
$reporter->perl_version(qq{"$^X"}); |
| 173 |
|
| 174 |
* subject |
| 175 |
|
| 176 |
Returns the subject line of a report, i.e. "PASS Mail-Freshmeat-1.20 |
| 177 |
Darwin 6.0". 'grade' and 'distribution' must first be specified |
| 178 |
before calling this method. |
| 179 |
|
| 180 |
* report |
| 181 |
|
| 182 |
Returns the actual content of a report, i.e. "This distribution has |
| 183 |
been tested as part of the cpan-testers...". 'comments' must first |
| 184 |
be specified before calling this method, if you have comments to |
| 185 |
make and expect them to be included in the report. |
| 186 |
|
| 187 |
* send |
| 188 |
|
| 189 |
Sends the test report to [email protected] via the defined |
| 190 |
"transport" mechanism. You must check errstr() on a send() in order |
| 191 |
to be guaranteed delivery. |
| 192 |
|
| 193 |
* edit_comments |
| 194 |
|
| 195 |
Allows one to interactively edit the comments within a text editor. |
| 196 |
comments() doesn't have to be first specified, but it will work |
| 197 |
properly if it was. Accepts an optional hash of arguments: |
| 198 |
|
| 199 |
* suffix |
| 200 |
|
| 201 |
Optional. Allows one to specify the suffix ("extension") of the |
| 202 |
temp file used by edit_comments. Defaults to '.txt'. |
| 203 |
|
| 204 |
* errstr |
| 205 |
|
| 206 |
Returns an error message describing why something failed. You must |
| 207 |
check errstr() on a send() in order to be guaranteed delivery. |
| 208 |
|
| 209 |
* write and read |
| 210 |
|
| 211 |
These methods are used in situations where you wish to save reports |
| 212 |
locally rather than transmitting them to CPAN Testers immediately. |
| 213 |
You use write() on the machine that you are testing from, transfer |
| 214 |
the written test reports from the testing machine to the sending |
| 215 |
machine, and use read() on the machine that you actually want to |
| 216 |
submit the reports from. write() will write a file in an internal |
| 217 |
format that contains 'From', 'Subject', and the content of the |
| 218 |
report. The filename will be represented as: |
| 219 |
grade.distribution.archname.osvers.seconds_since_epoch.pid.rpt. |
| 220 |
write() uses the value of dir() if it was specified, else the cwd. |
| 221 |
|
| 222 |
On the machine you are testing from: |
| 223 |
|
| 224 |
my $reporter = Test::Reporter->new |
| 225 |
( |
| 226 |
grade => 'pass', |
| 227 |
distribution => 'Test-Reporter-1.16', |
| 228 |
)->write(); |
| 229 |
|
| 230 |
On the machine you are submitting from: |
| 231 |
|
| 232 |
# wrap in an opendir if you've a lot to submit |
| 233 |
my $reporter; |
| 234 |
$reporter = Test::Reporter->new()->read( |
| 235 |
'pass.Test-Reporter-1.16.i686-linux.2.2.16.1046685296.14961.rpt' |
| 236 |
)->send() || die $reporter->errstr(); |
| 237 |
|
| 238 |
write() also accepts an optional filehandle argument: |
| 239 |
|
| 240 |
my $fh; open $fh, '>-'; # create a STDOUT filehandle object |
| 241 |
$reporter->write($fh); # prints the report to STDOUT |
| 242 |
|
| 243 |
Deprecated methods |
| 244 |
* message_id |
| 245 |
|
| 246 |
CAVEATS |
| 247 |
If you experience a long delay sending reports with Test::Reporter, you |
| 248 |
may be experiencing a wait as Test::Reporter attempts to determine your |
| 249 |
email address. Always use the "from" parameter to set your email address |
| 250 |
explicitly. |
| 251 |
|
| 252 |
SEE ALSO |
| 253 |
For more about CPAN Testers: |
| 254 |
|
| 255 |
* CPAN Testers reports <http://www.cpantesters.org/> |
| 256 |
|
| 257 |
* CPAN Testers wiki <http://wiki.cpantesters.org/> |
| 258 |
|
| 259 |
SUPPORT |
| 260 |
Bugs / Feature Requests |
| 261 |
Please report any bugs or feature requests through the issue tracker at |
| 262 |
<https://github.com/cpan-testers/Test-Reporter/issues>. You will be |
| 263 |
notified automatically of any progress on your issue. |
| 264 |
|
| 265 |
Source Code |
| 266 |
This is open source software. The code repository is available for |
| 267 |
public review and contribution under the terms of the license. |
| 268 |
|
| 269 |
<https://github.com/cpan-testers/Test-Reporter> |
| 270 |
|
| 271 |
git clone https://github.com/cpan-testers/Test-Reporter.git |
| 272 |
|
| 273 |
AUTHORS |
| 274 |
* Adam J. Foxson <[email protected]> |
| 275 |
|
| 276 |
* David Golden <[email protected]> |
| 277 |
|
| 278 |
* Kirrily "Skud" Robert <[email protected]> |
| 279 |
|
| 280 |
* Ricardo Signes <[email protected]> |
| 281 |
|
| 282 |
* Richard Soderberg <[email protected]> |
| 283 |
|
| 284 |
* Kurt Starsinic <[email protected]> |
| 285 |
|
| 286 |
CONTRIBUTORS |
| 287 |
* Andreas Koenig <[email protected]> |
| 288 |
|
| 289 |
* Ed J <[email protected]> |
| 290 |
|
| 291 |
* Tatsuhiko Miyagawa <[email protected]> |
| 292 |
|
| 293 |
* Vincent Pit <[email protected]> |
| 294 |
|
| 295 |
COPYRIGHT AND LICENSE |
| 296 |
This software is copyright (c) 2015 by Authors and Contributors. |
| 297 |
|
| 298 |
This is free software; you can redistribute it and/or modify it under |
| 299 |
the same terms as the Perl 5 programming language system itself. |
| 300 |
|