NAME
CPAN::Testers::Report - Creates CPAN Testers test-report objects
SYNOPSIS
use CPAN::Testers::Report;
use JSON::DWIW;
my $serialized_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();
# generate a JSON serialization of test-report object ("client side")
my $json_obj = JSON::DWIW->new({pretty => 1});
$serialized_report = $json_obj->to_json($test_report);
}
# transport magic pixie dust! ($serialized_report transmitted via HTTP)
{
# reconstitue the object ("server side")
my $json_obj = JSON::DWIW->new();
my $test_report = $json_obj->from_json($serialized_report);
bless $test_report, 'CPAN::Testers::Report';
# methods may now be called against the reconstituted object..
print $test_report->grade(), "\n";
}
DESCRIPTION
This module is a component of the next-generation implementation of the
CPAN Tester's stack. Once completed, 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 (but will be
soon); The API may change at any time without notice. This module is not
yet recommended for general use, but testing is highly encouraged.
SERIALIZATION
These objects are generated specifically with serialization in mind.
Below, please find a sample test report in JSON:
{ "_interpreter_vers_numeric":"5.8.8", "_grade":"PASS", "_from":"Adam J.
Foxson <afoxson@pobox.com>", "_config": { "gnulibc_version":"",
"uname":"uname", "longdblsize":"16", "nvtype":"double", "ccdlflags":" ",
"cppflags":"-no-cpp-precomp -g -pipe -fno-common -DPERL_DARWIN
-no-cpp-precomp -fno-strict-aliasing -Wdeclaration-after-statement
-I\/usr\/local\/include", "cc":"cc",
"archname":"darwin-thread-multi-2level", "config_args":"-ds -e
-Dprefix=\/usr -Dccflags=-g -pipe -Dldflags=-Dman3ext=3pm -Duseithreads
-Duseshrplib", "libc":"\/usr\/lib\/libc.dylib", "byteorder":"1234",
"osname":"darwin", "d_longdbl":"define", "libpth":"\/usr\/local\/lib
\/usr\/lib", "prototype":"define", "useperlio":"define", "so":"dylib",
"ccflags":"-arch i386 -arch ppc -g -pipe -fno-common -DPERL_DARWIN
-no-cpp-precomp -fno-strict-aliasing -Wdeclaration-after-statement
-I\/usr\/local\/include", "gccversion":"4.0.1 (Apple Inc. build 5465)",
"ldflags":"-arch i386 -arch ppc -L\/usr\/local\/lib", "useposix":"true",
"useshrplib":"true", "longsize":"4", "uselongdouble":null,
"alignbytes":"8", "d_longlong":"define", "use64bitall":"define",
"ccversion":"", "man3ext":"3pm", "doublesize":"8", "usemymalloc":"n",
"hint":"recommended", "use5005threads":null, "usemultiplicity":"define",
"perllibs":"-ldl -lm -lutil -lc", "dlext":"bundle", "ivsize":"4",
"usesocks":null, "lddlflags":"-arch i386 -arch ppc -bundle -undefined
dynamic_lookup -L\/usr\/local\/lib", "libperl":"libperl.dylib",
"osvers":"9.0", "cccdlflags":" ", "ptrsize":"4",
"uselargefiles":"define", "useithreads":"define", "longlongsize":"8",
"usethreads":"define", "d_sfio":null, "lseeksize":"8", "n":"",
"libs":"-ldbm -ldl -lm -lutil -lc", "dlsrc":"dl_dlopen.xs",
"use64bitint":"define", "d_dlsymun":null, "ld":"cc
-mmacosx-version-min=10.5", "gccosandvers":"", "d_sigaction":"define",
"ivtype":"long", "optimize":"-O3", "nvsize":"8", "intsize":"4",
"prefix":"\/" }, "_report_vers":1, "_need_prerequisites": {
"Test::More":"0.74" }, "_interpreter_vers_extra":null,
"_via":"CPAN::Testers::Report 0.03, cpantest",
"_make_test_output":"PERL_DL_NONLAZY=1 \/usr\/bin\/perl
\"-MExtUtils::Command::MM\" \"-e\" \"test_harness(0, 'blib\/lib',
'blib\/arch')\" t\/*.t\nt\/0-signature........skipped\n all skipped: Set
the environment variable TEST_SIGNATURE to enable this
test.\nt\/1-report...........ok \nt\/98-pod.............skipped\n all
skipped: Skipping author tests\nt\/99-pod_coverage....skipped\n all
skipped: Skipping author tests\nAll tests successful, 3 tests
skipped.\nFiles=4, Tests=113, 0 wallclock secs ( 0.38 cusr + 0.02 csys =
0.40 CPU)\n", "__errstr":null, "_dist":"Test-Reporter-1.34",
"_dist_name":"Test-Reporter", "_environment_variables": {
"HOME":"\/Users\/afoxson",
"PERL5LIB":"\/sw\/lib\/perl5:\/sw\/lib\/perl5\/darwin" },
"_interpreter_version_extra":"", "_interpreter_vers_float":"5.008008",
"_interpreter":"perl", "_have_prerequisites": { "Test::More":"0.47" },
"_perl_special_variables": { "$GID":"500 500", "$^X":"\/usr\/bin\/perl",
"$EGID":"500 500", "$UID\/$EUID":"500 \/ 500" }, "_dist_vers":"1.34",
"_rfc2822_date":"Sun, 13 Jan 2008 03:03:03 -0500",
"_perl_toolchain_modules": { "Module::Signature":"0.55", "YAML":"0.66",
"File::Spec":"3.25", "ExtUtils::Install":"1.44",
"ExtUtils::Command":"1.13", "Module::Build":"0.2808",
"ExtUtils::CBuilder":"0.21", "ExtUtils::Manifest":"1.51",
"Test::Harness":"3.05", "ExtUtils::MakeMaker":"6.42",
"ExtUtils::ParseXS":"2.18", "version":"0.74", "YAML::Syck":"1.00",
"Test::More":"0.74", "CPAN":"1.9205", "Cwd":"3.25" },
"_comments":"...This is a computer-generated test report..." }
METHODS
* comments
User-specified comments to include with the test report.
* 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 instead be specified. This
represents the distribution's name only. For example
'Test-Reporter'.
* dist_vers
Automatically calculated but can instead be specified. This
represents the distribution's version only. For example '1.34'.
* environment_variables
Store environment variable name and value pairs inside the object:
$test_report->environment_variables({HOME => '/home/foo', PATH =>
'/bin'});
Get the environment variable names:
$test_report->environment_variables(); # ('HOME', 'PATH')
Get the value for a particular environment variable:
$test_report->environment_variables('HOME'); # '/home/foo'
* 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.
* have_prerequisites
Store prerequisite module and version pairs that the user had,
inside the object:
$test_report->have_prerequisites({DBI => '1.23', CGI => '1.04'});
Get the prerequisite modules that the user had:
$test_report->have_prerequisites(); # ('DBI', 'CGI')
Get the version of a particular prerequisite module that user had:
$test_report->have_prerequisites('DBI'); # '1.23'
* interpreter
At the moment always returns 'perl' but can instead be specified.
* interpreter_vers_numeric
Automatically calculated but can instead be specified. This
represents the interpreter's version. For example in the format of
'5.8.8'.
* interpreter_vers_float
Automatically calculated but can instead be specified. This
represents the interpreter's version. For example in the format of
'5.008008'.
* interpreter_vers_extra
Automatically calculated but can instead be specified. This usually
represents the interpreter's patch/patchlevel, if available. For
example 'patchlevel 12345'.
* make_test_output
Output of "make test".
* need_prerequisites
Store prerequisite module and version pairs that the user needed,
inside the object:
$test_report->need_prerequisites({DBI => '1.23', CGI => '1.04'});
Get the prerequisite modules that the user needed:
$test_report->need_prerequisites(); # ('DBI', 'CGI')
Get the version of a particular prerequisite module that user
needed:
$test_report->need_prerequisites('DBI'); # '1.23'
* new
Constructor. Accepts no arguments at this time. If this method
returns undef, it failed.
* perl_special_variables
Store perl special variable name and value pairs inside the object:
$test_report->perl_special_variables({'$^X' => '/usr/bin/perl'});
Get the perl special variable names:
$test_report->perl_special_variables(); # ('$^X')
Get the value for a particular perl special variable:
$test_report->perl_special_variables('$^X'); # '/usr/bin/perl'
* perl_toolchain_modules
Store perl toolchain module and version pairs inside the object:
$test_report->perl_toolchain_modules({CPAN => '1.9205'});
Get the perl toolchain modules:
$test_report->perl_toolchain_modules(); # ('CPAN')
Get the version of a particular perl toolchain module:
$test_report->perl_toolchain_modules('CPAN'); # '1.9205'
* report_vers
Revision of the internal test report object format. This will be
incremented any time the format changes.
* rfc2822_date
Automatically calculated but can instead be specified. 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. This 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 instead be
specified. This represents the automation wrapping
CPAN::Testers::Report. This is usually something like
CPAN::Reporter, CPAN::YACSmoke. This is metadata.
COPYRIGHT
Copyright (C) 2007, 2008 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 <afoxson@pobox.com>
With many thanks to:
* Barbie <barbie@missbarbell.co.uk>
* David Golden <dagolden@cpan.org>
* Kirrily "Skud" Robert <skud@cpan.org>
* Richard Soderberg <rsod@cpan.org>
* Kurt Starsinic <Kurt.Starsinic@isinet.com>