README
1NAME
2 CPAN::YACSmoke - Yet Another CPAN Smoke Tester
3
4SYNOPSIS
5 perl -MCPAN::YACSmoke -e test
6
7REQUIREMENTS
8 This package requires the following modules (most of which are not
9 included with Perl):
10
11 CPANPLUS
12 Config::IniFiles
13 File::HomeDir
14 File::Spec
15 IO::File
16 LWP::Simple
17 Module::Pluggable
18 Regexp::Assemble
19 SDBM_File
20 Sort::Versions
21 Test::Reporter
22 URI
23
24 These dependencies (such as CPANPLUS and Test::Reporter) may require
25 additional modules.
26
27Installation
28 Installation can be done using the traditional Makefile.PL or the
29 newer Build.PL methods.
30
31 Using Makefile.PL:
32
33 perl Makefile.PL
34 make
35 make test
36 make install
37
38 (On Windows platforms you should use nmake instead.)
39
40 Using Build.PL (if you have Module::Build installed):
41
42 perl Build.PL
43 perl Build
44 perl Build test
45 perl Build install
46
47DESCRIPTION
48 This module uses the backend of CPANPLUS to run tests on modules
49 recently uploaded to CPAN and post results to the CPAN Testers list.
50
51 It will create a database file in the .cpanplus directory which it uses
52 to track tested distributions. This information will be used to keep
53 from posting multiple reports for the same module, and to keep from
54 testing modules that use non-passing modules as prerequisites.
55
56 If it is given multiple versions of the same distribution to test, it
57 will test the most recent version only. If that version fails, then it
58 will test a previous version.
59
60 By default it uses CPANPLUS configuration settings, although these
61 can be overridden by a configuration file.
62
63 EXPORTS
64 The following routines are exported by default. They are intended to be
65 called from the command-line, though they could be used from a script.
66
67 test
68 perl -MCPAN::YACSmoke -e test
69
70 perl -MCPAN::YACSmoke
71 -e test('authors/id/R/RR/RRWO/Some-Dist-0.01.tar.gz')
72
73 Runs tests on CPAN distributions. Arguments should be paths of
74 individual distributions in the author directories. If no arguments
75 are given, it will download the RECENT file from CPAN and use that.
76
77 By default it uses CPANPLUS configuration settings. If CPANPLUS is
78 set not to send test reports, then it will not send test reports.
79
80 mark
81 perl -MCPAN::YACSmoke -e mark('Some-Dist-0.01')
82
83 perl -MCPAN::YACSmoke -e mark('Some-Dist-0.01', 'fail')
84
85 Retrieves the test result in the database, or changes the test
86 result.
87
88 It can be useful to update the status of a distribution that once
89 failed or was untestable but now works, so as to test modules which
90 make use of it.
91
92 excluded
93 perl -MCPAN::YACSmoke -e excluded('Some-Dist-0.01')
94
95 perl -MCPAN::YACSmoke -e excluded()
96
97 Given a list of distributions, indicates which ones would be excluded
98 from testing, based on the exclude_dist list that is created.
99
100REVISION HISTORY
101 The following changes have been made since the previous publicly
102 available version:
103
104 0.03 Tue Mar 1 2005
105 - minor fixes/tweaks
106
107 0.02_08 (Not publicly released.)
108 - fixed bug with install_prerequisites callback
109 - cleaned up Build.PL
110 - additional updates/corrects to POD
111 - patches from Barbie
112 - audit_log is in the base directory if no path is given
113 - uncompleted tests are marked 'aborted'
114 - additional logging
115 - minor tweaks to code
116 - added Barbie to author in Build.PL abstract
117
118 0.02_06 Sat Feb 12 2005
119 - removed all plugins except default Recent
120 - distros are tested in sorted order (as they were in 0.02)
121 - aborts if prereq on excluded list
122 - minor tweaks
123
124 0.02_05 Fri Feb 11 2005
125 - minor changes to POD
126 - appends comments to test reports if CPANPLUS v0.052 installed
127 - ignore_cpanplus_bugs when CPANPLUS version >= 0.052
128 - 'aborted' grade can be set with mark function
129
130 0.02_04 Tue Feb 8 2005
131 - smarter handling of aborted installations (they are marked as
132 'aborted')
133 - minor tweaks to plugins
134 - added report_pass_only option
135 - corrected typo when no new distros are to be tested
136 * uses Sort::Versions to sort version numbers
137 - added option to ignore bad prereqs rather than abort install
138 - uninstallable prereqs abort install by default
139 - install aborted if prereqs have grade of 'na' or 'ungraded'
140 - default config file assumed for basedir
141 - fixed tests
142 - minor tweaks in Build.PL
143 - added Barbie as author in POD
144
145 0.02_03 Wed Feb 2 2005
146 - If a report grade couldn't be determined, then the DB was
147 recording this as 'unknown'. However, seeing as this a valid
148 report grade, this has been changed to 'ungraded'.
149 - Fixed bugs in send reporting - if a module had been tested and
150 the DB had 'ungraded', a subsequent pass/fail/na/unknown wasn't
151 being recorded. Should be able to override grades for
152 ungraded/unknown/none. Should be able to override a fail grade
153 with a pass.
154 - Fixed bugs in audit & plugin reporting.
155 - Settings passed to CPANPLUS::Configure now handled correctly.
156 - Reduced object overhead by not using mark() in test(), but
157 accessing the tied DB directly.
158 - created private methods _track and _debug to better handle
159 messages to STDOUT and audit file.
160 - Added new plugin, SmokeDB, to access the contents of the current
161 local cpansmoke DB.
162 - Added standard regex for supported archive extensions.
163 - Added support for an audit callback handler.
164
165 0.02_02 Mon Jan 31 2005
166 - Move NNTP.pm to NNTPWeb.pm and created a NNTP.pm plugin that
167 uses Net::NNTP.
168 - added excluded() function to list the distributions that would
169 be excluded from testing.
170 - added a parameter to download_list(). If set to 1 it implies a
171 test run is in progress.
172 - added more audit trail printing.
173 - fixed a few bugs in previous development version.
174 - added a cpansmoke.pl script.
175
176 0.02_01 Fri Jan 25 2005
177 - added POD and more tests.
178 - added plugin capability to be more flexible about where to
179 get the recent distribution lists.
180 - added more configuration support including an audit_log and
181 config_file settings.
182 - set $ENV{'AUTOMATED_TESTING'} = 1, which if adopted by others
183 will hopefully enable CPAN authors to detect if their
184 distribution is being tested by a machine or a human.
185
186 See the Changes file for a complete revision history.
187
188CAVEATS
189 This is a proto-type release. Use with caution and supervision.
190
191 The current version has a very primitive interface and limited
192 functionality. Future versions may have a lot of options.
193
194 There is always a risk associated with automatically downloading and
195 testing code from CPAN, which could turn out to be malicious or severely
196 buggy. Do not run this on a critical machine.
197
198 This module uses the backend of CPANPLUS to do most of the work, so is
199 subject to any bugs of CPANPLUS.
200
201 And yes, it's sorely in need of documentation.
202
203AUTHORS
204 Robert Rothenberg <rrwo at cpan.org>
205
206 Barbie <barbie at cpan.org>, for Miss Barbell Productions,
207 <http://www.missbarbell.co.uk>
208
209COPYRIGHT AND LICENSE
210 Copyright (C) 2005 by Robert Rothenberg. All Rights Reserved.
211
212 This library is free software; you can redistribute it and/or modify it
213 under the same terms as Perl itself, either Perl version 5.8.3 or, at
214 your option, any later version of Perl 5 you may have available.
215