.\" Man page generated from reStructuredText. . .TH "PLAINBOX" "1" "January 05, 2016" "0.25" "Plainbox" .SH NAME plainbox \- toolkit for software and hardware integration testing . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C plainbox [\-\-help] [\-\-version] | [options] ... .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp Undocumented .sp 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. .SH OPTIONS .sp \fBOptional arguments:\fP .PP .INDENT 0.0 .TP .B \-\-version show program\(aqs version number and exit .TP .B \-v\fP,\fB \-\-verbose be more verbose (same as \-\-log\-level=INFO) .TP .B \-D\fP,\fB \-\-debug enable DEBUG messages on the root logger .TP .B \-C\fP,\fB \-\-debug\-console display DEBUG messages in the console .TP .B \-T\fP,\fB \-\-trace enable DEBUG messages on the specified logger (can be used multiple times) .TP .B \-P\fP,\fB \-\-pdb jump into pdb (python debugger) when a command crashes .TP .B \-I\fP,\fB \-\-debug\-interrupt crash on SIGINT/KeyboardInterrupt, useful with \-\-pdb .UNINDENT .SH PLAINBOX SUB-COMMANDS .sp 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 .SS Test Users .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B 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. .TP .B plainbox check\-config check and display plainbox configuration. While this command doesn\(aqt allow to edit any settings it is very useful for figuring out what variables are available and which configuration files are consulted. .UNINDENT .UNINDENT .UNINDENT .SS Test Authors .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B plainbox startprovider Create a new provider (directory). This command allows test authors to create a new collection (provider) of test definitions for Plainbox. .TP .B 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. .TP .B plainbox dev analyze Analyze how selected jobs would be executed. Takes almost the same arguments as \fBplainbox run\fP does. Additional optional arguments control the type of analysis performed. .TP .B 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. .TP .B 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. .UNINDENT .UNINDENT .UNINDENT .SS Core Developers .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B 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. .TP .B plainbox dev special Access to special/internal commands. .TP .B plainbox dev crash Crash the application. Useful for testing the crash handler and crash log files. .TP .B plainbox dev logtest Log messages at various levels. Useful for testing the logging system. .UNINDENT .UNINDENT .UNINDENT .SH FILES .sp The following files and directories affect Plainbox: .SS Created or written to .INDENT 0.0 .TP .B \fB$XDG_CACHE_HOME/plainbox/logs\fP Plainbox keeps all internal log files in this directory. In particular the \fBcrash.log\fP is generated there on abnormal termination. If extended logging / tracing is enabled via \fB\-\-debug\fP or \fB\-\-trace\fP then \fBdebug.log\fP 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. .TP .B \fB$XDG_CACHE_HOME/plainbox/sessions\fP 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 \fBlast\-session\fP that points at one of those sessions. The symlink may be broken as a part of normal operation. .sp 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. .UNINDENT .SS Looked up or read from .INDENT 0.0 .TP .B \fB/usr/local/share/plainbox\-providers\-1/*.provider\fP System wide, locally administered directory with provider definitions. See PROVIDERS for more information. Jobs defined here have access to \fBplainbox\-trusted\-launcher(1)\fP and may run as root without prompting (depending on configuration). .TP .B \fB/usr/share/plainbox\-providers\-1/*.provider\fP Like \fB/usr/local/share/plainbox\-providers\-1\fP but maintained by the local package management system. This is where packaged providers add their definitions. .TP .B \fB$XDG_DATA_HOME/plainbox\-providers\-1/*.provider\fP 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 \fBplainbox\-trusted\-launcher(1)\fP and will use \fBpkexec(1)\fP or \fBsudo(1)\fP to run as root, if needed. .sp Typically this directory is used by test provider developers transparently by invoking \fBmanage.py develop\fP (manage.py is the per\-provider management script generated by \fBplainbox startprovider\fP) .UNINDENT .sp In addition, refer to the list of files mentioned by \fBplainbox.conf\fP (5) .SH ENVIRONMENT VARIABLES .sp The following environment variables affect Plainbox: .INDENT 0.0 .TP .B \fBPROVIDERPATH\fP 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. .sp The default value is composed out of \(aq:\(aq\-joined list of: .INDENT 7.0 .IP \(bu 2 \fB/usr/local/share/plainbox\-providers\-1\fP .IP \(bu 2 \fB/usr/share/plainbox\-providers\-1\fP .IP \(bu 2 \fB$XDG_DATA_HOME/plainbox\-providers\-1\fP .UNINDENT .TP .B \fBPLAINBOX_SESSION_REPOSITORY\fP 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 \fB$XDG_CACHE_HOME/plainbox/sessions\fP\&. .TP .B \fBPLAINBOX_LOCALE_DIR\fP Alters the lookup directory for translation catalogs. When unset uses system\-wide locations. Developers working with a local copy should set it to \fBbuild/mo\fP (after running \fB\&./setup.py build_i18n\fP) .TP .B \fBPLAINBOX_I18N_MODE\fP 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 \fBno\-op\fP, \fBgettext\fP (default), \fBlorem\-ipsum\-XX\fP where \fBXX\fP is the language code of the faked translations. Supported faked translations are: \fBar\fP (Arabic), \fBch\fP (Chinese), \fBhe\fP (Hebrew), \fBjp\fP (Japanese), \fBkr\fP (Korean), \fBpl\fP (Polish) and \fBru\fP (Russian) .TP .B \fBPLAINBOX_DEBUG\fP Setting this to a non\-empty string enables early logging support. This is somewhat equivalent to running \fBplainbox \-\-debug\fP 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 \fBplainbox \-\-debug\-console\fP command\-line argument). .TP .B \fBPLAINBOX_LOG_LEVEL\fP This variable is only inspected if \fBPLAINBOX_DEBUG\fP is not empty. It is equivalent to the \fBplainbox \-\-log\-level=\fP command\-line argument. By default (assuming \fBPLAINBOX_DEBUG\fP is set) is \fBDEBUG\fP which turns on everything. .TP .B \fBPLAINBOX_TRACE\fP\&. This variable is only inspected if \fBPLAINBOX_DEBUG\fP is not empty. It is equivalent to the \fBplainbox \-\-trace=\fP command\-line argument. Unlike the command line argument, it handles a comma\-separated list of loggers to trace. By default it is empty. .UNINDENT .SH SEE ALSO .sp \fBplainbox\-run\fP, \fBplainbox\-session\fP, \fBplainbox\-check\-config\fP \fBplainbox\-self\-test\fP, \fBplainbox\-startprovider\fP, \fBplainbox\-dev\fP \fBplainbox.conf\fP .SH AUTHOR Zygmunt Krynicki & Checkbox Contributors .SH COPYRIGHT 2012-2014 Canonical Ltd .\" Generated by docutils manpage writer. .