README
1NAME
2 Test::Reporter - sends test results to cpan-testers@perl.org
3
4VERSION
5 version 1.62
6
7SYNOPSIS
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 => 'whoever@wherever.net (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
45DESCRIPTION
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
67ATTRIBUTES
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 <jdoe@example.com>".
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
158METHODS
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 cpan-testers@perl.org 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
246CAVEATS
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
252SEE 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
259SUPPORT
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
273AUTHORS
274 * Adam J. Foxson <afoxson@pobox.com>
275
276 * David Golden <dagolden@cpan.org>
277
278 * Kirrily "Skud" Robert <skud@cpan.org>
279
280 * Ricardo Signes <rjbs@cpan.org>
281
282 * Richard Soderberg <rsod@cpan.org>
283
284 * Kurt Starsinic <Kurt.Starsinic@isinet.com>
285
286CONTRIBUTORS
287 * Andreas Koenig <andk@cpan.org>
288
289 * Ed J <mohawk2@users.noreply.github.com>
290
291 * Tatsuhiko Miyagawa <miyagawa@bulknews.net>
292
293 * Vincent Pit <perl@profvince.com>
294
295COPYRIGHT 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
301