Rechercher une page de manuel
Test::AutoBuild::Stage.3pm
Langue: en
Version: 2007-12-08 (fedora - 06/07/09)
Section: 3 (Bibliothèques de fonctions)
NAME
Test::AutoBuild::Stage - The base class for an AutoBuild stageSYNOPSIS
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 ALSO
perl(1), Test::AutoBuild, Test::AutoBuild::RuntimeContenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre