← Back to branch summary

~jocave/checkbox/hybrid-amd-gpu-mods

« back to all changes in this revision

Viewing changes to plainbox/docs/manpages/plainbox-test-plan-units.rst

  • Committer: Tarmac
  • Author(s): Brendan Donegan
  • Date: 2013-06-03 11:12:58 UTC
  • mfrom: (2154.2.1 bug1185759)
  • Revision ID: tarmac-20130603111258-1b3m5ydvkf1accts
"[r=zkrynicki][bug=1185759][author=brendan-donegan] automatic merge by tarmac"

Show diffs side-by-side

added added

removed removed

Lines of Context:
plainbox/docs/manpages/plainbox-test-plan-units.rst
1
 
============================
2
 
plainbox-test-plan-units (7)
3
 
============================
4
 
 
5
 
Synopsis
6
 
========
7
 
 
8
 
This page documents the Plainbox test plan units syntax and runtime behavior
9
 
 
10
 
Description
11
 
===========
12
 
 
13
 
The test plan unit is an evolution of the Plainbox whitelist concept, that is,
14
 
a facility that describes a sequence of job definitions that should be executed
15
 
together.
16
 
 
17
 
As in whitelists, jobs definitions are _selected_ by either listing their
18
 
identifier or a regular expression that matches their identifier. Selected
19
 
jobs are executed in the sequence they appear in the list, unless they need to
20
 
be reordered to satisfy dependencies which always take priority.
21
 
 
22
 
Unlike whitelists, test plans can contain additional meta-data which can be
23
 
used in a graphical user interface. You can assign a translatable name and
24
 
description to each test plan. This used to be done informally by naming the
25
 
``.whitelist`` file appropriately, with some unique filename and including
26
 
some #-based comments at the top of the file.
27
 
 
28
 
Test plans are also typical units so they can be defined with the familiar
29
 
RFC822-like syntax that is also used for job definitions. They can also be
30
 
multiple test plan definitions per file, just like with all the other units,
31
 
including job definitions.
32
 
 
33
 
Test Plan Fields
34
 
-----------------
35
 
 
36
 
The following fields can be used in a test plan. Note that **not all** fields
37
 
need to be used or even should be used. Please remember that Checkbox needs to
38
 
maintain backwards compatibility so some of the test plans it defines may have
39
 
non-typical constructs required to ensure proper behavior. You don't have to
40
 
copy such constructs when working on a new test plan from scratch
41
 
 
42
 
``id``:
43
 
    Each test plan needs to have a unique identifier. This is exactly the same
44
 
    as with other units that have an identifier (like job definitions
45
 
    and categories).
46
 
 
47
 
    This field is not used for display purposes but you may need to refer
48
 
    to it on command line so keeping it descriptive is useful
49
 
 
50
 
``name``:
51
 
    A human-readable name of the test plan. The name should be relatively short
52
 
    as it may be used to display a list of test plans to the test operator.
53
 
 
54
 
    Remember that the user or the test operator may not always be familiar with
55
 
    the scope of testing that you are focusing on. Also consider that multiple
56
 
    test providers may be always installed at the same time. The translated
57
 
    version of the name (and icon, see below) is the only thing that needs
58
 
    to allow the test operator to  pick the right test plan.
59
 
 
60
 
    Please use short and concrete names like:
61
 
     - "Storage Device Certification Tests"
62
 
     - "Ubuntu Core Application's Clock Acceptance Tests"
63
 
     - "Default Ubuntu Hardware Certification Tests".
64
 
 
65
 
    The field has a soft limit of eighty characters. It cannot have multiple
66
 
    lines. This field should be marked as translatable by prepending the
67
 
    underscore character (\_) in front. This field is mandatory.
68
 
 
69
 
``description``:
70
 
    A human-readable description of this test plan. Here you can include as
71
 
    many or few details as you'd like. Some applications may offer a way
72
 
    of viewing this data. In general it is recommended to include a description
73
 
    of what is being tested so that users can make an informed decision but
74
 
    please in mind that the ``name`` field alone must be sufficient to
75
 
    discriminate between distinct test plans so you don't have to duplicate
76
 
    that information in the description.
77
 
 
78
 
    If your tests will require any special set-up (procuring external hardware,
79
 
    setting some devices or software in special test mode) it is recommended
