NAME

CPAN::Testers::Report - Creates CPAN Testers test-report objects

SYNOPSIS

  use CPAN::Testers::Report;

  my $test_report = CPAN::Testers::Report->new() || die CPAN::Testers::Report->errstr();
  $test_report->comments('...This is a computer-generated test report...');
  $test_report->dist('Test-Reporter-1.34') || die $test_report->errstr();
  $test_report->from('Adam J. Foxson <afoxson@pobox.com>') || die $test_report->errstr();
  $test_report->grade('pass') || die $test_report->errstr();

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. An object of this type will encapsulate all data and information about a single, specific test report. This object 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.

SERIALIZATION

These objects are generated specifically with serialization in mind.

Below, please find a sample test report in YAML:

 --- !!perl/hash:CPAN::Testers::Report
 __errstr: ~
 _comments: |
  Dear Adam J. Foxson,


  This is a computer-generated report for CPAN-Testers-Report-0.03
  on perl-5.8.8, created automatically by CPAN-Reporter-0.99_15 and sent 
  to the CPAN Testers mailing list.


  If you have received this email directly, it is because the person testing 
  your distribution chose to send a copy to your CPAN email address; there 
  may be a delay before the official report is received and processed 
  by CPAN Testers.


  Thank you for uploading your work to CPAN.  Congratulations!
  All tests were successful.


  <snip!>
 _config:
  alignbytes: 8
  archname: darwin-2level
  byteorder: 1234
  cc: /usr/bin/gcc-4.0
  cccdlflags: ' '
  ccdlflags: ' '
  ccflags: -I/opt/local/include -fno-common -DPERL_DARWIN -no-cpp-precomp -fno-strict-aliasing -pipe -Wdeclaration-after-statement -I/opt/local/include
  ccversion: ''
  config_args: -des -Dprefix=/opt/local -Dccflags=-I'/opt/local/include' -Dldflags=-L/opt/local/lib -Dvendorprefix=/opt/local -Dcc=/usr/bin/gcc-4.0
  cppflags: -no-cpp-precomp -I/opt/local/include -fno-common -DPERL_DARWIN -no-cpp-precomp -fno-strict-aliasing -pipe -Wdeclaration-after-statement -I/opt/local/include
  d_dlsymun: ~
  d_longdbl: define
  d_longlong: define
  d_sfio: ~
  d_sigaction: define
  dlext: bundle
  dlsrc: dl_dlopen.xs
  doublesize: 8
  gccosandvers: ''
  gccversion: '4.0.1 (Apple Computer, Inc. build 5367)'
  gnulibc_version: ''
  hint: recommended
  intsize: 4
  ivsize: 4
  ivtype: long
  ld: env MACOSX_DEPLOYMENT_TARGET=10.3 cc
  lddlflags: -L/opt/local/lib -bundle -undefined dynamic_lookup
  ldflags: -L/opt/local/lib
  libc: /usr/lib/libc.dylib
  libperl: libperl.a
  libpth: /opt/local/lib /usr/lib
  libs: -ldbm -ldl -lm -lc
  longdblsize: 16
  longlongsize: 8
  longsize: 4
  lseeksize: 8
  nvsize: 8
  nvtype: double
  optimize: -O3
  osname: darwin
  osvers: 8.10.1
  perllibs: -ldl -lm -lc
  prefix: /opt/local
  prototype: define
  ptrsize: 4
  so: dylib
  uname: uname
  use5005threads: ~
  use64bitall: ~
  use64bitint: ~
  useithreads: ~
  uselargefiles: define
  uselongdouble: ~
  usemultiplicity: ~
  usemymalloc: n
  useperlio: define
  useposix: true
  useshrplib: false
  usesocks: ~
  usethreads: ~
  vendorprefix: /opt/local
 _dist: CPAN-Testers-Report-0.03
 _dist_name: CPAN-Testers-Report
 _dist_vers: 0.03
 _from: 'Adam J. Foxson <afoxson@pobox.com>'
 _grade: PASS
 _interpreter: perl
 _interpreter_vers_extra: ~
 _interpreter_vers_float: 5.008008
 _interpreter_vers_numeric: 5.8.8
 _interpreter_version_extra: ''
 _report_vers: 1
 _rfc2822_date: 'Wed, 3 Oct 2007 23:30:13 -0400'
 _via: 'CPAN::Testers::Report 0.03, CPAN::Reporter 0.99_15'

METHODS

comments
User-specified comments to include with the test report. This is oftentimes the output of a failed 'make test'. Optional.
config
Without an argument returns a list of all of the major configuration items (osname, osvers, archname, byteorder, cc, libs, et al...) If given an argument will return the value associated with one of those configuration items
dist
Full distribution name and version of which this test report is about. For example 'Test-Reporter-1.34'. Mandatory. If this method 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 overridden. This represents the distribution's name only. For example 'Test-Reporter'.
dist_vers
Automatically calculated but can be overridden. This represents the distribution's version only. For example '1.34'.
errstr
Returns the error message from the last error that occurred.
from
Name and e-mail address of the tester. For example 'Adam J. Foxson <afoxson@pobox.com>'. Mandatory, and must be RFC 2822 compliant. Name may be omitted. 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 was specified was not RFC 2822 compliant). This is metadata.
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' but can be overridden.
interpreter_vers_numeric
Automatically calculated but can be overridden. This represents the interpreter's version. For example in the format of '5.8.8'.
interpreter_vers_float
Automatically calculated but can be overridden. This represents the interpreter's version. For example in the format of '5.008008'.
interpreter_vers_extra
Automatically calculated but can be overridden. This usually represents the interpreter's patch/patchlevel, if available. For example 'patchlevel 12345'.
new
Constructor. Accepts no arguments at this time. If this method returns undef, it failed.
report_vers
Revision of the internal test report object format.
rfc2822_date
Automatically calculated but can be overridden. This is the RFC2822-compliant datetime. This is metadata.
validate
Accepts no arguments. Returns true if the object represents a valid test report. Returns false and sets errstr() if the object does not represent a valid test report. The ensures that that distribution specified is parseable into its name/version constituents, that the grade is one of 'pass', 'fail', 'na', or 'unknown', and that from is present and RFC 2822 compliant
via
Automatically calculated (based on the caller) but can be overridden. This represents the automation wrapping CPAN::Testers::Report. This is usually something like CPAN::Reporter, CPAN::YACSmoke. This is metadata.

TODO

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''?

COPYRIGHT

LICENSE

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

AUTHOR

Adam J. Foxson <afoxson@pobox.com>

With many thanks to:

Richard Soderberg <rsod@cpan.org>
Kirrily ``Skud'' Robert <skud@cpan.org>
Kurt Starsinic <Kurt.Starsinic@isinet.com>
Barbie <barbie@missbarbell.co.uk>
David Golden <dagolden@cpan.org>

CPAN::Testers::Report - Creates CPAN Testers test-report objects