← Back to branch summary

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

« back to all changes in this revision

Viewing changes to plainbox/docs/manpages/plainbox-run.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-run.rst
1
 
================
2
 
plainbox-run (1)
3
 
================
4
 
 
5
 
.. argparse::
6
 
    :ref: plainbox.impl.box.get_parser_for_sphinx
7
 
    :prog: plainbox
8
 
    :manpage:
9
 
    :path: run
10
 
    :nodefault:
11
 
 
12
 
    This command runs zero or more Plainbox jobs as a part of a single session
13
 
    and saves the test results. Plainbox will follow the following high-level
14
 
    algorithm during the execution of this command.
15
 
 
16
 
    1. Parse command line arguments and look if there's a session that can be
17
 
       resumed (see **RESUMING** below). If so, offer the user a choice to
18
 
       resume that session. If the resume operation fails move to the next
19
 
       qualifying session. Finally offer to create a new session.
20
 
 
21
 
    2. If the session is being resumed, replay the effects of the session
22
 
       execution from the on-disk state. This recreates generated jobs and
23
 
       re-introduces the same resources into the session state. In other words,
24
 
       no jobs that have run in the past are re-ran.
25
 
 
26
 
       If the resumed session was about to execute a job then offer to skip the
27
 
       job. This allows test operators to skip jobs that have caused the system
28
 
       to crash in the past (e.g. system suspend tests)
29
 
 
30
 
       If the session is not being resumed (a new session was created), set the
31
 
       `incomplete` flag.
32
 
 
33
 
    3. Use the job selection (see **SELECTING JOBS** below) to derive the run
34
 
       list. This step involves resolving job dependencies and reordering jobs
35
 
       if required.
36
 
 
37
 
    4. Follow the run list, executing each job in sequence if possible.  Jobs
38
 
       can be inhibited from execution by failed dependencies or failed
39
 
       (evaluating to non-True result) resource expressions.
40
 
 
41
 
       If at any time a new job is being re-introduced into the system (see
42
 
       **GENERATED JOBS** below) then the loop is aborted and control jumps
43
 
       back to step 3 to re-select jobs. Existing results are not discarded so
44
 
       jobs that already have some results are not executed again.
45
 
 
46
 
       Before and after executing any job the session state is saved to disk to
47
 
       allow resuming from a job that somehow crashes the system or crashes
48
 
       Plainbox itself.
49
 
 
50
 
    5. Remove the `incomplete` flag.
51
 
 
52
 
    6. Export the state of the session to the desired format (see **EXPORTING
53
 
       RESULTS**) and use the desired transport to send the results (see
54
 
       **TRANSPORTING RESULTS**).
55
 
 
56
 
    7. Set the `submitted` flag.
57
 
 
58
 
    SELECTING JOBS
59
 
    ==============
60
 
 
61
 
    Plainbox offers two mechanisms for selecting jobs. Both can be used at the
62
 
    same time, both can be used multiple times.
63
 
 
64
 
    Selecting jobs with patterns
65
 
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
66
 
 
67
 
    The first mechanism is exposed through the ``--include-pattern PATTERN``
68
 
    command-line option. It instructs Plainbox to `select` any job whose
69
 
    fully-qualified identifier matches the regular expression ``PATTERN``.
70
 
 
71
 
    Jobs selected this way will be, if possible, ordered according to the order
72
 
    of command line arguments. For example, having the following command line
73
 
    would run the job `foo` before running the job `bar`:
74
 
 
75
 
        plainbox run -i '.*::foo' -i '.*::bar'
76
 
 
77
 
    Selecting jobs with whitelists
78
 
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
79
 
 
80
 
    The second mechanism is the ``--whitelist WHITELIST`` command-line option.
81
 
    WhiteLists (or test plans, which is somewhat easier to relate to).
82
 
    Whitelists are simple text files composed of a list of regular expressions,
83
 
    identical to those that may be passed with the ``-i`` option.
84
 
 
85
 
    Unlike the ``-i`` option though, there are two kinds of whitelists.
86
 
    Standalone whitelists are not associated with any Plainbox Provider.  Such
87
 
    whitelists can be distributed entirely separately from any other component
88
 
    and thus have no association with any namespace.
89
 
 
90
 
    Therefore, be fully qualified, each pattern must include both the namespace
91
 
    and the partial identifier components. For example, this is a valid, fully
92
 
    quallified whitelist::
93
 
 
94
 
        2013.com.canonical.plainbox::stub/.*
