Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Understanding Junos Snapshot Administrator in Python Test Files

 

The Junos Snapshot Administrator in Python (jsnapy) test files define the details of what a snapshot contains. Test files, also known as test cases, are YAML-formatted files that are referenced from inside jsnapy configuration files. Configuration files are read as an argument to the jsnapy CLI command. Generally speaking, test files define what tests are included within the test case and the specific definitions for those tests.

Understanding the Structure of a Test File

There are only two sections to a test file: the tests_include list, and the details section. There is a details section for each test named in the include list. Test files begin with an include statement: tests_include:. The include statement denotes the beginning of a list of tests that are contained within the test case. Each test name in the list is preceded by a dash (-); for example, - test_name. You can name the tests whatever you want, except test names cannot include spaces or special characters. Valid test names include: check_interfaces_up, show_software_version, or test_bgp_neighbors.

Note

If the tests_include list does not exist in the test file, but there are tests defined in the details section, all tests detailed within the test file are run. You can skip the running of specific tests within a test file by leaving the test name off of the tests_include list.

The details section begins with the name of the test from the include list, followed by a colon; for example, check_interfaces_up:. The purpose of the details section is to provide all of the test criteria for the test case, including:

  • Junos OS CLI or RPC commands (one per test) that are executed on the device. The output of these commands forms the basis of the snapshot.

  • The Extensible Markup Path Language (XPath) that identifies the starting node in the Junos OS hierarchy from which the tests are run.

  • Test operators that help to analyze the output from the commands.

  • Info messages that are returned as the result of successful execution of the test operators.

  • Error messages that are returned as the result of failure of the test operators.

When using the get-config RPC command, you can filter for specific configuration information using the filter_xml: statement. As an example, the filter_xml: configuration/system/loginstatement causes the device to filter out all of the configuration elements except those in the Junos OS /system/login hierarchy. This statement only works on the specific RPC command get-config. For more information, see Example: Creating the Junos Snapshot Administrator in Python Test Files.

Elements of a Test File

Like the other YAML files used with jsnapy, test files are structured using key-value pairs. The keywords and values are separated by a colon (:).

For example rpc: get-config.

Table 1 shows the keys available for use in a jsnapy test file and describes each key.

Table 1: Test File Keywords and Descriptions

Keyword

Description

tests_include

This keyword denotes the beginning of a jsnapy test file and the beginning of the include statement. It is followed by a colon (:) and a carriage-return. Each element of the list that follows is the name of a test case, preceded by a space, a dash, and another space and must be on a line by itself. For example:

tests_include:
 - show_version
 - check_interface_state
 - return_bgp_neighbors

command

This keyword is used to specify what Junos OS command is run on the device by jsnapy. It is preceded by a space, a dash (-), and another space and followed immediately by a colon (:). For example:

- command: show version

rpc

This keyword is used to specify what Junos OS RPC command should be run on the device by jsnapy. It is preceded by a space, a dash (-), and another space and followed immediately by a colon (:). For example:

- rpc: get-software-version

format

This keyword is used to format the device output. Available options are: text and xml. When comparing output that is formatted as text, only the --diff operation is supported. The --check and --snapcheck operations do not work on text formatted snapshots.

kwargs

This keyword only works with RPC commands. It is ignored if the command keyword is used in the test case definition. The keyword is used to provide arguments to the rpc command being sent to the device; for example:

when using the get-interface-information rpc command, arguments like interface-name and media-type could be used to provide specific information about the interface.

item

This keyword denotes the beginning of a test definition. It is preceded by a space, a dash (-), and another space and followed immediately by a colon (:). For example:

- item:

This keyword also instructs jsnapy to match only the first node in the xpath.

iterate

This keyword denotes the beginning of a test definition. It is preceded by a space, a dash (-), and another space and followed immediately by a colon (:). For example:

- iterate:

This keyword also instructs jsnapy to continue to match all nodes in the xpath.

Note: A test definition can use either iterate or item. They cannot be used together.

xpath

This keyword denotes the path in the Junos OS hierarchy from which you want to start tests. It is preceded by two spaces and followed by a colon (:). For example:

  xpath:

The values used with this keyword are path syntax values. For example,

the /configuration/system/servicesxpath selects the [system services] portion of the Junos OS hierarchy.

id

This keyword denotes an XPATH expression relative to the node-set being iterated that specifies a unique data element that maps the first snapshot data item with the second snapshot data item. The keyword is followed immediately by a colon (:). It is possible to use single or multiple id keywords under the same iterate or item XPATH blocks.

tests

This keyword denotes the beginning of the test definition. It is followed by a colon. Tests are activated only when the --check and --snapcheck options are used. Tests are not performed when taking snapshots using the --snap option. See Junos Snapshot Administrator in Python Test Operators Summary for details about the available tests.

info

This keyword specifies what information is logged upon successful completion of the tests if the jsnapy logging level is set to debug. The information can use a jinja2 formatted template that pulls node values from the snapshot files. For example:

info: “Test successful! The admin status of the interface is <{{pre[’admin-status’]}}>.”

err

This keyword specifies what information will be logged upon failure of the test if the jsnapy logging level is set to debug. The information can use a jinja2 formatted template that pulls node values from the snapshot files. For example:

err: “Test Failed! The admin-status of the interface is <{{post[’admin-status’]}}>.”

pre

When used with jinja2 formatted variables in the info or err message sections, this keyword causes jsnapy to search for the named variable inside of the pre-change snapshot.

post

When used with jinja2 formatted templates in the info or err message sections, this keyword causes jsnapy to search for the named variable inside of the post-change snapshot.