File: README

package info (click to toggle)
libtest-reporter-perl 1.27-3
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k
  • size: 140 kB
  • ctags: 107
  • sloc: perl: 1,295; makefile: 50
file content (214 lines) | stat: -rw-r--r-- 8,887 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
NAME
    Test::Reporter - sends test results to cpan-testers@perl.org

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('afoxson@cpan.org') || 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 testing service. See http://testers.cpan.org/ for details.

    Test::Reporter has wide support for various perl5's and platforms.

METHODS
    * new
        This constructor returns a Test::Reporter object. It will optionally
        accept named parameters for: mx, address, grade, distribution, from,
        comments, via, timeout, debug and dir.

    * 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.

    * 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'.

    * 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.

    * 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.

    * 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   distribution did not include tests

    * 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.

    * send
        Sends the test report to cpan-testers@perl.org and cc's the e-mail
        to the specified recipients, if any. If you do specify recipients to
        be cc'd and you do not have Mail::Send installed be sure that you
        use the author's @cpan.org address otherwise they will not be
        delivered. You must check errstr() on a send() in order to be
        guaranteed delivery. Technically, this 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.

    * timeout
        Optional. Gets or sets the timeout value for the submission of test
        reports. Default is 120 seconds.

    * 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".

    * 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.

    * 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.

    * 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.

    * mail_send_args
        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 the
        Mail::Mailer manpage and the Mail::Send manpage for details.

    * dir
        Optional. Defaults to the current working directory. This method
        specifies the directory that write() writes test report files to.

    * 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:

          my $reporter;
          $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

CAVEATS
    If you specify recipients to be cc'd while using send() (and you do not
    have Mail::Send installed) be sure that you use the author's @cpan.org
    address otherwise they may not be delivered, since the perl.org MX's are
    unlikely to relay for anything other than perl.org and cpan.org.

BUGS
    If you happen to find one please email me at afoxson@pobox.com, and/or
    report it to the below URL. Thank you.

      http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Reporter

COPYRIGHT
    Copyright (c) 2003 Adam J. Foxson. All rights reserved.

LICENSE
    This program is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    * the perl manpage
    * the Config manpage
    * the Net::SMTP manpage
    * the File::Spec manpage
    * the File::Temp manpage
    * the Net::Domain manpage
        This is optional. If it's installed Test::Reporter will try even
        harder at guessing your mail domain.

    * the Net::DNS manpage
        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.

    * the Mail::Send manpage
        This is optional. If it's installed Test::Reporter will use
        Mail::Send instead of Net::SMTP.

AUTHOR
    Adam J. Foxson <afoxson@pobox.com>, with much deserved credit to Kirrily
    "Skud" Robert <skud@cpan.org>, and Kurt Starsinic
    <Kurt.Starsinic@isinet.com> for predecessor versions
    (CPAN::Test::Reporter, and cpantest respectively).