Robert Rothenberg > CPAN-YACSmoke-0.03_07 > CPAN::YACSmoke

Download:
CPAN-YACSmoke-0.03_07.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  9
Open  8
Stalled  2
View/Report Bugs
Module Version: 0.03_07   Source  

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.

CPANPLUS configuration settings (inherited from CPANPLUS unless otherwise noted) are:

  verbose
  debug 
  force 
  cpantest
  report_pass_only
  prereqs
  prefer_bin
  prefer_makefile    - enabled by default
  makeflags
  makemakerflags
  md5
  signature
  extractdir
  fetchdir

CPAN::YACSmoke configuration settings are:

  ignore_cpanplus_bugs
  ignore_bad_prereqs
  fail_max
  exclude_dists
  test_max
  allow_retries
  suppress_extracted
  flush_flag         - used by purge()

  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 plugins 
  webpath            - used with the WebList plugin 

  audit_log          - log file to write progress to

  config_file        - an INI file with the above settings
  database_file      - the local cpansmoke database

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.

The setting 'allow_retries' defaults to include grades of UNGRADED, IGNORED and ABORTED. If you wish to change this, for example to only allow grades of UNGRADED to be retried, you can specify as:

  [CONFIG]
  allow_retries=ungraded

Often module authors prefer to see the details of failed tests. You can make this the default setting using:

  [CONFIG]
  makeflags=TEST_VERBOSE=1

Note that sending verbose failure reports for packages with thousands of tests will be quite large (!), and may be blocked by mail and news servers.

See Config::IniFiles for more information on the INI file format.

METHODS

homedir

Obtains the users home directory

basedir

Obtains the base directory for downloading and testing distributions.

builddir

Obtains the build directory for unpacking 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):

  aborted  = tests aborted (uninstallable prereqs or other failure in test)
  pass     = passed tests
  fail     = failed tests
  unknown  = no tests available
  na       = not applicable to platform or installed libraries
  ungraded = no grade (test possibly aborted by user)
  none     = undefines a grade
  ignored  = package was ignored (a newer version was tested)

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.

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

  perl -MCPAN::YACSmoke -e purge('Some-Dist-0.01')

Purges the entries from the local cpansmoke database. The criteria for purging is that a distribution must have a more recent version, which has previously been marked as a PASS. However, if one or more distributions are passed as a parameter list, those specific distributions will be purged.

If the flush_flag is set, via the config hash, to a true value, the directory path created for each older copy of a distribution is deleted.

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

flush( [ %config, ] [ 'all' | 'old' ] )
  perl -MCPAN::YACSmoke -e flush()
  
  perl -MCPAN::YACSmoke -e flush('all')

  perl -MCPAN::YACSmoke -e flush('old')

Removes unrequired build directories from the designated CPANPLUS build directory. Note that this deletes directories regardless of whether the associated distribution was tested.

Default flush is 'all'. The 'old' option will only delete the older distributions, of multiple instances of a distribution.

Note that this cannot be done reliably using last access or modify time, as the intention is for this distribution to be used on any OS that CPANPLUS is installed on. In this case not all OSs support the full range of return values from the stat function.

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 => '.'
  };

SmokeDB

The SmokeDB plugin uses the contents of the locally stored cpansmoke database. This can then be used to retest distributions that haven't been fully tested previously.

There are no pass through configuration settings.

PlainTextList

The PlainTextList plugin allows for a locally created plain text file, listing all the distributions to be tested in a single run. Note that the excluded list and text_max settings will still apply.

Pass through configuration settings:

  %config = {
          list_from => 'PlainTextList',
          data => $my_data_file,
  };

Writing A Plugin

For an example, see one of the above plugins, or one of the known plugin packages available on CPAN (see list below).

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.

Known Plugin Packages on CPAN

CPAN::YACSmoke::Plugin::NNTP

Uses the NNTP feed direct via 'nntp.perl.org' of 'perl.cpan.testers'.

CPAN::YACSmoke::Plugin::NNTPWeb

Uses the web interface to the newsgroup 'perl.cpan.testers'.

CPAN::YACSmoke::Plugin::Outlook

Uses a list of emails held in an Outlook mail folder

CPAN::YACSmoke::Plugin::Phlanax100

Uses the distributions within the Phlanax 100 list

CPAN::YACSmoke::Plugin::WebList

Uses a web page containing the list of recently uploaded distributions to CPAN. Uses KobeSearch by default, but another similar page can be requested.

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.

There is a SourceForge project site for CPAN::YACSmoke at http://sourceforge.net/projects/yacsmoke.

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.

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.

syntax highlighting: