Introduction¶

The pyATS Manifest is a file with YAML syntax describing how and where to execute a script. It is intended to formally describe the execution of a single script, the runtime environment, script arguments and profile which includes the test topology and related parameters.

A script can be executed via the manifest using the pyats run manifest command. Manifest files use the file extension .tem which stands for Test Execution Manifest.

Command line execution examples:

$ pyats run manifest job.tem
$ pyats run manifest job.tem --profile sanity

Command line manifest validation:

$ pyats validate manifest job.tem

The manifest defines the script execution arguments, runtime environment and the profile(s) that define environment specific settings and arguments. Profiles allow the same script to be run against multiple environments or run with different input parameters, e.g. local testbed, orchestrated testbed, production environment, different scaling numbers, or purposes like regression runs. Each profile can have its own specific script arguments and runtime specific settings.

Warning

Passing the job filename as an argument is not supported. See note below.

Note

The associated script file that the manifest refers to is inferred based on the manifest filename with the extension py. E.g. the script filename for a manifest with filename of job.tem is job.py in the same directory as the manifest file.

Script types¶

The manifest defines a type for the script that is associated with the manifest. Currently, the supported types for the manifest are:

easypy

Only supported script types have an execution runtime that allows the manifest to execute the script.

Script arguments¶

One of the primary definitions in the manifest is the arguments key in the manifest.

The arguments are defined as a set of key value pairs to be used as execution options. These arguments are translated to shell command arguments for script execution.

Arguments defined for the script can be superseded by arguments defined in a profile. Any arguments specified on the command line will override arguments defined in the profile.

Arguments are transformed into a command line argument string by combining the script arguments, profile arguments and command line arguments and translating those using below rules.

The transformation of arguments is done in steps:

Arguments are translated from command line, manifest script arguments and profile arguments into internal argument structures

Internal argument structures are combined using the priority: command line > profile > script.

Internal argument structure is translated to the command line argument string

The internal argument structure is translated to the command line argument string using the following rules:

Arguments that do not start with - are assumed to be double dash arguments and -- will be prepended to the key in the command line argument string.

Arguments may explicitly define dash syntax, e.g "-key": value

Argument values are quoted using double quotes, e.g. val1 will translate to "val1"

Arguments specified as a list will translate to --key "val1" "val2"

If the value is *N, repeat the argument key N number of times (e.g. "-v": "*3" translates to -v -v -v)

If the value is a boolean, leave out the value and only add the key to the argument string, e.g. flag: True translates to --flag. Note: if the boolean needs to be explicitly added to the argument string, the value must be explicitly specified as a string, e.g. key: "True" (not as a boolean value). See below for overriding boolean arguments.

If the meta argument is used on the command line, it will be prepended as an additional meta argument.

For example, the script arguments defined in the manifest could look like this:

arguments:
    mail-html: True
    configuration: easypy_config.yaml

profile:
    local:
        arguments:
            testbed-file: testbed.yaml

The arguments will be combined from the profile arguments and script arguments and translated to command arguments for execution. Adding command line arguments will add or override these.

For example running the manifest execution with the above arguments and adding the testbed-file argument on the command line will override the profile argument.

$ pyats validate manifest job.tem --profile local --testbed-file testbed2.yaml

Meta argument handling

If the meta argument is used on the command line, it will be prepended as an additional meta argument. Note, the value for the meta argument provided via a profile argument will override the default value (same as for any other argument).

arguments:
    meta: key1=value1

$ pyats validate manifest job.tem --meta key2=value2

The above will result in the following command line arguments to be used:

pyats run job job.py --meta key2=value2 --meta key1=value1

Overriding boolean arguments

You can override boolean arguments by specifying the boolean string value after the argument on the command line, i.e. "False" or "True".

With below example, the no-mail: True argument specified in the manifest can be overriden by specifying the argument on the manifest command line with value False. This combination will result in the --no-mail argument not to be added to the pyats run job command.

arguments:
    no-mail: True

$ pyats validate manifest job.tem --no-mail False

runtimes¶

The manifest can define zero or more runtime environments that can be used to execute the script. Runtimes are defined as named entries under the runtimes key in the manifest.

A runtime environment is used to execute the script and provides the shell environment and related libraries to be able to execute the script. If no runtime environment is defined, it is assumed the script is intended to run in the ‘current’ system environment.

The supported runtime types are:

system

virtualenv

profiles¶

The manifest can define zero or more profiles that contain environment specific settings and arguments. Profiles are defined as named entries under the profiles key in the manifest.

The arguments defined in the profile override the arguments specified for the script. Profiles specify a runtime to be used to execute the script and any additional settings relevant for that specific environment and runtime combination.

Examples¶

Minimal manifest to run a easypy job script using the ‘system’ runtime.

version: 1

type: easypy

arguments:
    configuration: easypy_config.yaml
    mail-html: True

Manifest with runtime and profile.

version: 1

type: easypy

runtimes:
    venv:
        type: virtualenv
        source:
            - /var/pyenv/venv/bin/activate
        environment:
            PYTHONPATH: /var/pyenv/libs
            TEST: "%ENV{VARNAME}"

arguments:
    configuration: easypy_config.yaml
    mail-html: True
    devices:
    - rtr1
    - rtr2

profiles:
    local:
        description: |
            Local run using virtual environment, send plain text email
        runtime: venv
        arguments:
            mail-html: False
            testbed-file: testbed.yaml