.\" Man page generated from reStructuredText.
.
.TH "PLAINBOX-DEV-ANALYZE" "1" "January 05, 2016" "0.25" "Plainbox"
.SH NAME
plainbox-dev-analyze \- analyze how seleted jobs would be executed
.
.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 dev analyze [\-h] [\-l | \-L] [\-s] [\-d] [\-t] [\-e] [\-v] [\-r] [\-E] [\-S]
                     [\-R] [\-T TEST\-PLAN\-ID] [\-i PATTERN] [\-x PATTERN]
                     [\-w WHITELIST]
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Analyze how selected jobs would be executed
.sp
The \fBplainbox dev analyze\fP command is a direct replacement for \fBplainbox
run\fP that doesn\(aqt really run most of the jobs. Instead it offers a set of
reports that can be enabled (confusingly, by default no reports are enabled
and the command prints nothing at all) to inspect certain aspects of the
hypothetical session
.sp
The only exception to the rule above is the \fB\-\-run\-local\fP option. With that
option all local jobs and their dependencies \fIare\fP started. This is
technically required to correctly emulate the behavior of \fBplainbox run\fP
that does so unconditionally. Still, local jobs can cause harm so don\(aqt run
untrusted code this way (the author of this man page recalls one local job
that ran \fBsudo reboot\fP to measure bootchart data)
.SS Report Types
.sp
Plainbox \fBdev analyze\fP command offers a number of reports that can be
selected with their respective command line options. By default, no reports
are enabled which may be a little bit confusing but all options can be
enabled at the same time.
.SS Dependency Report
.sp
This report shows if any of the jobs have missing dependencies. It almost
never happens but the report is here for completeness.
.SS Interactivity Report
.sp
This report shows, for each job, if it is fully automatic or if it requires
human interaction.
.SS Estimated Duration Report
.sp
This report shows if Plainbox would be able to accurately estimate the
duration of the session. It shows details for both fully automatic and
interactive jobs.
.SS Validation Report
.sp
This report shows if all of the selected jobs are valid. It is of lesser
use now that we have provider\-wide validation via \fB\&./manage.py validate\fP
.SS Two Kinds of Job Lists
.SS Desired Job List
.sp
This list is displayed with the \fB\-S\fP option. It contains the ordered
sequence of jobs that are "desired" by the test operator to execute.  This
list contrasts with the so\-called \fIrun list\fP mentioned below.
.SS Run List
.sp
This list is displayed with the \fB\-R\fP option. It contains the ordered
sequence of jobs that should be executed to satisfy the \fIdesired list\fP
mentioned above. It is always a superset of the desired job list and almost
always includes additional jobs (such as resource jobs and other
dependencies)
.sp
The run list is of great importance. Most of the time the test operator will
see tests in precisely this order. The only exception is that some test
applications choose to pre\-run local jobs. Still, if your job ordering is
wrong in any way, inspecting the run list is the best way to debug the
problem.
.SH OPTIONS
.sp

\fBOptional arguments:\fP
.PP
.INDENT 0.0
.TP
.B \-l\fP,\fB  \-\-run\-local
run all selected local jobs, required to see true data
.TP
.B \-L\fP,\fB  \-\-skip\-local
do not run local jobs
.TP
.B \-s\fP,\fB  \-\-print\-stats
print general job statistics
.TP
.B \-d\fP,\fB  \-\-print\-dependency\-report
print dependency report
.TP
.B \-t\fP,\fB  \-\-print\-interactivity\-report
print interactivity report
.TP
.B \-e\fP,\fB  \-\-print\-estimated\-duration\-report
print estimated duration report
.TP
.B \-v\fP,\fB  \-\-print\-validation\-report
print validation report
.TP
.B \-r\fP,\fB  \-\-print\-requirement\-report
print requirement report
.TP
.B \-E\fP,\fB  \-\-only\-errors
when coupled with \-v, only problematic jobs will be listed
.TP
.B \-S\fP,\fB  \-\-print\-desired\-job\-list
print desired job list
.TP
.B \-R\fP,\fB  \-\-print\-run\-list
print run list
.TP
.B \-T\fP,\fB  \-\-test\-plan
load the specified test plan
.TP
.B \-i\fP,\fB  \-\-include\-pattern
include jobs matching the given regular expression
.TP
.B \-x\fP,\fB  \-\-exclude\-pattern
exclude jobs matching the given regular expression
.TP
.B \-w\fP,\fB  \-\-whitelist
load whitelist containing run patterns
.UNINDENT
.SH SEE ALSO
.sp
\fBplainbox\-run\fP
.SH AUTHOR
Zygmunt Krynicki & Checkbox Contributors
.SH COPYRIGHT
2012-2014 Canonical Ltd
.\" Generated by docutils manpage writer.
.