Test::Reporter(3) User Contributed Perl Documentation Test::Reporter(3)NAME
Test::Reporter - sends test results to cpan-testers@perl.org
VERSION
version 1.58
SYNOPSIS
use Test::Reporter;
my $reporter = Test::Reporter->new(
transport => 'File',
transport_args => [ dir => '/tmp' ],
);
$reporter->grade('pass');
$reporter->distribution('Mail-Freshmeat-1.20');
$reporter->send() || die $reporter->errstr();
# or
my $reporter = Test::Reporter->new(
transport => 'File',
transport_args => [ dir => '/tmp' ],
);
$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(
transport => 'File',
transport_args => [ dir => '/tmp' ],
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.
CPAN Testers no longer receives test reports by email, but reports
still resemble an email message. This module has numerous legacy
"features" left over from the days of email transport.
Transport mechanism
The choice of transport is set with the "transport" argument. CPAN
Testers should usually install Test::Reporter::Transport::Metabase and
use 'Metabase' as the "transport". See that module for necessary
transport arguments. Advanced testers may wish to test on a machine
different from the one used to send reports. Consult the CPAN Testers
Wiki <http://wiki.cpantesters.org/> for examples using other transport
classes.
The legacy email-based transports have been split out into a separate
Test::Reporter::Transport::Legacy distribution and methods solely
related to email have been deprecated.
ATTRIBUTES
Required attributes
· 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.
· from
Gets or sets the e-mail address of the individual submitting the
test report, i.e. "John Doe <jdoe@example.com>".
· 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
Transport attributes
· transport
Gets or sets the transport type. The transport type argument is
refers to a 'Test::Reporter::Transport' subclass. The default is
'Null', which uses the Test::Reporter::Transport::Null class and
does nothing when "send" is called.
You can add additional arguments after the transport selection.
These will be passed to the constructor of the lower-level
transport. See "transport_args".
$reporter->transport(
'File', dir => '/tmp'
);
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.
Optional attributes
· comments
Gets or sets the comments on the test report. This is most commonly
used for distributions that did not pass a 'make test'.
· debug
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
Defaults to the current working directory. This method specifies
the directory that write() writes test report files to.
· timeout
Gets or sets the timeout value for the submission of test reports.
Default is 120 seconds.
· via
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".
Deprecated attributes
CPAN Testers no longer uses email for submitting reports. These
attributes are deprecated.
· address
· mail_send_args
· mx
METHODS
· new
This constructor returns a Test::Reporter object.
· 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.
· 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.
· 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 via the defined
"transport" mechanism. You must check errstr() on a send() in
order to be guaranteed delivery.
· edit_comments
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.
· write and read
These methods are used in situations where you wish to save reports
locally rather than transmitting them to CPAN Testers immediately.
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
Deprecated methods
· message_id
CAVEATS
If you experience a long delay sending reports with Test::Reporter, you
may be experiencing a wait as Test::Reporter attempts to determine your
email address. Always use the "from" parameter to set your email
address explicitly.
SEE ALSO
For more about CPAN Testers:
· CPAN Testers reports <http://www.cpantesters.org/>
· CPAN Testers wiki <http://wiki.cpantesters.org/>
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests by email to
"bug-test-reporter at rt.cpan.org", or through the web interface at
http://rt.cpan.org/Public/Dist/Display.html?Name=Test-Reporter
<http://rt.cpan.org/Public/Dist/Display.html?Name=Test-Reporter>. You
will be automatically notified of any progress on the request by the
system.
Source Code
This is open source software. The code repository is available for
public review and contribution under the terms of the license.
http://github.com/dagolden/test-reporter
<http://github.com/dagolden/test-reporter>
git clone http://github.com/dagolden/test-reporter
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) 2011 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.
perl v5.14.2 2011-07-19 Test::Reporter(3)
