/ 
CPAN-YACSmoke-0.02_06
/ CPAN::YACSmoke

NAME

CPAN::YACSmoke - Yet Another CPAN Smoke Tester

SYNOPSIS

perl -MCPAN::YACSmoke -e test

DESCRIPTION

This module uses the backend of CPANPLUS to run tests on modules recently uploaded to CPAN and post results to the CPAN Testers list.

It will create a database file in the .cpanplus directory, which it uses to track tested distributions. This information will be used to keep from posting multiple reports for the same module, and to keep from testing modules that use non-passing modules as prerequisites.

If it is given multiple versions of the same distribution to test, it will test the most recent version only. If that version fails, then it will test a previous version.

By default it uses CPANPLUS configuration settings.

OBJECT INTERFACE

new( [ %config ] )

The object interface is created normally through the test() or mark() functions of the procedural interface. However, it can be accessed with a set of configuration settings to extend the capabilities of the package.

Configuration settings are:

verbose
debug 
force 
cpantest
report_pass_only
prereqs
ignore_cpanplus_bugs
ignore_bad_prereqs
fail_max
exclude_dists
test_max

list_from          - List plugin required, default Recent

recent_list_age    - used with the Recent plugin 
recent_list_path   - used with the Recent plugin 
mailbox            - used with the Outlook plugin 
nntp_id            - used with the NNTP plugin 
webpath            - used with the WebList plugin 

audit_log          - log file to write progress to

config_file        - an INI file with the above settings

All settings can use defaults. With regards to the last setting, the INI file should contain one setting per line, except the values for the exclude_dists setting, which are laid out as:

[CONFIG]
exclude_dists=<<HERE
mod_perl
HERE

The above would then ignore any distribution that include the string 'mod_perl' in its name. This is useful for distributions which use external C libraries, which are not installed, or for which testing is problematic.

The setting 'test_max' is used to restrict the number of distributions tested in a single run. As some distributions can take some time to be tested, it may be more suitable to run in small batches at a time. The default setting is 100 distributions.

METHODS

homedir

Obtains the users home directory

basedir

Obtains the base directory for downloading and testing distributions.

PROCEDURAL INTERFACE

EXPORTS

The following routines are exported by default. They are intended to be called from the command-line, though they could be used from a script.

test( [ %config, ] [ $dist [, $dist .... ] ] )
perl -MCPAN::YACSmoke -e test

perl -MCPAN::YACSmoke -e test('R/RR/RRWO/Some-Dist-0.01.tar.gz')

Runs tests on CPAN distributions. Arguments should be paths of individual distributions in the author directories. If no arguments are given, it will download the RECENT file from CPAN and use that.

By default it uses CPANPLUS configuration settings. If CPANPLUS is set not to send test reports, then it will not send test reports.

For further use of configuration settings see the new() constructor.

mark( [ %config, ] $dist [, $grade ] ] )
perl -MCPAN::YACSmoke -e mark('Some-Dist-0.01')

perl -MCPAN::YACSmoke -e mark('Some-Dist-0.01', 'fail')

Retrieves the test result in the database, or changes the test result.

It can be useful to update the status of a distribution that once failed or was untestable but now works, so as to test modules which make use of it.

Grades can be one of (case insensitive):

pass
fail
unknown
na
ungraded
none

For further use of configuration settings see the new() constructor.

excluded( [ %config, ] [ $dist [, $dist ... ] ] )
perl -MCPAN::YACSmoke -e excluded('Some-Dist-0.01')

perl -MCPAN::YACSmoke -e excluded()

Given a list of distributions, indicates which ones would be excluded from testing, based on the exclude_dist list that is created.

For further use of configuration settings see the new() constructor.

PLUGINS

To know which distributions to test, the packages needs to access a list of distributions that have been recently uploaded to CPAN. There are currently four plugins which can enable this:

Recent

The Recent plugin downloads the RECENT file from CPAN, and returns the list of recently added modules, by diff-ing from the previously downloaded version.

Pass through configuration settings:

  %config = {
	  list_from => 'Recent',
 	  recent_list_age => '',
	  recent_list_path => '.'
  };

Outlook

The Outlook plugin uses a mailbox via the Outlook mail client to return the current list of distributions

Pass through configuration settings:

  %config = {
	  list_from => 'Outlook',
 	  mailbox => 'CPAN Testers'
  };

Note that the mailbox needs to be in a folder below 'Inbox'.

In order to use this plugin you will need to install the following modules:

Win32::OLE
Win32::OLE::Const

NNTPWeb

The NNTP plugin uses the webpages that are available at http://www.nntp.perl.org/group/perl.cpan.testers/ to return the current list of distributions

Pass through configuration settings:

  %config = {
	  list_from => 'NNTPWeb',
	  nntp_id => $nntp_id
  };

In order to use this plugin you will need to install the following modules:

WWW::Mechanize
Template::Extract

NNTP

The NNTP plugin access the USENET group directly to return the current list of distributions

Pass through configuration settings:

  %config = {
	  list_from => 'NNTP',
	  nntp_id => $nntp_id
  };

In order to use this plugin you will need to install the following modules:

Net::NNTP

WebList

The WebList plugin accesses a formatted webpage to return the current list of distributions. The current pages which provide this list in correct format are cycled through, unless a specific webpage is requested.

Currently used webpages:

http://cpan.uwinnipeg.ca/recent

Note that the following webpages do not provide a 'download' link, which can identify the exact distribution. Further checking may be added in the future.

http://search.cpan.org/recent
http://use.perl.org/modulelist/

Pass through configuration settings:

  %config = {
	  list_from => 'WebList',
 	  webpath => 'http://cpan.uwinnipeg.ca/recent'
  };

In order to use this plugin you will need to install the following modules:

WWW::Mechanize
Template::Extract

Writing A Plugin

For an example, see one of the above plugins.

The constructor, new(), is passed a hash of the configuration settings. The setting 'smoke' is an object reference to YACSmoke. Be sure to save the configuration settings your plugin requires in the constructor.

The single instance method used by YACSmoke is download_list(). This should return a simple list of the distributions available for testing. Note that if a parameter value of 1 is passed to download_list(), this indicates that a test run is in progress, otherwise only a query on the outstanding list is being made.

CAVEATS

This is a proto-type release. Use with caution and supervision.

The current version has a very primitive interface and limited functionality. Future versions may have a lot of options.

There is always a risk associated with automatically downloading and testing code from CPAN, which could turn out to be malicious or severely buggy. Do not run this on a critical machine.

This module uses the backend of CPANPLUS to do most of the work, so is subject to any bugs of CPANPLUS.

SUGGESTIONS AND BUG REPORTING

Please submit suggestions and report bugs to the CPAN Bug Tracker at http://rt.cpan.org.

SEE ALSO

The CPAN Testers Website at http://testers.cpan.org has information about the CPAN Testing Service.

For additional information, see the documentation for these modules:

CPANPLUS
Test::Reporter

AUTHORS

Robert Rothenberg <rrwo at cpan.org>

Barbie <barbie at cpan.org>, for Miss Barbell Productions, http://www.missbarbell.co.uk

Acknowledgements

Jos Boumans <kane at cpan.org> for writing CPANPLUS.

Suggestions and Bug Reporting

Please submit suggestions and report bugs to the CPAN Bug Tracker at http://rt.cpan.org.

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Robert Rothenberg. All Rights Reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.