NAME CPAN::Testers::Report - Creates CPAN Testers test-report objects SYNOPSIS use CPAN::Testers::Report; use Config; my $test_report = CPAN::Testers::Report->new(); $test_report->comments('Rejoice!'); $test_report->config(Config::myconfig()) || die $test_report->error(); $test_report->dist('Test-Reporter-1.34') || die $test_report->error(); $test_report->from('Adam J. Foxson ') || die $test_report->error(); $test_report->grade('pass') || die $test_report->error(); DESCRIPTION Welcome to CPAN::Testers::Report. This is the first distribution in the CPAN::Testers namespace. This module is designed to be part of the next-generation implementation of the CPAN Tester's stack. When complete, this distribution and its constituents will obsolete Test::Reporter. This module provides an abstraction for test reports. Objects will encapsulate all data and information about a single, specific test report. These objects can then be submitted to a user's transport of choice for delivery. This is a developer's release. The interface is not stable; The API may change at any time without notice. This module is not yet recommended for general use. METHODS * archname Automatically calculated but can be overriden. This is a short name to characterize the current architecture. * comments User-specified comments to include with the test report. This is oftentimes the output of a failed 'make test'. Optional. * config This method should be the recipient of Config::myconfig(). Mandatory. If this method returns undef, it failed. * dist Full distribution name and version of which this test report is about. For example 'Test-Reporter-1.34'. Mandatory. If this methods returns undef, it failed. Attempts to call this method with anything resembling a distribution of perl itself will not be honored (use perlbug). * dist_name Automatically calculated but can be overriden. This represents the distribution's name only. For example 'Test-Reporter'. * dist_vers Automatically calculated but can be overriden. This represents the distribution's version only. For example '1.34'. * error Returns an error message when an error has occurred. * from Name and e-mail address of the tester. For example 'Adam J. Foxson '. Optional, but if specified it must be RFC 2822 compliant. If you ever need to parse this out to separate the name from the e-mail address, visit Email::Address. If this method returns undef, it failed (i.e., what you specified was not RFC 2822 compliant). * grade Grade for the result of 'make test'. Must be pass, fail, na, or unknown. 'Pass' indicates that all tests passed. 'Fail' indicates one or more tests failed. 'Na' indicates that the distribution will not work on this platform. 'Unknown' indicates that the distribution did not include tests. Mandatory. If this method returns undef, it failed. * interpreter At the moment always returns 'perl'. * interpreter_vers_numeric Automatically calculated but can be overriden. This represents the interpreter's version. For example in the format of '5.8.8'. * interpreter_vers_float Automatically calculated but can be overriden. This represents the interpreter's version. For example in the format of '5.008008'. * interpreter_vers_extra Automatically calculated but can be overriden. This usually represents the interpreter's patch/patchlevel, if available. For example 'patchlevel 12345'. * new Constructor. Accepts no arguments at this time. * osname Automatically calculated but can be overriden. This is the operating system name. * osvers Automatically calculated but can be overriden. This is the operating system version. * report_vers Revision of the internal test report object format. * rfc2822_date Automatically calculated but can be overriden. This is the RFC2822-compliant datetime. * via Automatically calculated (based on the caller) but can be overriden. This represents the automation wrapping CPAN::Testers::Report. This is usually something like CPAN::Reporter, CPAN::YACSmoke. TODO Please excuse me for a few moments while I think aloud publically. :-) * Add tests for error conditions At a minimum: * dist() * from() * grade() * config() * Add a validate() method to ensure overall consistency? This is not intended to indicate suitablity for any particular transport. This is more about verifying that the object contains the minimum necessary data and in a correct form to even be considered a valid test report. A transport could call this as a sanity check before attempting delivery. * a distribution that is parseable into its name and version components * a config that is parseable into its archname, osvers, and perl version components * a from, if specified, must be RFC 2822 compliant * a grade that is one of 'pass', 'fail', 'na', or 'unknown' * Decide what to do about "interpreter" The idea behind this is that CPAN modules might theoretically be able to be run under interpreters other than perl itself. Therefore, it might be a potentially valueable endeavor to test this. For example, in the past, ponie would have been an example of where this might have occurred. Nowadays, would pugs perhaps be a current example? The question is whether or not we want to actually accomodate for this possibility. Or to restate, do we want to have support for testing CPAN distributions with interpreters that are "perl-like"? * Shall the metadata be handled specially (from/date/via) ? These are all three bits of data that are arguably part of a test-report, but a test-report can be fully 100% valid in all of their absence. As such, I'm wondering if we want to handle these differently/specially. Food for thought! * RFC 2822 compliance regex shouldn't be assembled on a per object basis This is inefficient and needs to be addressed. * Hmm. What to do about the subject... Doesn't really belong in this module (because the concept of 'Subject' is specfic only to a particular class of transport), but we don't want each e-mail based transport reimplementing this functionality or duplicating code. And, we need the flexibility to change it in the future without major disruption. So then, what we might want to do is create a new distribution that provides methods to do both parsing and generating of subjects, once passed a previously generated subject or CPAN::Testers::Report object. * Hmm. What to do about the "stringified formatted report"... Almost 3am! Time for bed... More to come tomorrow... COPYRIGHT Copyright (c) 2007 Adam J. Foxson and the CPAN Testers. 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 * perl * CPAN::Testers AUTHOR Adam J. Foxson With many thanks to: * Richard Soderberg * Kirrily "Skud" Robert * Kurt Starsinic * Barbie * David Golden