xenial (1) plainbox.1.gz

Provided by: plainbox_0.25-1_all bug

NAME

       plainbox - toolkit for software and hardware integration testing

SYNOPSIS

          plainbox [--help] [--version] | [options] <command> ...

DESCRIPTION

       Undocumented

       Plainbox is a toolkit consisting of python3 library, development tools, documentation and examples. It is
       targeted at developers working on testing or certification applications and authors  creating  tests  for
       such applications.

OPTIONS

       Optional arguments:

       --version
              show program's version number and exit

       -v, --verbose
              be more verbose (same as --log-level=INFO)

       -D, --debug
              enable DEBUG messages on the root logger

       -C, --debug-console
              display DEBUG messages in the console

       -T, --trace
              enable DEBUG messages on the specified logger (can be used multiple times)

       -P, --pdb
              jump into pdb (python debugger) when a command crashes

       -I, --debug-interrupt
              crash on SIGINT/KeyboardInterrupt, useful with --pdb

PLAINBOX SUB-COMMANDS

       Plainbox  uses  a  number  of  sub-commands for performing specific operations.  Since it targets several
       different audiences commands are arranged into three parts: test authors, test users and core developers

   Test Users
          plainbox run
                 Run a test job. This is the swiss army knife of a swiss army knife. Has lots  of  options  that
                 affect job selection, execution and handling results.

          plainbox check-config
                 check and display plainbox configuration. While this command doesn't allow to edit any settings
                 it is very useful for figuring out what variables are available and which  configuration  files
                 are consulted.

   Test Authors
          plainbox startprovider
                 Create  a new provider (directory). This command allows test authors to create a new collection
                 (provider) of test definitions for Plainbox.

          plainbox dev script
                 Run the command from a job in a way it would  run  as  a  part  of  normal  run,  ignoring  all
                 dependencies / requirements and providing additional diagnostic messages.

          plainbox dev analyze
                 Analyze  how  selected  jobs would be executed. Takes almost the same arguments as plainbox run
                 does. Additional optional arguments control the type of analysis performed.

          plainbox dev parse
                 Parse stdin with the specified parser.  Plainbox  comes  with  a  system  for  plugging  parser
                 definitions so that shell programs (and developers) get access to structured data exported from
                 otherwise hard-to-parse output.

          plainbox dev list
                 List and describe various objects. Run without arguments to  see  all  the  high-level  objects
                 Plainbox knows about. Optional argument can restrict the list to objects of one kind.

   Core Developers
          plainbox self-test
                 Run  unit  and  integration  tests. Unit tests work also after installation so this command can
                 verify a local installation at any time.

          plainbox dev special
                 Access to special/internal commands.

          plainbox dev crash
                 Crash the application. Useful for testing the crash handler and crash log files.

          plainbox dev logtest
                 Log messages at various levels. Useful for testing the logging system.

FILES

       The following files and directories affect Plainbox:

   Created or written to
       $XDG_CACHE_HOME/plainbox/logs
              Plainbox keeps all internal log files in this directory. In particular the crash.log is  generated
              there  on  abnormal  termination.  If extended logging / tracing is enabled via --debug or --trace
              then debug.log will be created in this directory. The  files  are  generated  on  demand  and  are
              rotated if they grow too large. It is safe to remove them at any time.

       $XDG_CACHE_HOME/plainbox/sessions
              Plainbox  keeps  internal  state of all running and dormant (suspended or complete) sessions here.
              Each session is kept in a separate directory with a randomly generated name.  This  directory  may
              also  contain  a  symlink  last-session  that  points at one of those sessions. The symlink may be
              broken as a part of normal operation.

              Sessions may accumulate, in some cases, and they are  not  garbage  collected  at  this  time.  In
              general it is safe to remove sessions when Plainbox is not running.

   Looked up or read from
       /usr/local/share/plainbox-providers-1/*.provider
              System  wide,  locally  administered  directory  with provider definitions. See PROVIDERS for more
              information. Jobs defined here have access to plainbox-trusted-launcher(1) and  may  run  as  root
              without prompting (depending on configuration).

       /usr/share/plainbox-providers-1/*.provider
              Like  /usr/local/share/plainbox-providers-1 but maintained by the local package management system.
              This is where packaged providers add their definitions.

       $XDG_DATA_HOME/plainbox-providers-1/*.provider
              Per-user directory with provider definitions. This directory may be  used  to  install  additional
              test  definitions  that  are only available to a particular user. Jobs defined there will not have
              access to plainbox-trusted-launcher(1) and will use pkexec(1)  or  sudo(1)  to  run  as  root,  if
              needed.

              Typically  this  directory is used by test provider developers transparently by invoking manage.py
              develop (manage.py is the per-provider management script generated by plainbox startprovider)

       In addition, refer to the list of files mentioned by plainbox.conf (5)

ENVIRONMENT VARIABLES

       The following environment variables affect Plainbox:

       PROVIDERPATH
              Determines the lookup of test providers. Note that unless otherwise essential, it  is  recommended
              to   install  test  providers  into  one  of  the  aforementioned  directories  instead  of  using
              PROVIDERPATH.

              The default value is composed out of ':'-joined list of:

              • /usr/local/share/plainbox-providers-1/usr/share/plainbox-providers-1$XDG_DATA_HOME/plainbox-providers-1

       PLAINBOX_SESSION_REPOSITORY
              Alters the default location of the session storage repository. In practical terms  this  is  where
              all  the  test  sessions  are  stored  in  the  filesystem.   By  default  the  effective value is
              $XDG_CACHE_HOME/plainbox/sessions.

       PLAINBOX_LOCALE_DIR
              Alters the lookup directory for translation  catalogs.  When  unset  uses  system-wide  locations.
              Developers  working  with  a  local  copy  should  set  it  to  build/mo (after running ./setup.py
              build_i18n)

       PLAINBOX_I18N_MODE
              Alters behavior of the translation subsystem. This is only useful to developers that wish  to  see
              fake  translations  of  all  the  strings  marked as translatable. Available values include no-op,
              gettext (default), lorem-ipsum-XX where XX  is  the  language  code  of  the  faked  translations.
              Supported  faked  translations  are:  ar  (Arabic),  ch  (Chinese), he (Hebrew), jp (Japanese), kr
              (Korean), pl (Polish) and ru (Russian)

       PLAINBOX_DEBUG
              Setting this to a non-empty string enables early logging support.  This is somewhat equivalent  to
              running plainbox --debug except that it also affects code that runs before command line parsing is
              finished. One particular value that can be used here  is  "console".  It  enables  console  traces
              (similar to plainbox --debug-console command-line argument).

       PLAINBOX_LOG_LEVEL
              This  variable  is only inspected if PLAINBOX_DEBUG is not empty. It is equivalent to the plainbox
              --log-level= command-line argument. By default (assuming PLAINBOX_DEBUG is  set)  is  DEBUG  which
              turns on everything.

       PLAINBOX_TRACE.
              This  variable  is only inspected if PLAINBOX_DEBUG is not empty. It is equivalent to the plainbox
              --trace= command-line argument. Unlike the command line argument,  it  handles  a  comma-separated
              list of loggers to trace. By default it is empty.

SEE ALSO

       plainbox-run,   plainbox-session,   plainbox-check-config   plainbox-self-test,   plainbox-startprovider,
       plainbox-dev plainbox.conf

AUTHOR

       Zygmunt Krynicki & Checkbox Contributors

       2012-2014 Canonical Ltd