Netpicker

Netpicker test rule syntax

Netpicker allows you to create custom rules (Python unit tests using pytest) to test your network devices. This guide outlines how to write these rules.

Creating a Rule

A rule in Netpicker is defined as a Python function decorated with @low, @medium or @high, specifying its severity and metadata. Here’s the basic structure:

@low(
    name='rule_name',
    platform=['platform_name'],
    commands=dict(show_interfaces='show interfaces'),
    device_tags=['device_tag1', 'device_tag2']
)
def rule_name(configuration, commands, device, devices):
    assert 'keyword' in configuration

Options in the Rule decorator

  • Severity: Each rule must be categorized with a severity level as decorator name, which can be high, medium, or low.
  • Rule Name: The function name (rule_name) must match the name parameter within the decorator. Rule names should start with rule_, followed by characters that aren’t numbers, spaces, or special symbols.
  • Platform Compatibility: The platform parameter should list one or more Netmiko platforms that the rule applies to (e.g., cisco_ios, juniper, ciena_saos).
  • Command Execution (optional): In the commands dictionary, define command names and their corresponding CLI commands. Prefer using non-configurational (show) commands to avoid unintended device behavior.
  • Device Tagging (optional): The device_tags array can be used to restrict the rule to devices with specific tags, facilitating targeted validations.

Inside the Rule function

Your rule function receives several parameters, giving you access to device configurations and other attributes:

  • configuration: A string containing the full device configuration.
  • configuration.lines: A list of strings of the configuration.
  • commands: A dictionary with the outputs of the executed commands, keyed by your defined command names. Use the dot notation to access them.
  • device: An object representing the current device, offering attributes like name, ip_address, platform, and tags.
  • devices: A collection of device objects that share the same tags specified in device_tags. Only applicable when device_tags are used in the decorator.
  • device.cli() method: Executes a given command in real-time on the device and returns the output. Use this function for executing additional commands if real-time data is necessary.