NAME
Test::Reporter - sends test results to cpan-testers@perl.org
VERSION
version 1.57
SYNOPSIS
use Test::Reporter;
my $reporter = Test::Reporter->new();
$reporter->grade('pass');
$reporter->distribution('Mail-Freshmeat-1.20');
$reporter->send() || die $reporter->errstr();
# or
my $reporter = Test::Reporter->new();
$reporter->grade('fail');
$reporter->distribution('Mail-Freshmeat-1.20');
$reporter->comments('output of a failed make test goes here...');
$reporter->edit_comments(); # if you want to edit comments in an editor
$reporter->send() || die $reporter->errstr();
# or
my $reporter = Test::Reporter->new(
grade => 'fail',
distribution => 'Mail-Freshmeat-1.20',
from => 'whoever@wherever.net (Whoever Wherever)',
comments => 'output of a failed make test goes here...',
via => 'CPANPLUS X.Y.Z',
);
$reporter->send() || die $reporter->errstr();
DESCRIPTION
Test::Reporter reports the test results of any given distribution to the
CPAN Testers project. Test::Reporter has wide support for various
perl5's and platforms.
METHODS
* address
Optional. Gets or sets the e-mail address that the reports will be
sent to. By default, this is set to cpan-testers@perl.org. You
shouldn't need this unless the CPAN Tester's change the e-mail
address to send report's to.
* comments
Optional. Gets or sets the comments on the test report. This is most
commonly used for distributions that did not pass a 'make test'.
* debug
Optional. Gets or sets the value that will turn debugging on or off.
Debug messages are sent to STDERR. 1 for on, 0 for off. Debugging
generates very verbose output and is useful mainly for finding bugs
in Test::Reporter itself.
* dir
Optional. Defaults to the current working directory. This method
specifies the directory that write() writes test report files to.
* distribution
Gets or sets the name of the distribution you're working on, for
example Foo-Bar-0.01. There are no restrictions on what can be put
here.
* edit_comments
Optional. Allows one to interactively edit the comments within a
text editor. comments() doesn't have to be first specified, but it
will work properly if it was. Accepts an optional hash of arguments:
* suffix
Optional. Allows one to specify the suffix ("extension") of the
temp file used by edit_comments. Defaults to '.txt'.
* errstr
Returns an error message describing why something failed. You must
check errstr() on a send() in order to be guaranteed delivery. This
is optional if you don't intend to use Test::Reporter to send
reports via e-mail, see 'send' below for more information.
* from
Optional. Gets or sets the e-mail address of the individual
submitting the test report, i.e. "afoxson@pobox.com (Adam Foxson)".
This is mostly of use to testers running under Windows, since
Test::Reporter will usually figure this out automatically.
Alternatively, you can use the MAILADDRESS environmental variable to
accomplish the same.
* grade
Gets or sets the success or failure of the distributions's 'make
test' result. This must be one of:
grade meaning
----- -------
pass all tests passed
fail one or more tests failed
na distribution will not work on this platform
unknown tests did not exist or could not be run
* mail_send_args -- DEPRECATED
Kept for backwards compatibility. Use "transport_args" instead.
Optional. If you have MailTools installed and you want to have it
behave in a non-default manner, parameters that you give this method
will be passed directly to the constructor of Mail::Mailer. See
Mail::Mailer and Mail::Send for details.
* message_id
Returns an automatically generated Message ID. This Message ID will
later be included as an outgoing mail header in the test report
e-mail. This was included to conform to local mail policies at
perl.org. This method courtesy of Email::MessageID.
* mx
Optional. Gets or sets the mail exchangers that will be used to send
the test reports. If you override the default values make sure you
pass in a reference to an array. By default, this contains the MX's
known at the time of release for perl.org. If you do not have
Mail::Send installed (thus using the Net::SMTP interface) and do
have Net::DNS installed it will dynamically retrieve the latest
MX's. You really shouldn't need to use this unless the hardcoded
MX's have become wrong and you don't have Net::DNS installed.
* new
This constructor returns a Test::Reporter object. It will optionally
accept named parameters for: mx, address, grade, distribution, from,
comments, via, timeout, debug, dir, perl_version, transport and
transport_args.
* perl_version
Returns a hashref containing _archname, _osvers, and _myconfig based
upon the perl that you are using. Alternatively, you may supply a
different perl (path to the binary) as an argument, in which case
the supplied perl will be used as the basis of the above data.
* report
Returns the actual content of a report, i.e. "This distribution has
been tested as part of the cpan-testers...". 'comments' must first
be specified before calling this method, if you have comments to
make and expect them to be included in the report.
* send
Sends the test report to cpan-testers@perl.org. You must check
errstr() on a send() in order to be guaranteed delivery.
Technically, send() is optional, as you may use Test::Reporter to
only obtain the 'subject' and 'report' without sending an e-mail at
all, although that would be unusual.
* subject
Returns the subject line of a report, i.e. "PASS Mail-Freshmeat-1.20
Darwin 6.0". 'grade' and 'distribution' must first be specified
before calling this method.
* timeout
Optional. Gets or sets the timeout value for the submission of test
reports. Default is 120 seconds.
* transport
Optional. Gets or sets the transport type. The transport type
argument is refers to a 'Test::Reporter::Transport' subclass. The
default is 'Net::SMTP', which uses the
[Test::Reporter::Transport::Net::SMTP] class.
You can add additional arguments after the transport selection.
These will be passed to the constructor of the lower-level
transport. This can be used to great effect for all manner of fun
and enjoyment. ;-) See "transport_args".
If Net::SMTP::TLS is used, 'Username' and 'Password' key-value
transport arguments must be provided.
$reporter->transport(
'Net::SMTP::TLS', Username => 'jdoe', Password => '123'
);
If the 'HTTP' transport is used, two additional arguments are
required: a URL to a Test::Reporter::HTTPGateway compatible server
and an (optional) API key.
$reporter->transport(
'HTTP', 'http://example.com/reporter-gateway/', '123456'
);
This is not designed to be an extensible platform upon which to
build transport plugins. That functionality is planned for the
next-generation release of Test::Reporter, which will reside in the
CPAN::Testers namespace.
* transport_args
Optional. Gets or sets transport arguments that will used in the
constructor for the selected transport, as appropriate.
* via
Optional. Gets or sets the value that will be appended to
X-Reported-Via, generally this is useful for distributions that use
Test::Reporter to report test results. This would be something like
"CPANPLUS 0.036".
* write and read
These methods are used in situations where you test on a machine
that has port 25 blocked and there is no local MTA. You use write()
on the machine that you are testing from, transfer the written test
reports from the testing machine to the sending machine, and use
read() on the machine that you actually want to submit the reports
from. write() will write a file in an internal format that contains
'From', 'Subject', and the content of the report. The filename will
be represented as:
grade.distribution.archname.osvers.seconds_since_epoch.pid.rpt.
write() uses the value of dir() if it was specified, else the cwd.
On the machine you are testing from:
my $reporter = Test::Reporter->new
(
grade => 'pass',
distribution => 'Test-Reporter-1.16',
)->write();
On the machine you are submitting from:
# wrap in an opendir if you've a lot to submit
my $reporter;
$reporter = Test::Reporter->new()->read(
'pass.Test-Reporter-1.16.i686-linux.2.2.16.1046685296.14961.rpt'
)->send() || die $reporter->errstr();
write() also accepts an optional filehandle argument:
my $fh; open $fh, '>-'; # create a STDOUT filehandle object
$reporter->write($fh); # prints the report to STDOUT
CAVEATS
If you experience a long delay sending mail with Test::Reporter, you may
be experiencing a wait as Test::Reporter attempts to determine your
email domain. Setting the MAILDOMAIN environment variable will avoid
this delay.
SEE ALSO
For more about CPAN Testers:
* <http://www.cpantesters.org/>
CPAN Testers reports
* <http://wiki.cpantesters.org/>
CPAN Testers wiki
Test::Reporter itself--as a project--also has several links for your
visiting enjoyment:
* <http://code.google.com/p/test-reporter/>
Test::Reporter's master project page
* <http://groups.google.com/group/test-reporter>
Discussion group for Test::Reporter
* <http://code.google.com/p/test-reporter/w/list>
The Wiki for Test::Reporter
* <http://github.org/dagolden/test-reporter>
Test::Reporter's public git source code repository.
* <http://search.cpan.org/dist/Test-Reporter/>
Test::Reporter on CPAN
* <http://code.google.com/p/test-reporter/issues/list>
UNFORTUNATELY, WE ARE UNABLE TO ACCEPT TICKETS FILED WITH RT.
Please file all bug reports and enhancement requests at our Google
Code issue tracker. Thank you for your support and understanding.
* <http://backpan.cpan.org/authors/id/F/FO/FOX/>
* <http://backpan.cpan.org/authors/id/A/AF/AFOXSON/>
If you happen to--for some strange reason--be looking for primordial
versions of Test::Reporter, you can almost certainly find them at
the above 2 links.
Related Perl modules:
* perl
* Config
* Net::SMTP
* Net::SMTP::TLS
* File::Spec
* File::Temp
* Net::Domain
This is optional. If it's installed Test::Reporter will try even
harder at guessing your mail domain.
* Net::DNS
This is optional. If it's installed Test::Reporter will dynamically
retrieve the mail exchangers for perl.org, instead of relying on the
MX's known at the time of this release.
* Test::Reporter::HTTPGateway
This is optional. It provides a web API for the 'HTTP' transport
method.
AUTHORS
Adam J. Foxson <afoxson@pobox.com>
David Golden <dagolden@cpan.org>
Kirrily "Skud" Robert <skud@cpan.org>
Ricardo Signes <rjbs@cpan.org>
Richard Soderberg <rsod@cpan.org>
Kurt Starsinic <Kurt.Starsinic@isinet.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Authors and Contributors.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.