README

   1 NAME
   2     Test::Reporter - sends test results to cpan-testers@perl.org
   3
   4 SYNOPSIS
   5       use Test::Reporter;
   6
   7       my $reporter = Test::Reporter->new();
   8
   9       $reporter->grade('pass');
  10       $reporter->distribution('Mail-Freshmeat-1.20');
  11       $reporter->send() || die $reporter->errstr();
  12
  13       # or
  14
  15       my $reporter = Test::Reporter->new();
  16
  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();
  22
  23       # or
  24
  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();
  33
  34 DESCRIPTION
  35     Test::Reporter reports the test results of any given distribution to the
  36     CPAN testing service. Test::Reporter has wide support for various
  37     perl5's and platforms. For further information visit the below links:
  38
  39     * <http://cpantesters.perl.org/>
  40         CPAN Testers reports (new site)
  41
  42     * <http://testers.cpan.org/>
  43         CPAN Testers reports (old site)
  44
  45     * <http://cpantest.grango.org/>
  46         The new CPAN Testers Wiki (thanks Barbie!)
  47
  48     Test::Reporter itself--as a project--also has several links for your
  49     visiting enjoyment:
  50
  51     * <http://code.google.com/p/test-reporter/>
  52         Test::Reporter's master project page
  53
  54     * <http://groups.google.com/group/test-reporter>
  55         Discussion group for Test::Reporter
  56
  57     * <http://code.google.com/p/test-reporter/w/list>
  58         The Wiki for Test::Reporter
  59
  60     * <http://repo.or.cz/w/test-reporter.git>
  61         Test::Reporter's public git source code repository.
  62
  63     * <http://search.cpan.org/dist/Test-Reporter/>
  64         Test::Reporter on CPAN
  65
  66     * <http://code.google.com/p/test-reporter/issues/list>
  67         UNFORTUNATELY, WE ARE UNABLE TO ACCEPT TICKETS FILED WITH RT.
  68
  69         Please file all bug reports and enhancement requests at our Google
  70         Code issue tracker. Thank you for your support and understanding.
  71
  72     * <http://backpan.cpan.org/authors/id/F/FO/FOX/>
  73     * <http://backpan.cpan.org/authors/id/A/AF/AFOXSON/>
  74         If you happen to--for some strange reason--be looking for primordial
  75         versions of Test::Reporter, you can almost certainly find them at
  76         the above 2 links.
  77
  78 METHODS
  79     * address
  80         Optional. Gets or sets the e-mail address that the reports will be
  81         sent to. By default, this is set to cpan-testers@perl.org. You
  82         shouldn't need this unless the CPAN Tester's change the e-mail
  83         address to send report's to.
  84
  85     * comments
  86         Optional. Gets or sets the comments on the test report. This is most
  87         commonly used for distributions that did not pass a 'make test'.
  88
  89     * debug
  90         Optional. Gets or sets the value that will turn debugging on or off.
  91         Debug messages are sent to STDERR. 1 for on, 0 for off. Debugging
  92         generates very verbose output and is useful mainly for finding bugs
  93         in Test::Reporter itself.
  94
  95     * dir
  96         Optional. Defaults to the current working directory. This method
  97         specifies the directory that write() writes test report files to.
  98
  99     * distribution
 100         Gets or sets the name of the distribution you're working on, for
 101         example Foo-Bar-0.01. There are no restrictions on what can be put
 102         here.
 103
 104     * edit_comments
 105         Optional. Allows one to interactively edit the comments within a
 106         text editor. comments() doesn't have to be first specified, but it
 107         will work properly if it was. Accepts an optional hash of arguments:
 108
 109         * suffix
 110             Optional. Allows one to specify the suffix ("extension") of the
 111             temp file used by edit_comments. Defaults to '.txt'.
 112
 113     * errstr
 114         Returns an error message describing why something failed. You must
 115         check errstr() on a send() in order to be guaranteed delivery. This
 116         is optional if you don't intend to use Test::Reporter to send
 117         reports via e-mail, see 'send' below for more information.
 118
 119     * from
 120         Optional. Gets or sets the e-mail address of the individual
 121         submitting the test report, i.e. "afoxson@pobox.com (Adam Foxson)".
 122         This is mostly of use to testers running under Windows, since
 123         Test::Reporter will usually figure this out automatically.
 124         Alternatively, you can use the MAILADDRESS environmental variable to
 125         accomplish the same.
 126
 127     * grade
 128         Gets or sets the success or failure of the distributions's 'make
 129         test' result. This must be one of:
 130
 131           grade     meaning
 132           -----     -------
 133           pass      all tests passed
 134           fail      one or more tests failed
 135           na        distribution will not work on this platform
 136           unknown   distribution did not include tests
 137
 138     * mail_send_args
 139         Optional. If you have MailTools installed and you want to have it
 140         behave in a non-default manner, parameters that you give this method
 141         will be passed directly to the constructor of Mail::Mailer. See
 142         Mail::Mailer and Mail::Send for details.
 143
 144     * message_id
 145         Returns an automatically generated Message ID. This Message ID will
 146         later be included as an outgoing mail header in the test report
 147         e-mail. This was included to conform to local mail policies at
 148         perl.org. This method courtesy of Email::MessageID.
 149
 150     * mx
 151         Optional. Gets or sets the mail exchangers that will be used to send
 152         the test reports. If you override the default values make sure you
 153         pass in a reference to an array. By default, this contains the MX's
 154         known at the time of release for perl.org. If you do not have
 155         Mail::Send installed (thus using the Net::SMTP interface) and do
 156         have Net::DNS installed it will dynamically retrieve the latest
 157         MX's. You really shouldn't need to use this unless the hardcoded
 158         MX's have become wrong and you don't have Net::DNS installed.
 159
 160     * new
 161         This constructor returns a Test::Reporter object. It will optionally
 162         accept named parameters for: mx, address, grade, distribution, from,
 163         comments, via, timeout, debug and dir.
 164
 165     * perl_version
 166         Returns a hashref containing _archname, _osvers, and _myconfig based
 167         upon the perl that you are using. Alternatively, you may supply a
 168         different perl (path to the binary) as an argument, in which case
 169         the supplied perl will be used as the basis of the above data.
 170
 171     * report
 172         Returns the actual content of a report, i.e. "This distribution has
 173         been tested as part of the cpan-testers...". 'comments' must first
 174         be specified before calling this method, if you have comments to
 175         make and expect them to be included in the report.
 176
 177     * send
 178         Sends the test report to cpan-testers@perl.org and cc's the e-mail
 179         to the specified recipients, if any. If you do specify recipients to
 180         be cc'd and you do not have Mail::Send installed be sure that you
 181         use the author's @cpan.org address otherwise they will not be
 182         delivered. You must check errstr() on a send() in order to be
 183         guaranteed delivery. Technically, this is optional, as you may use
 184         Test::Reporter to only obtain the 'subject' and 'report' without
 185         sending an e-mail at all, although that would be unusual.
 186
 187     * subject
 188         Returns the subject line of a report, i.e. "PASS Mail-Freshmeat-1.20
 189         Darwin 6.0". 'grade' and 'distribution' must first be specified
 190         before calling this method.
 191
 192     * timeout
 193         Optional. Gets or sets the timeout value for the submission of test
 194         reports. Default is 120 seconds.
 195
 196     * via
 197         Optional. Gets or sets the value that will be appended to
 198         X-Reported-Via, generally this is useful for distributions that use
 199         Test::Reporter to report test results. This would be something like
 200         "CPANPLUS 0.036".
 201
 202     * write and read
 203         These methods are used in situations where you test on a machine
 204         that has port 25 blocked and there is no local MTA. You use write()
 205         on the machine that you are testing from, transfer the written test
 206         reports from the testing machine to the sending machine, and use
 207         read() on the machine that you actually want to submit the reports
 208         from. write() will write a file in an internal format that contains
 209         'From', 'Subject', and the content of the report. The filename will
 210         be represented as:
 211         grade.distribution.archname.osvers.seconds_since_epoch.pid.rpt.
 212         write() uses the value of dir() if it was specified, else the cwd.
 213
 214         On the machine you are testing from:
 215
 216           my $reporter = Test::Reporter->new
 217           (
 218             grade => 'pass',
 219             distribution => 'Test-Reporter-1.16',
 220           )->write();
 221
 222         On the machine you are submitting from:
 223
 224           my $reporter;
 225           $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
 226
 227         write() also accepts an optional filehandle argument:
 228
 229           my $fh; open $fh, '>-';  # create a STDOUT filehandle object
 230           $reporter->write($fh);   # prints the report to STDOUT
 231
 232 CAVEATS
 233     If you specify recipients to be cc'd while using send() (and you do not
 234     have Mail::Send installed) be sure that you use the author's @cpan.org
 235     address otherwise they may not be delivered, since the perl.org MX's are
 236     unlikely to relay for anything other than perl.org and cpan.org.
 237
 238 COPYRIGHT
 239     Copyright (c) 2007 Adam J. Foxson. All rights reserved.
 240
 241 LICENSE
 242     This program is free software; you may redistribute it and/or modify it
 243     under the same terms as Perl itself.
 244
 245 SEE ALSO
 246     * perl
 247     * Config
 248     * Net::SMTP
 249     * File::Spec
 250     * File::Temp
 251     * Net::Domain
 252         This is optional. If it's installed Test::Reporter will try even
 253         harder at guessing your mail domain.
 254
 255     * Net::DNS
 256         This is optional. If it's installed Test::Reporter will dynamically
 257         retrieve the mail exchangers for perl.org, instead of relying on the
 258         MX's known at the time of this release.
 259
 260     * Mail::Send
 261         This is optional. If it's installed Test::Reporter will use
 262         Mail::Send instead of Net::SMTP.
 263
 264 AUTHOR
 265     Adam J. Foxson <afoxson@pobox.com> and Richard Soderberg
 266     <rsod@cpan.org>, with much deserved credit to Kirrily "Skud" Robert
 267     <skud@cpan.org>, and Kurt Starsinic <Kurt.Starsinic@isinet.com> for
 268     predecessor versions (CPAN::Test::Reporter, and cpantest respectively).
 269