80
 
    to include this information here.
81
 
 
82
 
    The field has no size limit. It can contain newline characters. This field
83
 
    should be marked as translatable by prepending the underscore character
84
 
    (\_) in front. This field is optional.
85
 
 
86
 
``include``:
87
 
    A multi-line list of job identifiers or patterns matching such identifiers
88
 
    that should be included for execution.
89
 
 
90
 
    This is the most important field in any test plan. It basically decides
91
 
    on which job definitions are selected by (included by) the test plan.
92
 
    Separate entries need to be placed on separate lines. White space does not
93
 
    separate entries as the id field may (sic!) actually include spaces.
94
 
 
95
 
    You have two options for selecting tests:
96
 
 
97
 
     - You can simply list the identifier (either partial or fully qualified)
98
 
       of the job you want to include in the test plan directly. This is very
99
 
       common and most test plans used by Checkbox actually look like that.
100
 
 
101
 
     - You can use regular expressions to select many tests at the same time.
102
 
       This is the only way to select generated jobs (created either by
103
 
       template units or by job definitions using the legacy 'local' plugin
104
 
       type). Please remember that the dot character has a special meaning
105
 
       so unless you actually want to match *any character* escape the dot
106
 
       with the backslash character (\\).
107
 
 
108
 
    Regardless of if you use patterns or literal job identifiers you can use
109
 
    their fully qualified name (the one that includes the namespace they reside
110
 
    in) or an abbreviated form. The abbreviated form is applicable for job
111
 
    definitions that reside in the same namespace (but not necessarily the same
112
 
    provider) as the provider that is defining the test plan.
113
 
 
114
 
    Plainbox will catch incorrect references to unknown jobs so you should
115
 
    be relatively safe. Have a look at the examples section below for examples
116
 
    on how you can refer to jobs from other providers (you simply use their
117
 
    fully qualified name for that)
118
 
 
119
 
``mandatory_include``:
120
 
    A multi-line list of job identifiers or patterns matching such identifiers
121
 
    that should always be executed.
122
 
 
123
 
    This optional field can be used to specify the jobs that should always run.
124
 
    This is particularly useful for specifying jobs that gather vital
125
 
    info about the tested system, as it renders imposible to generate a report
126
 
    with no information about system under test.
127
 
 
128
 
    For example, session results meant to be sent to the Ubuntu certification
129
 
    website must include the special job: miscellanea/submission-resources
130
 
 
131
 
    Example:
132
 
 
133
 
        mandatory_include:
134
 
            miscellanea/submission-resources
135
 
 
136
 
    Note that mandatory jobs will always be run first (along with their
137
 
    dependant jobs)
138
 
 
139
 
``bootstrap_include``:
140
 
    A multi-line list of job identifiers that should be run first, before the
141
 
    main body of testing begins. The job that should be included in the
142
 
    bootstrapping sections are the ones generating or helping to generate other
143
 
    jobs.
144
 
 
145
 
    Example:
146
 
 
147
 
        bootstrap_include:
148
 
            graphics/generator_driver_version
149
 
 
150
 
    Note that each entry in the bootstrap_include section must be a valid job
151
 
    identifier and cannot be a regular expression pattern.
152
 
    Also note that only local and resource jobs are allowed in this section.
153
 
 
154
 
``exclude``:
155
 
    A multi-line list of job identifiers or patterns matching such identifiers
156
 
    that should be excluded from execution.
157
 
 
158
 
    This optional field can be used to prevent some jobs from being selected
159
 
    for execution. It follows the similarly named  ``-x`` command line option
160
 
    to the ``plainbox run`` command.
161
 
 
162
 
    This field may be used when a general (broad) selection is somehow made
163
 
    by the ``include`` field and it must be trimmed down (for example, to
164
 
    prevent a specific dangerous job from running). It has the same syntax
165
 
    as the ``include``.
166
 
 
167
 
    When a job is both included and excluded, exclusion always takes priority.
168
 
 
169
 
``category-overrides``:
170
 
    A multi-line list of category override statements.
171
 
 
172
 
    This optional field can be used to alter the natural job definition
173
 
    category association. Currently Plainbox allows each job definition to
