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.
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.
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
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).
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:
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=json --output-file=results.json
To generate an XML file that can be sent to the certification website you need to pass two additional arguments to plainbox run:
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=xml --output-file=submission.xml
You can discover the full list of known exporters at runtime, by passing ? to --output-format.
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.