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 com.canonical.plainbox::stub/true


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 three most commonly used exporters are tar.xz, html and xlsx.

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:

  1. --output-format=com.canonical.plainbox::json
  2. --output-options=OPTION1,OPTION2 where OPTIONx are option names.
  3. --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=com.canonical.plainbox::json --output-file=results.json

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.

comments powered by Disqus