view release on metacpan or  search on metacpan

lib/CPAN/Reporter/Smoker/Safer.pm  view on Meta::CPAN

This can be used to run partial smoke testing on a box that normally wouldn't be desired for full smoke testing
(i.e. isn't a dedicated/isolated environment).
Another potential use is to vet everything before upgrading.

=head1 GETTING STARTED

See the CPAN Testers Quick Start guide L<http://wiki.cpantesters.org/wiki/QuickStart>.  Once L<CPAN::Reporter> is installed and configured, you should be all set.

There are also some very good hints and notes in the L<CPAN::Reporter::Smoker> documentation.

=head2 WARNING -- smoke testing is risky

While in theory this is much safer than full CPAN smoke testing, ALL of the same risks (see L<CPAN::Reporter::Smoker>) still apply:

Smoke testing will download and run programs that other people have uploaded to
CPAN.  These programs could do *anything* to your system, including deleting
everything on it.  Do not run CPAN::Reporter::Smoker unless you are prepared to
take these risks.  


=head1 USAGE

=head2 start()

This is an overload of L<CPAN::Reporter::Smoker>::start, and supports the same arguments, with the exception of C<list> which is set internally.  In addition, supports the following argument:

=head3 safer

Hashref with the following possible keys:

=over 2

=item mask

Scalar; Defaults to C<'/./'>; Value is passed to C<CPAN::Shell::expand()> for filtering the module list (applies to I<module> names, not distro names).

=item filter

Code ref; Defaults to L<"__filter">. First argument is the CPAN::Reporter::Smoker::Safer class/object; Second argument is a L<CPAN::Distribution> object.  Return value should be C<1> (true) to accept, and C<0> (false) to reject the distribution.

	filter => sub {
	  my ($safer, $dist) = @_;
	  ...
          return 1; 
	},

=item min_reports

Defaults to 0 (since this involves extra http fetches). This is used by the default filter -- distros are 'trusted' if they have at least this many CPAN testers reports already.

=item min_days_old

Defaults to 14. This is used by the default filter -- distros are 'trusted' if they were uploaded to CPAN at least this many days ago.

=item exclusions

Defaults to C<[ qr#/perl-5\.#, qr#/mod_perl-\d# ]>.  This is used by the default filter to exclude
any distro whose name (e.g. A/AU/AUTHOR/Foo-Bar-1.23.tar.gz) matches one of these regexes.

Note that the F<disabled.yml> functionality might be more suitable.  See L<CPAN::Reporter::Smoker>, L<CPAN>, and L<CPAN::Distroprefs> for more details.

=item preview

Default false.  If true, instead of invoking C<CPAN::Reporter::Smoker::start()> will just return the args (as hashref) that would have been passsed to C<start()>.  This is usefull for debugging/testing without kicking off the actual smoke tester.

=item exclude_tested

Default true. This is used by the default filter -- if true, distros are skipped if they were previously tested.  L<CPAN::Reporter::Smoker> does this anyways, so doing up front is more efficient. (Use in test suite is the only reason this is provided...

=back

=head1 INTERNAL METHODS

=head2 __filter

Used as the default L<"filter"> code ref.

=over 2

=item *

Excludes any distro who's name (e.g. A/AU/AUTHOR/Foo-Bar-1.23.tar.gz) matches a list of L<"exclusions">.

=item *

If L<"exclude_tested"> is true, excludes any distro that was already tested, as determined by L<CPAN::Reporter::History>. 

=item *

Exclude any distro that was uploaded to CPAN less than L<"min_days_old"> days ago.

=item *

Exclude any distro that has less than L<"min_reports"> CPAN Testers reports.

=back


=head2 __installed_dists

Returns an array ref of dist names (e.g. 'ANDK/CPAN-1.9301.tar.gz' ).

	CPAN::Reporter::Smoker::Safer->__installed_dists( $mask, $filter );

C<mask> is optional, and is same value as L<"mask">. C<filter> is optional, and is same value as L<"filter">.


=head1 AUTHOR

David Westbrook (CPAN: davidrw), C<< <dwestbrook at gmail.com> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-cpan-reporter-smoker-safer at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CPAN-Reporter-Smoker-Safer>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.