2 Test::Reporter - sends test results to cpan-testers@perl.org
7 my $reporter = Test::Reporter->new();
9 $reporter->grade('pass');
10 $reporter->distribution('Mail-Freshmeat-1.20');
11 $reporter->send() || die $reporter->errstr();
15 my $reporter = Test::Reporter->new();
17 $reporter->grade('fail');
18 $reporter->distribution('Mail-Freshmeat-1.20');
19 $reporter->comments('output of a failed make test goes here...');
20 $reporter->edit_comments(); # if you want to edit comments in an editor
21 $reporter->send('afoxson@cpan.org') || die $reporter->errstr();
25 my $reporter = Test::Reporter->new(
27 distribution => 'Mail-Freshmeat-1.20',
28 from => 'whoever@wherever.net (Whoever Wherever)',
29 comments => 'output of a failed make test goes here...',
30 via => 'CPANPLUS X.Y.Z',
32 $reporter->send() || die $reporter->errstr();
35 Test::Reporter reports the test results of any given distribution to the
36 CPAN Testers. Test::Reporter has wide support for various perl5's and
37 platforms. For further information visit the below links:
39 * <http://cpantesters.perl.org/>
40 CPAN Testers reports (new site)
42 * <http://testers.cpan.org/>
43 CPAN Testers reports (old site)
45 * <http://cpantest.grango.org/>
46 The new CPAN Testers Wiki (thanks Barbie!)
48 * <http://lists.cpan.org/showlist.cgi?name=cpan-testers>
49 The cpan-testers mailing list
51 Test::Reporter itself--as a project--also has several links for your
54 * <http://code.google.com/p/test-reporter/>
55 Test::Reporter's master project page
57 * <http://groups.google.com/group/test-reporter>
58 Discussion group for Test::Reporter
60 * <http://code.google.com/p/test-reporter/w/list>
61 The Wiki for Test::Reporter
63 * <http://repo.or.cz/w/test-reporter.git>
64 Test::Reporter's public git source code repository.
66 * <http://search.cpan.org/dist/Test-Reporter/>
67 Test::Reporter on CPAN
69 * <http://code.google.com/p/test-reporter/issues/list>
70 UNFORTUNATELY, WE ARE UNABLE TO ACCEPT TICKETS FILED WITH RT.
72 Please file all bug reports and enhancement requests at our Google
73 Code issue tracker. Thank you for your support and understanding.
75 * <http://backpan.cpan.org/authors/id/F/FO/FOX/>
76 * <http://backpan.cpan.org/authors/id/A/AF/AFOXSON/>
77 If you happen to--for some strange reason--be looking for primordial
78 versions of Test::Reporter, you can almost certainly find them at
83 Optional. Gets or sets the e-mail address that the reports will be
84 sent to. By default, this is set to cpan-testers@perl.org. You
85 shouldn't need this unless the CPAN Tester's change the e-mail
86 address to send report's to.
89 Optional. Gets or sets the comments on the test report. This is most
90 commonly used for distributions that did not pass a 'make test'.
93 Optional. Gets or sets the value that will turn debugging on or off.
94 Debug messages are sent to STDERR. 1 for on, 0 for off. Debugging
95 generates very verbose output and is useful mainly for finding bugs
96 in Test::Reporter itself.
99 Optional. Defaults to the current working directory. This method
100 specifies the directory that write() writes test report files to.
103 Gets or sets the name of the distribution you're working on, for
104 example Foo-Bar-0.01. There are no restrictions on what can be put
108 Optional. Allows one to interactively edit the comments within a
109 text editor. comments() doesn't have to be first specified, but it
110 will work properly if it was. Accepts an optional hash of arguments:
113 Optional. Allows one to specify the suffix ("extension") of the
114 temp file used by edit_comments. Defaults to '.txt'.
117 Returns an error message describing why something failed. You must
118 check errstr() on a send() in order to be guaranteed delivery. This
119 is optional if you don't intend to use Test::Reporter to send
120 reports via e-mail, see 'send' below for more information.
123 Optional. Gets or sets the e-mail address of the individual
124 submitting the test report, i.e. "afoxson@pobox.com (Adam Foxson)".
125 This is mostly of use to testers running under Windows, since
126 Test::Reporter will usually figure this out automatically.
127 Alternatively, you can use the MAILADDRESS environmental variable to
131 Gets or sets the success or failure of the distributions's 'make
132 test' result. This must be one of:
136 pass all tests passed
137 fail one or more tests failed
138 na distribution will not work on this platform
139 unknown distribution did not include tests
142 Optional. If you have MailTools installed and you want to have it
143 behave in a non-default manner, parameters that you give this method
144 will be passed directly to the constructor of Mail::Mailer. See
145 Mail::Mailer and Mail::Send for details.
148 Returns an automatically generated Message ID. This Message ID will
149 later be included as an outgoing mail header in the test report
150 e-mail. This was included to conform to local mail policies at
151 perl.org. This method courtesy of Email::MessageID.
154 Optional. Gets or sets the mail exchangers that will be used to send
155 the test reports. If you override the default values make sure you
156 pass in a reference to an array. By default, this contains the MX's
157 known at the time of release for perl.org. If you do not have
158 Mail::Send installed (thus using the Net::SMTP interface) and do
159 have Net::DNS installed it will dynamically retrieve the latest
160 MX's. You really shouldn't need to use this unless the hardcoded
161 MX's have become wrong and you don't have Net::DNS installed.
164 This constructor returns a Test::Reporter object. It will optionally
165 accept named parameters for: mx, address, grade, distribution, from,
166 comments, via, timeout, debug, dir, perl_version, and transport.
169 Returns a hashref containing _archname, _osvers, and _myconfig based
170 upon the perl that you are using. Alternatively, you may supply a
171 different perl (path to the binary) as an argument, in which case
172 the supplied perl will be used as the basis of the above data.
175 Returns the actual content of a report, i.e. "This distribution has
176 been tested as part of the cpan-testers...". 'comments' must first
177 be specified before calling this method, if you have comments to
178 make and expect them to be included in the report.
181 Sends the test report to cpan-testers@perl.org and cc's the e-mail
182 to the specified recipients, if any. If you do specify recipients to
183 be cc'd and you do not have Mail::Send installed be sure that you
184 use the author's @cpan.org address otherwise they will not be
185 delivered. You must check errstr() on a send() in order to be
186 guaranteed delivery. Technically, this is optional, as you may use
187 Test::Reporter to only obtain the 'subject' and 'report' without
188 sending an e-mail at all, although that would be unusual.
191 Returns the subject line of a report, i.e. "PASS Mail-Freshmeat-1.20
192 Darwin 6.0". 'grade' and 'distribution' must first be specified
193 before calling this method.
196 Optional. Gets or sets the timeout value for the submission of test
197 reports. Default is 120 seconds.
200 Optional. Gets or sets the transport method. If you do not specify a
201 transport, one will be selected automatically on your behalf: If
202 you're on Windows, Net::SMTP will be selected, if you're not on
203 Windows, Net::SMTP will be selected unless Mail::Send is installed,
204 in which case Mail::Send is used.
206 At the moment, this must be one of either 'Net::SMTP', or
207 'Mail::Send'. Support for authenticated SMTP may soon be possibly
210 If you specify 'Mail::Send' as a transport, you can add an
211 additional argument in the form of an array reference which will be
212 passed to the constructor of the lower-level Mail::Mailer. This can
213 be used to great effect for all manner of fun and enjoyment. ;-)
215 This is not designed to be an extensible platform upon which to
216 build transport plugins. That functionality is planned for the
217 next-generation release of Test::Reporter, which will reside in the
218 CPAN::Testers namespace.
221 Optional. Gets or sets the value that will be appended to
222 X-Reported-Via, generally this is useful for distributions that use
223 Test::Reporter to report test results. This would be something like
227 These methods are used in situations where you test on a machine
228 that has port 25 blocked and there is no local MTA. You use write()
229 on the machine that you are testing from, transfer the written test
230 reports from the testing machine to the sending machine, and use
231 read() on the machine that you actually want to submit the reports
232 from. write() will write a file in an internal format that contains
233 'From', 'Subject', and the content of the report. The filename will
235 grade.distribution.archname.osvers.seconds_since_epoch.pid.rpt.
236 write() uses the value of dir() if it was specified, else the cwd.
238 On the machine you are testing from:
240 my $reporter = Test::Reporter->new
243 distribution => 'Test-Reporter-1.16',
246 On the machine you are submitting from:
249 $reporter = Test::Reporter->new()->read('pass.Test-Reporter-1.16.i686-linux.2.2.16.1046685296.14961.rpt')->send() || die $reporter->errstr(); # wrap in an opendir if you've a lot to submit
251 write() also accepts an optional filehandle argument:
253 my $fh; open $fh, '>-'; # create a STDOUT filehandle object
254 $reporter->write($fh); # prints the report to STDOUT
257 If you specify recipients to be cc'd while using send() (and you do not
258 have Mail::Send installed) be sure that you use the author's @cpan.org
259 address otherwise they may not be delivered, since the perl.org MX's are
260 unlikely to relay for anything other than perl.org and cpan.org.
263 Copyright (c) 2007 Adam J. Foxson. All rights reserved.
266 This program is free software; you may redistribute it and/or modify it
267 under the same terms as Perl itself.
276 This is optional. If it's installed Test::Reporter will try even
277 harder at guessing your mail domain.
280 This is optional. If it's installed Test::Reporter will dynamically
281 retrieve the mail exchangers for perl.org, instead of relying on the
282 MX's known at the time of this release.
285 This is optional. If it's installed Test::Reporter will use
286 Mail::Send instead of Net::SMTP.
289 Adam J. Foxson <afoxson@pobox.com> and Richard Soderberg
290 <rsod@cpan.org>, with much deserved credit to Kirrily "Skud" Robert
291 <skud@cpan.org>, and Kurt Starsinic <Kurt.Starsinic@isinet.com> for
292 predecessor versions (CPAN::Test::Reporter, and cpantest respectively).