Basic Usage¶
Currently Plainbox has no graphical user interface. To use it you need to use the command line.
Plainbox has built-in help system so running plainbox run --help will give you instant information about all the various arguments and options that are available. This document is not intended to replace that.
Running a specific job¶
Basically there is just one command that does everything we can do so far, that is plainbox run. It has a number of options that tell it which job to run and what to do with results.
To run a specific job pass it to the --include-pattern
or -i
option.
For example, to run one of the internal “smoke” test job:
$ plainbox run -i 2013.com.canonical.plainbox::stub/true
Note
The option -i
can be provided any number of times.
Running a white list¶
To run a whitelist pass the --whitelist
or -w
option.
For example, to run the default white list run:
$ plainbox run -w /path/to/some/file.whitelist
Saving test results¶
Anything that Plainbox captures and stores during test execution can be exported to a file using the exporter system. The two most commonly used exporters are JSON (versatile and general) and XML (for internal Canonical use).
JSON Exporter¶
To generate a JSON file with all of the internally available data (for storage,
processing or other automation) you will need to pass three additional
arguments to plainbox run
:
--output-format=2013.com.canonical.plainbox::json
--output-options=OPTION1,OPTION2
where OPTIONx are option names.--output-file=NAME
where NAME is a file name.
Pass ?
to --output-options
for a list of available options. Multiple
exporter options can be specified, separated with commas.
$ plainbox run --whitelist=/path/to/some/file.whitelist --output-format=2013.com.canonical.plainbox::json --output-file=results.json
XML Exporter¶
To generate an XML file that can be sent to the certification website
you need to pass two additional arguments to plainbox run
:
--output-format=2013.com.canonical.plainbox::hexr
--output-file=NAME
where NAME is a file name
For example, to get the default certification tests ready to be submitted run this command:
$ plainbox run --whitelist=/path/to/some/file.whitelist --output-format=2013.com.canonical.plainbox::hexr --output-file=submission.xml
Other Exporters¶
You can discover the full list of known exporters at runtime, by passing ?
to --output-format
.
Custom Exporters¶
Exporters can be provided by third party packages. Exporters are very simple to write. If you don’t want to transform JSON to your preferred format, you can copy the json exporter and use it as template for writing your own.