174
 
    associate itself with at most one category (see plainbox-category-units(7)
175
 
    and plainbox-job-units(7) for details). This is sub-optimal as some tests
176
 
    can be easily assigned equally well to two categories at the same time.
177
 
 
178
 
    For that reason, it may be necessary, in a particular test plan, to
179
 
    override the natural category association with one that more correctly
180
 
    reflects the purpose of a specific job definition in the context of a
181
 
    specific test plan.
182
 
 
183
 
    For example let's consider a job definition that tests if a specific piece
184
 
    of hardware works correctly after a suspend-resume cycle. Let's assume that
185
 
    the job definition  has a natural association with the category describing
186
 
    such hardware devices. In one test plan, this test will be associated
187
 
    with the hardware-specific category (using the natural association). In
188
 
    a special suspend-resume test plan the same job definition can
189
 
    be associated with a special suspend-resume category.
190
 
 
191
 
    The actual rules as to when to use category overrides and how to assign
192
 
    a natural category to a specific test is not documented here. We believe
193
 
    that each project should come up with a workflow and semantics that best
194
 
    match its users.
195
 
 
196
 
    The syntax of this field is a list of statements defined on separate lines.
197
 
    Each override statement has the following form::
198
 
 
199
 
        apply CATEGORY-IDENTIFIER to JOB-DEFINITION-PATTERN
200
 
 
201
 
    Both 'apply' and 'to' are literal strings. CATEGORY-IDENTIFIER is
202
 
    the identifier of a category unit. The JOB-DEFINITION-PATTERN has the
203
 
    same syntax as the ``include`` field does. That is, it can be either
204
 
    a simple string or a regular expression that is being compared to
205
 
    identifiers of all the known job definitions. The pattern can be
206
 
    either partially or fully qualified. That is, it may or may not
207
 
    include the namespace component of the job definition identifier.
208
 
 
209
 
    Overrides are applied in order and the last applied override is the
210
 
    effective override in a given test plan. For example, given the
211
 
    following two overrides::
212
 
 
213
 
        apply cat-1 to .*
214
 
        apply cat-2 to foo
215
 
 
216
 
    The job definition with the partial identifier ``foo`` will be associated
217
 
    with the ``cat-2`` category.
218
 
 
219
 
.. _testplan_estimated_duration:
220
 
 
221
 
``estimated_duration``:
222
 
    An approximate time to execute this test plan, in seconds.
223
 
 
224
 
    Since plainbox version 0.24 this field can be expressed in two formats. The
225
 
    old format, a floating point number of seconds is somewhat difficult to
226
 
    read for larger values. To avoid mistakes test designers can use the second
227
 
    format with separate sections for number of hours, minutes and seconds. The
228
 
    format, as regular expression, is ``(\d+h)?[: ]*(\d+m?)[: ]*(\d+s)?``. The
229
 
    regular expression expresses an optional number of hours, followed by the
230
 
    ``h`` character, followed by any number of spaces or ``:`` characters,
231
 
    followed by an optional number of minutes, followed by the ``m`` character,
232
 
    again followed by any number of spaces or ``:`` characters, followed by the
233
 
    number of seconds, ultimately followed by the ``s`` character.
234
 
 
235
 
    The values can no longer be fractional (you cannot say ``2.5m`` you need to
236
 
    say ``2m 30s``). We feel that sub-second granularity does is too
237
 
    unpredictable to be useful so that will not be supported in the future.
238
 
 
239
 
    This field is optional. If it is missing it is automatically computed by
240
 
    the identical field that may be specified on particular job definitions.
241
 
 
242
 
    Since sometimes it is easier to think in terms of test plans (they are
243
 
    typically executed more often than a specific job definition) this estimate
244
 
    may be more accurate as it doesn't include the accumulated sum of
245
 
    mis-estimates from all of the job definitions selected by a particular test
246
 
    plan.
247
 
 
248
 
Migrating From Whitelists
249
 
-------------------------
250
 
 
251
 
Migrating from whitelists is optional but strongly recommended. Whitelists
252
 
are discouraged but neither deprecated nor unsupported. As we progress on the
253
 
transition we are likely to fully deprecate and subsequently remove the
254
 
classical form of whitelits (as are typically found in many ``*.whitelist``
255
 
files).
256
 
 
257
 
The first thing you need to do is to create a file that will hold your test
258
 
