← Back to branch summary

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

« back to all changes in this revision

Viewing changes to plainbox/docs/usage.rst

  • Committer: Zygmunt Krynicki
  • Date: 2013-05-17 13:54:25 UTC
  • mto: This revision was merged to the branch mainline in revision 2130.
  • Revision ID: zygmunt.krynicki@canonical.com-20130517135425-cxcenxx5t0qrtbxd
checkbox-ng: add CheckBoxNG sub-project

CheckBoxNG (or lowercase as checkbox-ng, pypi:checkbox-ng) is a clean
implementation of CheckBox on top of PlainBox. It provides a new
executable, 'checkbox' that has some of the same commands that were
previously implemented in the plainbox package.

In particular CheckBoxNG comes with the 'checkbox sru' command
(the same one as in plainbox). Later on this sub-command will be removed
from plainbox.

CheckBoxNG depends on plainbox >= 0.3

Signed-off-by: Zygmunt Krynicki <zygmunt.krynicki@canonical.com>

Show diffs side-by-side

added added

removed removed

Lines of Context:
plainbox/docs/usage.rst
1
1
.. _usage:
2
2
 
3
 
Basic Usage
4
 
===========
 
3
Usage
 
4
=====
5
5
 
6
 
Currently :term:`Plainbox` has no graphical user interface. To use it you need
 
6
Currently :term:`PlainBox` has no graphical user interface. To use it you need
7
7
to use the command line.
8
8
 
9
 
Plainbox has built-in help system so running :command:`plainbox run --help`
 
9
Basically there is just one command that does everything we can do so far, that
 
10
is :command:`plainbox run`. It has a number of options that tell it which
 
11
:term:`job` to run and what to do with results.
 
12
 
 
13
PlainBox has built-in help system so running :command:`plainbox run --help`
10
14
will give you instant information about all the various arguments and options
11
15
that are available. This document is not intended to replace that.
12
16
 
13
17
Running a specific job
14
18
^^^^^^^^^^^^^^^^^^^^^^
15
19
 
16
 
Basically there is just one command that does everything we can do so far, that
17
 
is :command:`plainbox run`. It has a number of options that tell it which
18
 
:term:`job` to run and what to do with results.
19
 
 
20
20
To run a specific :term:`job` pass it to the ``--include-pattern`` or ``-i``
21
21
option.
22
22
 
23
 
For example, to run one of the internal "smoke" test job:
 
23
For example, to run the ``cpu/scaling_test`` job:
24
24
 
25
25
.. code-block:: bash
26
26
 
27
 
    $ plainbox run -i 2013.com.canonical.plainbox::stub/true
 
27
    $ plainbox run -i cpu/scaling_test
28
28
 
29
29
.. note::
30
30
 
33
33
Running jobs related to a specific area
34
34
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
35
35
 
36
 
Plainbox has no concept of job categories but you can simulate that by
 
36
PlainBox has no concept of job categories but you can simulate that by
37
37
running all jobs that follow a specific naming pattern. For example, to run
38
38
all of the USB tests you can run the following command:
39
39
 
45
45
 
46
46
.. code-block:: bash
47
47
 
48
 
    plainbox dev special --list-jobs
 
48
    plainbox special --list-jobs
49
49
 
50
50
Running a white list
51
51
^^^^^^^^^^^^^^^^^^^^
52
52
 
53
 
To run a :term:`whitelist` pass the ``--whitelist`` or ``-w`` option.
 
53
To run a :term:`white list` pass the ``--whitelist`` or ``-w`` option.
54
54
 
55
55
For example, to run the default white list run:
56
56
 
57
57
.. code-block:: bash
58
58
 
59
 
    $ plainbox run -w /path/to/some/file.whitelist
60
 
 
61
 
Saving test results
62
 
^^^^^^^^^^^^^^^^^^^
63
 
 
64
 
Anything that Plainbox captures and stores during test execution can be
65
 
exported to a file using the exporter system. The two most commonly used
66
 
exporters are JSON (versatile and general) and XML (for internal Canonical use).
67
 
 
68
 
JSON Exporter
69
 
-------------
70
 
 
71
 
To generate a JSON file with all of the internally available data (for storage,
72
 
processing or other automation) you will need to pass three additional
73
 
arguments to ``plainbox run``:
74
 
 
75
 
#. ``--output-format=2013.com.canonical.plainbox::json``
76
 
#. ``--output-options=OPTION1,OPTION2`` where *OPTIONx* are option names.
77
 
#. ``--output-file=NAME`` where *NAME* is a file name.
78
 
 
79
 
Pass ``?`` to ``--output-options`` for a list of available options. Multiple
80
 
exporter options can be specified, separated with commas.
81
 
 
82
 
.. code-block:: bash
83
 
 
84
 
    $ plainbox run --whitelist=/path/to/some/file.whitelist --output-format=2013.com.canonical.plainbox::json --output-file=results.json
85
 
 
86
 
XML Exporter
87
 
------------
 
59
    $ plainbox run -w /usr/share/checkbox/data/whitelists/default.whitelist
 
60
 
 
61
Saving test results as XML
 
62
^^^^^^^^^^^^^^^^^^^^^^^^^^
88
63
 
89
64
To generate an XML file that can be sent to the :term:`certification website`
90
 
you need to pass two additional arguments to ``plainbox run``:
 
65
you need to pass two additional options:
91
66
 
92
 
#. ``--output-format=2013.com.canonical.plainbox::hexr``
93
 
#. ``--output-file=NAME`` where *NAME* is a file name
 
67
1. ``--output-format=xml``
 
68
2. ``--output-file=NAME`` where *NAME* is a file name
94
69
 
95
70
For example, to get the default certification tests ready to be submitted
96
71
run this command:
97
72
 
98
73
.. code-block:: bash
99
74
 
100
 
    $ plainbox run --whitelist=/path/to/some/file.whitelist --output-format=2013.com.canonical.plainbox::hexr --output-file=submission.xml
101
 
 
102
 
Other Exporters
103
 
---------------
104
 
 
105
 
You can discover the full list of known exporters at runtime, by passing ``?``
106
 
to ``--output-format``.
107
 
 
108
 
Custom Exporters
109
 
----------------
110
 
 
111
 
Exporters can be provided by third party packages. Exporters are very simple to
112
 
write. If you don't want to transform JSON to your preferred format, you can
113
 
copy the json exporter and use it as template for writing your own.
 
75
    $ plainbox run --whitelist=/usr/share/checkbox/data/whitelists/default.whitelist --output-format=xml --output-file=submission.xml
 
76
 
 
77
Running stable release update tests
 
78
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
79
 
 
80
PlainBox has special support for running stable release updates tests in an
 
81
automated manner. This runs all the jobs from the *sru.whitelist* and sends the
 
82
results to the certification website.
 
83
 
 
84
To run SRU tests you will need to know the so-called :term:`Secure ID` of the
 
85
device you are testing. Once you know that all you need to do is run:
 
86
 
 
87
.. code-block:: bash
 
88
 
 
89
    $ plainbox sru $secure_id submission.xml
 
90
 
 
91
The second argument, submission.xml, is a name of the fallback file that is
 
92
only created when sending the data to the certification website fails to work
 
93
for any reason.