Sponsoring The Perl Toolchain Summit 2025: Help make this important event another success Learn more

 / 
POE-Component-SmokeBox-0.58
River stage one • 3 direct dependents • 6 total dependents
/ POE::Component::SmokeBox

NAME

POE::Component::SmokeBox - POE enabled CPAN smoke testing with added value.

VERSION

version 0.58

SYNOPSIS


            

              
              
# A simple smoker that takes modules to smoke from @ARGV
use strict;
use warnings;
use POE;
use POE::Component::SmokeBox;
use POE::Component::SmokeBox::Smoker;
use POE::Component::SmokeBox::Job;
use Getopt::Long;
$|=1;
my $perl;
GetOptions( 'perl=s' => \$perl, );
die "No 'perl' specified\n" unless $perl;
die "No modules specified to smoke\n" unless scalar @ARGV;
my $smokebox = POE::Component::SmokeBox->spawn();
POE::Session->create(
      package_states => [
         'main' => [ qw(_start _stop _results) ],
      ],
      heap => { perl => $perl, pending => [ @ARGV ] },
);
$poe_kernel->run();
exit 0;
sub _start {
  my ($kernel,$heap) = @_[KERNEL,HEAP];
  my $smoker = POE::Component::SmokeBox::Smoker->new( perl => $perl, );
  $smokebox->add_smoker( $smoker );
  $smokebox->submit( event => '_results',
 job => POE::Component::SmokeBox::Job->new( command => 'smoke', module => $_ ) )
                        for @{ $heap->{pending} };
  undef;
}
sub _stop {
  $smokebox->shutdown();
  undef;
}
sub _results {
  my $results = $_[ARG0];
  print $_, "\n" for map { @{ $_->{log} } } $results->{result}->results();
  undef;
}

DESCRIPTION

POE::Component::SmokeBox is a flexible CPAN Smoke testing framework which provides an extensible method for testing CPAN distributions against various different smoker backends.

A smoker backend is defined using a POE::Component::SmokeBox::Smoker object and is basically the path to a perl executable that is configured for CPAN Testing and its associated environment settings.

The perl executable must be configured appropriately to support CPAN testing with any of the currently supported backends, CPANPLUS::YACSmoke, CPAN::YACSmoke or CPAN::Reporter. Additional backends may be supported by inheriting and extending the backend base class POE::Component::SmokeBox::Backend::Base.

By default, the component will test submitted jobs against each configured smoker in turn. Setting multiplicity to true will enable each job to be run against configured smokers in parallel.

CONSTRUCTOR

spawn

Creates a new session and returns an object. Takes a number of parameters:


            

              
              
'alias', set an alias that you can use to address the component later;
'options', a hashref of POE session options;
'multiplicity', set to a true value to enable multiplicity, default is false;
'smokers', an arrayref of POE::Component::SmokeBox::Smoker objects;
'delay', the time in seconds to wait between job runs, default is 0;

METHODS

session_id

Returns the POE::Session ID of the smokebox component.

multiplicity

Returns true or false depending on whether multiplicity is enabled or not.

NOTE: If you enable multiplicity, you cannot use "delay" as an argument to SmokeBox::Job->new!

queues

Returns a list of POE::Component::SmokeBox::JobQueue objects that are currently active in the smokebox.

add_smoker

Takes one mandatory argument, a POE::Component::SmokeBox::Smoker object to add to the smokebox.

del_smoker

Takes one mandatory argument, a POE::Component::SmokeBox::Smoker object to remove from the smokebox.

delay

Sets the delay in seconds between job runs. Useful to "throttle" your smoker :) If called with no arguments, returns the current delay. This option will work even if multiplicity is enabled.

submit

Submits a job to the smokebox. Takes a number of parameters.


            

              
              
'event', the event name where results should be sent, mandatory;
'job', a POE::Component::SmokeBox::Job object to submit, mandatory;
'session', optionally specify a different session to send the result event to;
shutdown

Terminates the smokebox component.

INPUT EVENTS

add_smoker

Takes one mandatory argument, a POE::Component::SmokeBox::Smoker object to add to the smokebox.

del_smoker

Takes one mandatory argument, a POE::Component::SmokeBox::Smoker object to remove from the smokebox.

submit

Submits a job to the smokebox. Takes a number of parameters.


            

              
              
'event', the event name where results should be sent, mandatory;
'job', a POE::Component::SmokeBox::Job object to submit, mandatory;
'session', optionally specify a different session to send the result event to;
shutdown

Terminates the smokebox component.

OUTPUT EVENTS

An event will be sent on process completion with a hashref as ARG0:


            

              
              
'job', the POE::Component::SmokeBox::Job object of the job;
'result', a POE::Component::SmokeBox::Result object containing the results;
'submitted', the epoch time in seconds when the job was submitted;
'event', the event that will be sent with the results;
'session', the session ID the above event will be sent to;

The results will be same as returned by POE::Component::SmokeBox::Backend. They may be obtained by querying the POE::Component::SmokeBox::Result object:


            

              
              
$_[ARG0]->{result}->results() # produces a list

Each result is a hashref:


            

              
              
'log', an arrayref of STDOUT and STDERR produced by the job;
'PID', the process ID of the POE::Wheel::Run;
'status', the $? of the process;
'start_time', the time in epoch seconds when the job started running;
'end_time', the time in epoch seconds when the job finished;
'idle_kill', only present if the job was killed because of excessive idle;
'excess_kill', only present if the job was killed due to excessive runtime;
'term_kill', only present if the job was killed due to a poco shutdown event;
'cb_kill', only present if the job was killed due to the callback returning false;

SEE ALSO

POE::Component::SmokeBox::Smoker

POE::Component::SmokeBox::Job

POE::Component::SmokeBox::JobQueue

POE::Component::SmokeBox::Backend

POE::Component::SmokeBox::Result

AUTHOR

Chris Williams <chris@bingosnet.co.uk>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Chris Williams.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.