NAME
Test::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 thefail
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 theprocess
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, theconfess
method should not be used to abort since, autobuilder will automatically hookconfess
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 thelabel
parameter. The optionalcritical
parameter can be used to change the behaviour of stages upon failure, if omitted, will default totrue
. The optionalenabled
parameter can be used to disable execution of the stage, if omitted, will default totrue
. Finally, theoptions
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 callingdie
. - 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 theprocess
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. Theprocess
method should call thefail
method is an expected error occurrs, otherwise it should simply calldie
.
AUTHORS
Daniel Berrange <dan@berrange.com>, Dennis Gregorovic <dgregorovic@alum.mit.edu>
COPYRIGHT
Copyright (C) 2004 Red Hat, Inc.
SEE ALSO
perl(1)
, Test::AutoBuild, Test::AutoBuild::Runtime