plans. You should put that file in the ``units/`` directory of your provider.
259
 
 
260
 
Note that a file that holds a test plan may also hold any other units.
261
 
The decision on how to structure your provider is up to you and the particular
262
 
constraints and recommended practices of the project you are participating in.
263
 
 
264
 
Having selected an appropriate file simply copy your old whitelist (just one)
265
 
and paste it into the _template_ below::
266
 
 
267
 
    unit: test plan
268
 
    id: << DERIVE A PROPER IDENTIFIER FROM THE NAME OF THE WHITELIST FILE >>
269
 
    _name: << COME UP WITH A PROPER NAME OF THIS TEST PLAN >>
270
 
    _description:
271
 
        << COME UP WITH A PROPER DESCRIPTION OF THIS TEST PLAN >>
272
 
    include:
273
 
        << PASTE THE FULL TEXT OF YOUR OLD WHITELIST >>
274
 
 
275
 
Note that you may also add the ``estimated_duration`` field but this is not
276
 
required. Sometimes it is easier to provide a rough estimate of a whole test
277
 
plan rather than having to compute it from all the job definitions it selects.
278
 
 
279
 
Examples
280
 
--------
281
 
 
282
 
A simple test plan that selects several jobs::
283
 
 
284
 
    id: foo-bar-and-froz
285
 
    _name: Tests Foo, Bar and Froz
286
 
    _description:
287
 
        This example test plan selects the following three jobs:
288
 
            - Foo
289
 
            - Bar
290
 
            - Froz
291
 
    include:
292
 
        foo
293
 
        bar
294
 
        froz
295
 
 
296
 
A test plan that uses jobs from another provider's namespace in addition
297
 
to some of its own definitions::
298
 
 
299
 
    id: extended-tests
300
 
    _name: Extended Storage Tests (By Corp Inc.)
301
 
    _description:
302
 
        This test plan runs an extended set of storage tests, customized
303
 
        by the Corp Inc. corporation. In addition to the standard Ubuntu
304
 
        set of storage tests, this test plan includes the following tests::
305
 
 
306
 
        - Multipath I/O Tests
307
 
        - Degraded Array Recovery Tests
308
 
    include:
309
 
        2013.com.canonical.certification:disk/.*
310
 
        multipath-io
311
 
        degrade-array-recovery
312
 
 
313
 
A test plan that generates jobs using bootstrap_include section::
314
 
 
315
 
    unit: test plan
316
 
    id: test-plan-with-bootstrapping
317
 
    _name: Tests with a bootstrapping stage
318
 
    _description:
319
 
        This test plan uses bootstrapping_include field to generate additional
320
 
        jobs depending on the output of the generator job.
321
 
    include: .*
322
 
    bootstrap_include:
323
 
        generator
324
 
 
325
 
    unit: job
326
 
    id: generator
327
 
    plugin: resource
328
 
    _description: Job that generates Foo and Bar resources
329
 
    command:
330
 
     echo "my_resource: Foo"
331
 
     echo
332
 
     echo "my_resource: Bar"
333
 
 
334
 
    unit: template
335
 
    template-unit: job
336
 
    template-resource: generator
337
 
    plugin: shell
338
 
    estimated_duration: 1
339
 
    id: generated_job_{my_resource}
340
 
    command: echo {my_resource}
341
 
    _description: Job instantiated from template that echoes {my_resource}
342
 
 
343
 
 
344
 
 
345
 
A test plan that marks some jobs as mandatory::
346
 
 
347
 
    unit: test plan
348
 
    id: test-plan-with-mandatory-jobs
349
 
    _name: Test plan with mandatory jobs
350
 
    _description:
351
 
        This test plan runs some jobs regardless of user selection.
352
 
    include:
353
 
        Foo
354
 
    mandatory_include:
355
 
        Bar
356
 
 
357
 
    unit: job
358
 
    id: Foo
359
 
    _name: Foo job
360
 
    _description: Job that might be deselected by the user
361
 
    plugin: shell
362
 
    command: echo Foo job
363
 
 
364
 
    unit: job
365
 
    id: Bar
366
 
    _name: Bar job (mandatory)
367
 
    _description: Job that should *always* run
368
 
    plugin: shell
369
 
    command: echo Bar job