Codebase list libtest-reporter-perl / debian/latest
debian/latest

Tree @debian/latest (Download .tar.gz)

NAME
    Test::Reporter - sends test results to cpan-testers@perl.org

VERSION
    version 1.62

SYNOPSIS
      use Test::Reporter;

      my $reporter = Test::Reporter->new(
          transport => 'File',
          transport_args => [ '/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 => [ '/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 => [ '/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', '/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. Make
        sure you protect it from the shell in case there are spaces in the
        path:

          $reporter->perl_version(qq{"$^X"});

    *   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 through the issue tracker at
    <https://github.com/cpan-testers/Test-Reporter/issues>. You will be
    notified automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/cpan-testers/Test-Reporter>

      git clone https://github.com/cpan-testers/Test-Reporter.git

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>

CONTRIBUTORS
    *   Andreas Koenig <andk@cpan.org>

    *   Ed J <mohawk2@users.noreply.github.com>

    *   Tatsuhiko Miyagawa <miyagawa@bulknews.net>

    *   Vincent Pit <perl@profvince.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2015 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.