1Test::AutoBuild::Stage(U3s)er Contributed Perl DocumentatTieosnt::AutoBuild::Stage(3)
2
6 Test::AutoBuild::Stage - The base class for an AutoBuild stage
7
9 use Test::AutoBuild::Stage
10 my $stage = Test::AutoBuild::Stage->new(name => $token,
12 label => $string,
13 [critical => $boolean,]
14 [enabled => $boolean]);
15 # Execute the stage
17 $stage->run($runtime);
18 if ($stage->aborted()) { # Very badly wrong
21 die $stage->log();
22 } elsif ($stage->failed()) { # Expected failure
23 if ($stage->is_critical()) { # Non-recoverable
24 .. do failure case ...
25 } else {
26 .. do recovery case ...
27 }
28 } elsif ($stage->success() || # Everything's ok
29 $stage->skipped()) {
30 .. do normal case ...
31 }
32
34 This module is an abstract base class for all AutoBuild stages. If
35 defines a handful of common methods and the abstract method "process"
36 to be implemented by sub-classes to provide whatever custom processing
37 is required.
38 STATUS
40 The status of a stage starts off as 'pending', and when the "run"
41 method is invoked, the status will changed to one of the following:
42 success
44 If the stage completed its processing without encountering any
45 problems. Stages will automatically have their status set to this
46 value if their "process" method completes without the "fail" method
47 having been called.
48 failed
50 If the stage completed its processing, but encountered and handled
51 one or more problems. Such problems may include failure of a module
52 build, failure of a test suite. Upon encountering such an problem,
53 the stage should call the "fail" method providing a description of
54 the problem, and then return from the "process" method.
55 aborted
57 If the stage died as a result of an error during processing.
58 Stages should simply call the "die" method to abort processing.
59 NB, the "confess" method should not be used to abort since,
60 autobuilder will automatically hook "confess" into the perl
61 SIG{__DIE__} handler.
62 skipped
64 If the stage was not executed due to the "is_enabled" flag being
65 set to false.
66
68 All stage modules have a number of standard configuration options that
69 are used. Sub-classes are not permitted to define additional
70 configuration parameters, rather, they should use the "options"
71 parameter for their custom configuration needs.
72 name
74 A short alpha-numeric token representing the stage, typically based
75 on the last component of the name of the stage module
76 label
78 An arbitrary string describing the purpose of the stage, suitable
79 for presenting to users through email alerts, or HTML status pages.
80 enabled
82 A boolean flag indicating whether the stage is to be executed, or
83 skipped.
84 critical
86 A boolean flag indicating whether failure of a stage should be
87 considered fatal to the build process. NB, if a stage aborts, it is
88 always considered fatal, regardless of this flag.
89 options
91 A hash containing options specific to the particular stage sub-
92 class.
93
95 my $stage = Test::AutoBuild::Stage->new(name => $name, label => $label,
96 [critical => $boolean,] [enabled => $boolean,] [options => \%options]);
97 Creates a new stage, with a name specified by the "name" parameter
98 and label by the "label" parameter. The optional "critical"
99 parameter can be used to change the behaviour of stages upon
100 failure, if omitted, will default to "true". The optional "enabled"
101 parameter can be used to disable execution of the stage, if
102 omitted, will default to "true". Finally, the "options" parameter
103 can be used to specify sub-class specific options.
104 $stage->init(%params);
106 A method to initialize the stage called automatically by the "run"
107 method, so see the docs for that method for details of the keys
108 accepted in the %params parameter.
109 my $boolean = $stage->pending();
111 Returns a true value if the stage is still pending execution.
112 my $boolean = $stage->failed();
114 Returns a true value if the stage encountered one or more problems
115 during execution. To mark a stage as failed, use the "fail" method
116 supplying a explanation of the failure.
117 my $boolean = $stage->succeeded();
119 Returns a true value if the stage completed execution without
120 encountering any problems
121 my $boolean = $stage->skipped();
123 Returns a true value if the stage was skipped, due to the
124 "is_enabled" flag being disabled.
125 my $boolean = $stage->aborted();
127 Returns a true value if the stage aborted, due to the "process"
128 method calling "die".
129 my $seconds = $stage->duration();
131 Returns the duration of the stage execution, rounded to the nearest
132 second.
133 $stage->fail($message);
135 Marks the stage as failing, providing an explanation with the
136 $message parameter. Should be called from the "process" method if
137 an expected error condition arises.
138 $value = $stage->option($name[, $newvalue]);
140 Retrieves the subclass specific configuration option specified by
141 the $name parameter. If the $newvalue parameter is supplied, then
142 the configuration option is updated.
143 $stage->run($runtime);
145 Executes the stage, recording the start and end time, and updating
146 the stage status to reflect the result of its execution. The
147 $runtime parameter should be an instance of the
148 Test::AutoBuild::Runtime module.
149 $stage->process($runtime);
151 This method should be implemented by subclasses to provide whatever
152 processing logic is required. The $runtime parameter should be an
153 instance of the Test::AutoBuild::Runtime module. The "process"
154 method should call the "fail" method is an expected error occurrs,
155 otherwise it should simply call "die".
156
158 Daniel Berrange <dan@berrange.com>, Dennis Gregorovic
159 <dgregorovic@alum.mit.edu>
160
162 Copyright (C) 2004 Red Hat, Inc.
163
165 perl(1), Test::AutoBuild, Test::AutoBuild::Runtime
166perl v5.12.1 2007-12-08 Test::AutoBuild::Stage(3)