95
 
 
96
 
    It will unambiguously select some of the jobs from the special, internal
97
 
    StubBox provider that is built into Plainbox. It can be saved under any
98
 
    filename and stored in any directory and it will always select the same set
99
 
    of jobs.
100
 
 
101
 
    In contrast, whitelists that are associated with a particular provider, by
102
 
    being stored in the per-provider ``whitelists/`` directory, carry an
103
 
    implicit namespace. Such whitelists are typically written without
104
 
    mentioning the namespace component.
105
 
 
106
 
    For example, the same "stub/.*" pattern can be abbreviated to::
107
 
 
108
 
        stub/.*
109
 
 
110
 
    Typically this syntax is used in all whitelists specific to a particular
111
 
    provider unless the provider maintainer explicitly wants to include a job
112
 
    from another namespace (for example, one of the well-known Checkbox job
113
 
    definitions).
114
 
 
115
 
    GENERATED JOBS
116
 
    ==============
117
 
 
118
 
    Plainbox offers a way to generate jobs at runtime. There are two
119
 
    motivations for this feature.
120
 
 
121
 
    Instantiating Tests for Multiple Devices
122
 
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
123
 
 
124
 
    The classic example is to probe the hardware (for example, to enumerate all
125
 
    storage devices) and then duplicate each of the store specific tests so
126
 
    that all devices are tested separately.
127
 
 
128
 
    At this time jobs can be generated only from jobs using the plugin type
129
 
    `local`. Jobs of this kind are expected to print fully conforming job
130
 
    definitions on stdout. Generated jobs cause a few complexities and one
131
 
    limitation that is currently enforced is that generated jobs cannot
132
 
    generate additional jobs if any of the affected jobs need to run as another
133
 
    user.
134
 
 
135
 
    Another limitation is that jobs cannot override existing definitions.
136
 
 
137
 
    Creating Parent-Child Association
138
 
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
139
 
 
140
 
    A relatively niche and legacy feature of generated jobs is to print a
141
 
    verbatim copy of existing job definitions from a ``local`` job definition
142
 
    named afer a generic testing theme or category. For example the Checkbox
143
 
    job definition ``__wireless__`` prints, with the help of ``cat`` (1), all
144
 
    of the job definitions defined in the file ``wireless.txt``.
145
 
 
146
 
    This behavior is special-cased not to cause redefinition errors. Instead,
147
 
    existing definitions gain the ``via`` attribute that links them to the
148
 
    generator job. This feature is used by derivative application such as
149
 
    Checkbox. Plainbox is not using it at this time.
150
 
 
151
 
    RESUMING
152
 
    ========
153
 
 
154
 
    Plainbox offers a session resume functionality whereas a session that was
155
 
    interrupted (either purposefully or due to a malfunction) can be resumed
156
 
    and effectively continued where it was left off.
157
 
 
158
 
    When resuming a session you may be given an option to either re-run, pass,
159
 
    fail or skip the test job that was being executed before the session was
160
 
    interrupted. This is intended to handle both normal situations, such as a
161
 
    "system reboot test" where it is perfectly fine to "pass" the test without
162
 
    re-running the command. In addition it can be used to handle anomalous
163
 
    cases where the machine misbehaves and re-running the same test would cause
164
 
    the problem to occur again indefinitely.
165
 
 
166
 
    Limitations
167
 
    ^^^^^^^^^^^
168
 
 
169
 
    This functionality does not allow to interrupt and resume a test job that
170
 
    is already being executed. Such job will be restarted from scratch.
171
 
 
172
 
    Plainbox tries to ensure that a single session is consistent and the
173
 
    assumptions that held at the start of the session are maintained at the
174
 
    end. To that end, Plainbox will try to ensure that job definitions have not
175
 
    changed between two separate invocations that worked with a single session.
176
 
    If such a situation is detected the session will not be resumed.
177
 
 
178
 
    EXPORTING RESULTS
179
 
    =================
180
 
 
181
 
    Plainbox offers a way to export the internal state of the session into a
182
 
    more useful format for further processing.
183
 
 
184
 
    Selecting Exporters
185
 
    ^^^^^^^^^^^^^^^^^^^
186
 
 
187
 
    The exporter can be selected using the ``--output-format FORMAT``
188
 
    command-line option. A list of available exporters (which may include 3rd
189
 
    party exporters) can be obtained by passing the ``--output-format ?``
190
 
    option.
191
 
 
192
 
    Some formats are more useful than others in that they are capable of
