Test::Reporter(3pm)

💖 Test::Reporter — the manual, but make it cute 💖

okay so bestie, you're reading the Test::Reporter(3pm) page — it's one of those User Contributed Perl Documentation situations, and honestly? it's giving "your fave sends test results to the CPAN Testers squad". sit down, grab a strawberry, and let's get into it 🍓✨

---

🌸 NAME 🌸

Test::Reporter — literally sends your test results to cpan-testers@perl.org. that's the whole job. she's a messenger. she's that girl. 💌

⭐ VERSION ⭐

version 1.62 — periodt.

🎀 SYNOPSIS 🎀

the vibe, in code:

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();

three whole ways to do the thing. pick your fighter 💅

🦋 DESCRIPTION 🦋

So. Test::Reporter reports the test results of any given distribution to the CPAN Testers project. She has wide support for various perl5's and platforms — she's flexible, she's well-traveled, she's booked and busy. ✨

Lowkey important lore: CPAN Testers no longer receives test reports by email, but the reports still resemble an email message. This module has numerous legacy "features" left over from the days of email transport. it's giving vintage, it's giving nostalgia, but we move. 🫶

📬 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 the necessary transport arguments. 👑

Advanced testers may wish to test on a machine different from the one used to send reports — main character energy, honestly. Consult the CPAN Testers Wiki <http://wiki.cpantesters.org/> for examples using other transport classes. iykyk.

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. rip to those, they served their time 💀

---

🌈 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. put whatever, bestie, no judgement 🌸
• 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 distribution'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 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. (a transport that does nothing. she's quiet. she's mysterious. she's literally not there.)

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'
);

Heads up: 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. it's coming. we're waiting. 💅

• transport_args — Optional. Gets or sets transport arguments that will be 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. (not me turning on debug and drowning in logs 😭)
• 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. the birth. the origin story. 🐣
• 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. no skipping steps bestie 🙈
• 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. do not skip this. do not be cute about it. 💅
• 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. (yes we're saying it twice. it's important. it's the rule. 🫶)
• 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. like, always. set it. don't let her guess. it never goes well 😭

---

👀 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. (the notifications? automatic. the satisfaction? unmatched. ✨)

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

---

and that's the whole page, bestie 💖 this was Test::Reporter(3pm) from the User Contributed Perl Documentation, page generated under perl v5.34.0 on 2022-06-28 — she's iconic, she's legacy, she's still sending reports. slay, stay hydrated, and always check your errstr() 🌈✨🎀