Herein lies Test-Reporter-1.38.
[test-reporter.git] / README
blobdb5f7a070cfb2438cc99f6bf109f7edcf8b781d9
1 NAME
2     Test::Reporter - sends test results to cpan-testers@perl.org
4 SYNOPSIS
5       use Test::Reporter;
7       my $reporter = Test::Reporter->new();
9       $reporter->grade('pass');
10       $reporter->distribution('Mail-Freshmeat-1.20');
11       $reporter->send() || die $reporter->errstr();
13       # or
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();
23       # or
25       my $reporter = Test::Reporter->new(
26           grade => 'fail',
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',
31       );
32       $reporter->send() || die $reporter->errstr();
34 DESCRIPTION
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
52     visiting enjoyment:
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
79         the above 2 links.
81 METHODS
82     * address
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.
88     * comments
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'.
92     * debug
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.
98     * dir
99         Optional. Defaults to the current working directory. This method
100         specifies the directory that write() writes test report files to.
102     * distribution
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
105         here.
107     * edit_comments
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:
112         * suffix
113             Optional. Allows one to specify the suffix ("extension") of the
114             temp file used by edit_comments. Defaults to '.txt'.
116     * errstr
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.
122     * from
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
128         accomplish the same.
130     * grade
131         Gets or sets the success or failure of the distributions's 'make
132         test' result. This must be one of:
134           grade     meaning
135           -----     -------
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
141     * mail_send_args
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.
147     * message_id
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.
153     * mx
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.
163     * new
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.
168     * perl_version
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.
174     * report
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.
180     * send
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.
190     * subject
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.
195     * timeout
196         Optional. Gets or sets the timeout value for the submission of test
197         reports. Default is 120 seconds.
199     * transport
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
208         added as well.
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.
220     * via
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
224         "CPANPLUS 0.036".
226     * write and read
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
234         be represented as:
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
241           (
242             grade => 'pass',
243             distribution => 'Test-Reporter-1.16',
244           )->write();
246         On the machine you are submitting from:
248           my $reporter;
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
256 CAVEATS
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.
262 COPYRIGHT
263     Copyright (c) 2007 Adam J. Foxson. All rights reserved.
265 LICENSE
266     This program is free software; you may redistribute it and/or modify it
267     under the same terms as Perl itself.
269 SEE ALSO
270     * perl
271     * Config
272     * Net::SMTP
273     * File::Spec
274     * File::Temp
275     * Net::Domain
276         This is optional. If it's installed Test::Reporter will try even
277         harder at guessing your mail domain.
279     * Net::DNS
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.
284     * Mail::Send
285         This is optional. If it's installed Test::Reporter will use
286         Mail::Send instead of Net::SMTP.
288 AUTHOR
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).