NAME

CPAN::YACSmoke - Yet Another CPAN Smoke Tester

SYNOPSIS

perl -MCPAN::YACSmoke -e test

REQUIREMENTS

This package requires the following modules (most of which are not included with Perl):

      CPANPLUS
      Config::IniFiles
      File::HomeDir
      File::Spec
      IO::File
      LWP::Simple
      Module::Pluggable
      Regexp::Assemble
      SDBM_File
      Sort::Versions
      Test::Reporter
      URI

These dependencies (such as CPANPLUS and Test::Reporter) may require additional modules.

Installation

Installation can be done using the traditional Makefile.PL or the newer Build.PL methods.

Using Makefile.PL:

      perl Makefile.PL
      make
      make test
      make install

(On Windows platforms you should use nmake instead.)

Using Build.PL (if you have Module::Build installed):

      perl Build.PL
      perl Build
      perl Build test
      perl Build install

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, although these can be overridden by a configuration file.

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

perl -MCPAN::YACSmoke -e test

          perl -MCPAN::YACSmoke
            -e test('authors/id/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.

mark

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.

excluded

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.

REVISION HISTORY

The following changes have been made since the previous publicly available version:

0.03 Tue Mar 1 2005

• minor fixes/tweaks

0.02_08 (Not publicly released.)

• fixed bug with install_prerequisites callback
• cleaned up Build.PL
• additional updates/corrects to POD
• patches from Barbie
• audit_log is in the base directory if no path is given
• uncompleted tests are marked 'aborted'
• additional logging
• minor tweaks to code
• added Barbie to author in Build.PL abstract

0.02_06 Sat Feb 12 2005

• removed all plugins except default Recent
• distros are tested in sorted order (as they were in 0.02)
• aborts if prereq on excluded list
• minor tweaks

0.02_05 Fri Feb 11 2005

• minor changes to POD
• appends comments to test reports if CPANPLUS v0.052 installed
• ignore_cpanplus_bugs when CPANPLUS version >= 0.052
• 'aborted' grade can be set with mark function

0.02_04 Tue Feb 8 2005

• smarter handling of aborted installations (they are marked as 'aborted')
• minor tweaks to plugins
• added report_pass_only option
• corrected typo when no new distros are to be tested
  • uses Sort::Versions to sort version numbers
• added option to ignore bad prereqs rather than abort install
• uninstallable prereqs abort install by default
• install aborted if prereqs have grade of 'na' or 'ungraded'
• default config file assumed for basedir
• fixed tests
• minor tweaks in Build.PL
• added Barbie as author in POD

0.02_03 Wed Feb 2 2005

• If a report grade couldn't be determined, then the DB was recording this as 'unknown'. However, seeing as this a valid report grade, this has been changed to 'ungraded'.
• Fixed bugs in send reporting - if a module had been tested and the DB had 'ungraded', a subsequent pass/fail/na/unknown wasn't being recorded. Should be able to override grades for ungraded/unknown/none. Should be able to override a fail grade with a pass.
• Fixed bugs in audit & plugin reporting.
• Settings passed to CPANPLUS::Configure now handled correctly.
• Reduced object overhead by not using mark() in test(), but accessing the tied DB directly.
• created private methods _track and _debug to better handle messages to STDOUT and audit file.
• Added new plugin, SmokeDB, to access the contents of the current local cpansmoke DB.
• Added standard regex for supported archive extensions.
• Added support for an audit callback handler.

0.02_02 Mon Jan 31 2005

• Move NNTP.pm to NNTPWeb.pm and created a NNTP.pm plugin that uses Net::NNTP.
• added excluded() function to list the distributions that would be excluded from testing.
• added a parameter to download_list(). If set to 1 it implies a test run is in progress.
• added more audit trail printing.
• fixed a few bugs in previous development version.
• added a cpansmoke.pl script.

0.02_01 Fri Jan 25 2005

• added POD and more tests.
• added plugin capability to be more flexible about where to get the recent distribution lists.
• added more configuration support including an audit_log and config_file settings.
• set $ENV{'AUTOMATED_TESTING'} = 1, which if adopted by others will hopefully enable CPAN authors to detect if their distribution is being tested by a machine or a human.

See the Changes file for a complete revision history.

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.

And yes, it's sorely in need of documentation.

AUTHORS

Robert Rothenberg <rrwo at cpan.org>

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

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.