Test::AutoBuild::StageUser Contributed Perl DocumentaTest::AutoBuild::Stage(3)NAMETest::AutoBuild::Stage - The base class for an AutoBuild stage
SYNOPSIS
use Test::AutoBuild::Stage
my $stage = Test::AutoBuild::Stage->new(name => $token,
label => $string,
[critical => $boolean,]
[enabled => $boolean]);
# Execute the stage
$stage->run($runtime);
if ($stage->aborted()) { # Very badly wrong
die $stage->log();
} elsif ($stage->failed()) { # Expected failure
if ($stage->is_critical()) { # Non-recoverable
.. do failure case ...
} else {
.. do recovery case ...
}
} elsif ($stage->success() || # Everything's ok
$stage->skipped()) {
.. do normal case ...
}
DESCRIPTION
This module is an abstract base class for all AutoBuild stages. If
defines a handful of common methods and the abstract method "process"
to be implemented by sub-classes to provide whatever custom processing
is required.
STATUS
The status of a stage starts off as 'pending', and when the "run"
method is invoked, the status will changed to one of the following:
success
If the stage completed its processing without encountering any
problems. Stages will automatically have their status set to this
value if their "process" method completes without the "fail" method
having been called.
failed
If the stage completed its processing, but encountered and handled
one or more problems. Such problems may include failure of a module
build, failure of a test suite. Upon encountering such an problem,
the stage should call the "fail" method providing a description of
the problem, and then return from the "process" method.
aborted
If the stage died as a result of an error during processing.
Stages should simply call the "die" method to abort processing.
NB, the "confess" method should not be used to abort since,
autobuilder will automatically hook "confess" into the perl
SIG{__DIE__} handler.
skipped
If the stage was not executed due to the "is_enabled" flag being
set to false.
CONFIGURATION
All stage modules have a number of standard configuration options that
are used. Sub-classes are not permitted to define additional
configuration parameters, rather, they should use the "options"
parameter for their custom configuration needs.
name
A short alpha-numeric token representing the stage, typically based
on the last component of the name of the stage module
label
An arbitrary string describing the purpose of the stage, suitable
for presenting to users through email alerts, or HTML status pages.
enabled
A boolean flag indicating whether the stage is to be executed, or
skipped.
critical
A boolean flag indicating whether failure of a stage should be
considered fatal to the build process. NB, if a stage aborts, it is
always considered fatal, regardless of this flag.
options
A hash containing options specific to the particular stage sub-
class.
METHODS
my $stage = Test::AutoBuild::Stage->new(name => $name, label => $label,
[critical => $boolean,] [enabled => $boolean,] [options => \%options]);
Creates a new stage, with a name specified by the "name" parameter
and label by the "label" parameter. The optional "critical"
parameter can be used to change the behaviour of stages upon
failure, if omitted, will default to "true". The optional "enabled"
parameter can be used to disable execution of the stage, if
omitted, will default to "true". Finally, the "options" parameter
can be used to specify sub-class specific options.
$stage->init(%params);
A method to initialize the stage called automatically by the "run"
method, so see the docs for that method for details of the keys
accepted in the %params parameter.
my $boolean = $stage->pending();
Returns a true value if the stage is still pending execution.
my $boolean = $stage->failed();
Returns a true value if the stage encountered one or more problems
during execution. To mark a stage as failed, use the "fail" method
supplying a explanation of the failure.
my $boolean = $stage->succeeded();
Returns a true value if the stage completed execution without
encountering any problems
my $boolean = $stage->skipped();
Returns a true value if the stage was skipped, due to the
"is_enabled" flag being disabled.
my $boolean = $stage->aborted();
Returns a true value if the stage aborted, due to the "process"
method calling "die".
my $seconds = $stage->duration();
Returns the duration of the stage execution, rounded to the nearest
second.
$stage->fail($message);
Marks the stage as failing, providing an explanation with the
$message parameter. Should be called from the "process" method if
an expected error condition arises.
$value = $stage->option($name[, $newvalue]);
Retrieves the subclass specific configuration option specified by
the $name parameter. If the $newvalue parameter is supplied, then
the configuration option is updated.
$stage->run($runtime);
Executes the stage, recording the start and end time, and updating
the stage status to reflect the result of its execution. The
$runtime parameter should be an instance of the
Test::AutoBuild::Runtime module.
$stage->process($runtime);
This method should be implemented by subclasses to provide whatever
processing logic is required. The $runtime parameter should be an
instance of the Test::AutoBuild::Runtime module. The "process"
method should call the "fail" method is an expected error occurrs,
otherwise it should simply call "die".
AUTHORS
Daniel Berrange <dan@berrange.com>, Dennis Gregorovic
<dgregorovic@alum.mit.edu>
COPYRIGHT
Copyright (C) 2004 Red Hat, Inc.
SEE ALSOperl(1), Test::AutoBuild, Test::AutoBuild::Runtime
perl v5.14.1 2011-09-01 Test::AutoBuild::Stage(3)
