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 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::Runtime