PLAINBOX-DEV-ANALYZE(1)

NAME
plainbox-dev-analyze - analyze how seleted jobs would be executed

SYNOPSIS

        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]

DESCRIPTION

Analyze how selected jobs would be executed

The plainbox dev analyze command is a direct replacement for plainbox run that doesn't 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

The only exception to the rule above is the --run-local option. With that option all local jobs and their dependencies are started. This is technically required to correctly emulate the behavior of plainbox run that does so unconditionally. Still, local jobs can cause harm so don't run untrusted code this way (the author of this man page recalls one local job that ran sudo reboot to measure bootchart data)

  Report Types

Plainbox dev analyze 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.

  Dependency Report

This report shows if any of the jobs have missing dependencies. It almost never happens but the report is here for completeness.

  Interactivity Report

This report shows, for each job, if it is fully automatic or if it requires human interaction.

  Estimated Duration Report

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.

  Validation Report

This report shows if all of the selected jobs are valid. It is of lesser use now that we have provider-wide validation via ./manage.py validate

  Two Kinds of Job Lists

  Desired Job List

This list is displayed with the -S option. It contains the ordered sequence of jobs that are "desired" by the test operator to execute. This list contrasts with the so-called run list mentioned below.

  Run List

This list is displayed with the -R option. It contains the ordered sequence of jobs that should be executed to satisfy the desired list 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)

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.

OPTIONS

Optional arguments:

    -l, --run-local
        run all selected local jobs, required to see true data

    -L, --skip-local
        do not run local jobs

    -s, --print-stats
        print general job statistics

    -d, --print-dependency-report
        print dependency report

    -t, --print-interactivity-report
        print interactivity report

    -e, --print-estimated-duration-report
        print estimated duration report

    -v, --print-validation-report
        print validation report

    -r, --print-requirement-report
        print requirement report

    -E, --only-errors
        when coupled with -v, only problematic jobs will be listed

    -S, --print-desired-job-list
        print desired job list

    -R, --print-run-list
        print run list

    -T, --test-plan
        load the specified test plan

    -i, --include-pattern
        include jobs matching the given regular expression

    -x, --exclude-pattern
        exclude jobs matching the given regular expression

    -w, --whitelist
        load whitelist containing run patterns

SEE ALSO

plainbox-run

AUTHOR
Zygmunt Krynicki & Checkbox Contributors

COPYRIGHT
2012-2014 Canonical Ltd