The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Reporter-1.57
River stage two • 19 direct dependents • 35 total dependents
4 ++
/ Test::Reporter

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:

Test::Reporter itself--as a project--also has several links for your visiting enjoyment:

Related Perl modules:

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.