193
 
    transferring more of the internal state. Depending on your application you
194
 
    may wish to choose the most generic format (json) and process it further
195
 
    with additional tools, choose the most basic format (text) just to get a
196
 
    simple summary of the results or lastly choose one of the two specialized
197
 
    formats (xml and html) that are specific to the Checkbox workflow.
198
 
 
199
 
    Out of the box the following exporters are supported:
200
 
 
201
 
    html
202
 
    ----
203
 
 
204
 
    This exporter creates a static HTML page with human-readable test report.
205
 
    It is useful for communicating with other humans and since it is entirely
206
 
    standalone and off-line it can be sent by email or archived.
207
 
 
208
 
    json
209
 
    ----
210
 
 
211
 
    This exporter creates a JSON document with the internal representation
212
 
    of the session state. It is the most versatile exporter and it is useful
213
 
    and easy for further processing. It is not particularly human-readable
214
 
    but can be quite useful for high-level debugging without having to use
215
 
    pdb and know the internals of Plainbox.
216
 
 
217
 
    rfc822
218
 
    ------
219
 
 
220
 
    This exporter creates quasi-RFC822 documents. It is rather limited and not
221
 
    used much. Still, it can be useful in some circumstances.
222
 
 
223
 
    text
224
 
    ----
225
 
 
226
 
    This is the default exporter. It simply prints a human-readable
227
 
    representation of test results without much detail. It discards nearly all
228
 
    of the internal state though.
229
 
 
230
 
    xlsx
231
 
    ----
232
 
 
233
 
    This exporter creates a standalone .xlsx (XML format for Microsoft Excel)
234
 
    file that contains a human-readable test report. It is quit similar to the
235
 
    HTML report but it is easier to edit. It is useful for communicating with
236
 
    other humans and since it is entirely standalone and off-line it can be
237
 
    sent by email or archived.
238
 
 
239
 
    It depends on python3-xlsxwriter package
240
 
 
241
 
    hexr
242
 
    ----
243
 
 
244
 
    This exporter creates a rather confusingly named XML document only
245
 
    applicable for internal Canonical Hardware Certification Team workflow.
246
 
 
247
 
    It is not a generic XML representation of test results and instead it
248
 
    carries quite a few legacy constructs that are only retained for
249
 
    compatibility with other internal tools. If you want generic processing
250
 
    look for JSON instead.
251
 
 
252
 
    Selecting Exporter Options
253
 
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
254
 
 
255
 
    Certain exporters offer a set of options that can further customize the
256
 
    exported data. A full list of options available for each exporter can be
257
 
    obtained by passing the ``--output-options ?`` command-line option.
258
 
 
259
 
    Options may be specified as a comma-separated list. Some options act as
260
 
    simple flags, other options can take an argument with the ``option=value``
261
 
    syntax.
262
 
 
263
 
    Known exporter options are documented below:
264
 
 
265
 
    json
266
 
    ----
267
 
 
268
 
    with-io-log:
269
 
        Exported data will include the input/output log associated with each
270
 
        job result. The data is included in its native three-tuple form unless
271
 
        one of the `squash-io-log` or `flatten-io-log` options are used as
272
 
        well.
273
 
 
274
 
        IO logs are representations of the data produced by the process created
275
 
        from the shell command associated with some jobs.
276
 
 
277
 
    squash-io-log:
278
 
        When used together with `with-io-log` option it causes Plainbox to
279
 
        discard the stream name and time-stamp and just include a list of
280
 
        base64-encoded binary strings. This option is more useful for
281
 
        reconstructing simple "log files"
282
 
 
283
 
    flatten-io-log:
284
 
        When used together with `with-io-log` option it causes Plainbox to
285
 
        concatenate all of the separate base64-encoded records into one large
286
 
        base64-encoded binary string representing the whole communication that
287
 
        took place.
288
 
 
289
 
    with-run-list:
290
 
        Exported data will include the run list (sequence of jobs computed from
291
 
        the desired job list).
292
 
 
293
 
    with-job-list:
294
 
        Exported data will include the full list of jobs known to the system
295
 
 
296
 
    with-resource-map:
297
 
        Exported data will include the full resource map. Resources are records
298
 
        of key-value sets that are associated with each job result for jobs
299
 
        that have plugin type `resource`. They are expected to be printed to
300
 
        `stdout` by such `resource jobs` and are parsed and stored by Plainbox.
301
 
 
302
 
    with-job-defs:
303
 
        Exported data will include some of the properties of each job
