Test::AutoBuild::Stage - The base class for an AutoBuild stage
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 ... }
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.
process
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:
run
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.
fail
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.
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.
die
confess
If the stage was not executed due to the is_enabled flag being set to false.
is_enabled
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.
options
A short alpha-numeric token representing the stage, typically based on the last component of the name of the stage module
An arbitrary string describing the purpose of the stage, suitable for presenting to users through email alerts, or HTML status pages.
A boolean flag indicating whether the stage is to be executed, or skipped.
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.
A hash containing options specific to the particular stage sub-class.
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.
name
label
critical
true
enabled
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.
%params
Returns a true value if the stage is still pending execution.
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.
Returns a true value if the stage completed execution without encountering any problems
Returns a true value if the stage was skipped, due to the is_enabled flag being disabled.
Returns a true value if the stage aborted, due to the process method calling die.
Returns the duration of the stage execution, rounded to the nearest second.
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.
$message
Retrieves the subclass specific configuration option specified by the $name parameter. If the $newvalue parameter is supplied, then the configuration option is updated.
$name
$newvalue
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.
$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.
Daniel Berrange <dan@berrange.com>, Dennis Gregorovic <dgregorovic@alum.mit.edu>
Copyright (C) 2004 Red Hat, Inc.
perl(1), Test::AutoBuild, Test::AutoBuild::Runtime
perl(1)
To install Test::AutoBuild, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::AutoBuild
CPAN shell
perl -MCPAN -e shell install Test::AutoBuild
For more information on module installation, please visit the detailed CPAN module installation guide.