304
 
        definition. Currently this set includes the following fields: `plugin`,
305
 
        `requires`, `depends`, `command` and `description`.
306
 
 
307
 
    with-attachments:
308
 
        Exported data will include attachments. Attachments are created from
309
 
        `stdout` stream of each job having plugin type `attachment`. The actual
310
 
        attachments are base64-encoded.
311
 
 
312
 
    with-comments:
313
 
        Exported data will include comments added by the test operator to each
314
 
        job result that has them.
315
 
 
316
 
    with-job-via:
317
 
        Exported data will include the ``via`` attribute alongside each job
318
 
        result. The via attribute contains the checksum of the job definition
319
 
        that generated a particular job definition. This is useful for tracking
320
 
        jobs generated by jobs with the plugin type `local`.
321
 
 
322
 
    with-job-hash:
323
 
        Exported data will include the ``hash`` attribute alongside each job
324
 
        result. The hash attribute is the checksum of the job definition's
325
 
        data. It can be useful alongside with `with-job-via`.
326
 
 
327
 
    machine-json:
328
 
        The generated JSON document will be minimal (devoid of any optional
329
 
        whitespace). This option is best to be used if the result is not
330
 
        intended to be read by humans as it saves some space.
331
 
 
332
 
    rfc822
333
 
    ------
334
 
 
335
 
    All of the options have the same meaning as for the `json` exporter:
336
 
    `with-io-log`, `squash-io-log`, `flatten-io-log`, `with-run-list`,
337
 
    `with-job-list`, `with-resource-map`, `with-job-defs`, `with-attachments`,
338
 
    `with-comments`, `with-job-via`, `with-job-hash`.  The only exception is
339
 
    the `machine-json` option which doesn't exist for this exporter.
340
 
 
341
 
    text
342
 
    ----
343
 
 
344
 
    Same as with rfc822.
345
 
 
346
 
    xlsx
347
 
    ----
348
 
 
349
 
    with-sys-info:
350
 
        Exported spreadsheet will include a worksheet detailing the hardware
351
 
        devices based on lspci, lsusb, udev, etc.
352
 
 
353
 
    with-summary:
354
 
        Exported spreadsheet will include test figures. This includes the
355
 
        percentage of tests that have passed, have failed, have been skipped
356
 
        and the total count.
357
 
 
358
 
    with-job-description:
359
 
        Exported spreadsheet will include job descriptions on a separate sheet
360
 
 
361
 
    with-text-attachments:
362
 
        Exported spreadsheet will include text attachments on a separate sheet
363
 
 
364
 
    xml
365
 
    ---
366
 
 
367
 
    client-name:
368
 
        This option allows clients to override the name of the application
369
 
        generating the XML document. By default that name is `plainbox`.  To
370
 
        use this option pass ``--output-options client-name=other-name``
371
 
        command-line option.
372
 
 
373
 
    TRANSPORTING RESULTS
374
 
    ====================
375
 
 
376
 
    Exported results can be either saved to a file (this is the most basic,
377
 
    default transport) or can be handed to one of the transport systems for
378
 
    further processing. The idea is that specialized users can provide their
379
 
    own transport systems (often coupled with a specific exporter) to move the
380
 
    test results from the system-under-test to a central testing result
381
 
    repository.
382
 
 
383
 
    Transport can be selected with the ``--transport`` option. Again, as with
384
 
    exporters, a list of known transports can be obtained by passing the
385
 
    ``--transport ?`` option. Transports need a destination URL which can be
386
 
    specified with the ``--transport-where=`` option. The syntax of the URL
387
 
    varies by transport type.
388
 
 
389
 
    Plainbox comes equipped with the following transports:
390
 
 
391
 
    launchpad
392
 
    ^^^^^^^^^
393
 
 
394
 
    This transport can send the results exported using ``xml`` exporter to the
395
 
    Launchpad Hardware Database. This is a little-known feature offered by the
396
 
    https://launchpad.net/ website.
397
 
 
398
 
    certification
399
 
    ^^^^^^^^^^^^^
400
 
 
401
 
    This transport can send the results exported using the ``xml`` exporter to
402
 
    the Canonical Certification Website (https://certification.canonical.com).
403
 
 
404
 
    This transport is of little use to anyone but the Canonical Hardware
405
 
    Certification Team that also maintains Plainbox and Checkbox but it is
406
 
    mentioned here for completeness.
407
 
 
408
 
See Also
409
 
========
410
 
 
411
 
:doc:`plainbox-dev-analyze`