tests¶

nornir_tests.plugins.tests.callback(callback: Callable[[…], Any], fail_task: bool = False) → nornir.core.task.Result¶

Test decorator using custom callback

This wrapper can be used to test a task result using a custom callback. The callback has the nornir Result, the Task which includes a host attribute that can be used for verifications, and the test record. To fail the test set test.passed to False and populate the CallbackRecord with whatever is desired.

Parameters

callback (Callable) – Callback function
fail_task (bool, optional) – Determines whether test failure results causes setting result failure.

Example:

def my_callback(result, test, task):
    if result.result['hostname'] != task.host.hostname:
        test.passed = False
        test.custom = "Hostname did not match inventory"

results = nr.run(
    wrap_task(napalm_get), getters=['system']
    tests=[
        callback(my_callback, fail_task=True)
    ]
)

This would fail the task and thus the host would end up in failed_hosts despite the fact that napalm_get had no issues. It would fail due to the fact that the callback was not ok with what was returned.

This is just another way to deal with validations in Nornir and the primary advantage is that it could potentially be chained with another test such as until to wait for a particular condition. It also provides a succinct way to display the logic of the validation into results without requiring another task or printing directly.

nornir_tests.plugins.tests.jpath(assertion: str = 'is_equal_to', value: Any = None, path: str = '', one_of: bool = False, result_attr: str = 'result', host_data: str = '', fail_task: bool = False) → nornir.core.task.Result¶

Test decorator using jsonpath

This test is based off of the jsonpath_ng implementation. The path and host_data attributes both use the jsonpath syntax documented there. The host_data is a jsonpath starting from the task.host.data dictionary.

The operation is based on the assertpy implementation. Any method available to assert_py.assert_that should be usable. If the assert_that assertion requires an argument to compare against then that should come from either the value argument or the value at the jsonpath match of host_data.

Parameters

path (str, optional) – jsonpath path.
value (str, optional) – Data to use for comparison.
result_attr (str, optional) – Attribute to check in results (ie. stdout, result).
assertion (str, optional) – Any method of assertpy.assert_that object.
one_of (bool, optional) – When found values is > 1, allow one match to pass otherwise all returned must match.
host_data (str, optional) – jsonpath starting at task.host.data to use for comparison.
fail_task (bool, optional) – Determines whether test failure results causes setting result failure.

Example:

results = nr.run(
    wrap_task(napalm_get), getters=['system']
    tests=[
        jpath(path="$.sw-version", assertion='is_in", value=['8.1', '9.1'], fail_task=True)
        jpath(path="$.hostname", host_data="$.fqdn", fail_task=True)
    ]
)

nornir_tests.plugins.tests.loop(values: List[Any], placeholder: Any, reset_conns: bool = False) → nornir.core.task.Result¶

Test decorator for looping

Parameters

values (List[Any]) – Values to loop through.
placeholder (Any) – Values are placed into placeholder for each iteration.
reset_conns (bool, optional) – [description]. Reset connections after each loop.

nornir_tests.plugins.tests.regexp(assertion: str = 'is_equal_to', value: Any = None, regexp: str = '', one_of: bool = False, result_attr: str = 'result', host_data: str = '', fail_task: bool = False) → nornir.core.task.Result¶

Test decorator using re module

This test is based off the standard re module.

The operation is based on the assertpy implementation. Any method available to assert_py.assert_that should be usable. If the assert_that assertion requires an argument to compare against then that should come from either the value argument or the value at the regexp match of host_data.

Parameters

regexp (str, optional) – regular expression.
value (str, optional) – Data to use for comparison.
result_attr (str, optional) – Attribute to check in results (ie. stdout, result).
assertion (str, optional) – Any method of assertpy.assert_that object.
one_of (bool, optional) – When found values is > 1, allow one match to pass otherwise all returned must match.
host_data (str, optional) – jsonpath starting at task.host.data to use for comparison.
fail_task (bool, optional) – Determines whether test failure results causes setting result failure.

nornir_tests.plugins.tests.timing(min_run_time: int = 0, max_run_time: int = 9223372036854775807, t0: float = - 1, t1: float = - 1, run_time: float = - 1, fail_task: bool = False) → nornir.core.task.Result¶

Test decorator for timing

Parameters

fail_task (bool, optional) – Determines whether test failure results causes setting result failure.
min_run_time (int, optional) – Required minimum runtime.
max_run_time (int, optional) – Required maximum runtime.

nornir_tests.plugins.tests.until(initial_delay: float = 0, retries: int = 0, delay: float = 0, reset_conns: bool = False, t0: float = - 1, t1: float = - 1, run_time: float = - 1, fail_task: bool = False) → nornir.core.task.Result¶

Test decorator for until This decorator allows retrying a task multiple times

Parameters

initial_delay (float, optional) – Time in seconds to wait for first attempt.
retries (int, optional) – Number of times to retry.
delay (float, optional) – Time to wait in between retries in seconds.
reset_conns (bool, optional) – Reset connections in between retries.
fail_task (bool, optional) – Determines whether test failure results causes setting result failure.

nornir_tests.plugins.tests.xpath(assertion: str = 'is_equal_to', value: Any = None, xpath: str = '', attrib: str = '', text: bool = False, one_of: bool = False, result_attr: str = 'result', host_data: str = '', fail_task: bool = False) → nornir.core.task.Result¶

Test decorator using lxml

This test is based off of the lxml implementation.

The operation is based on the assertpy implementation. Any method available to assert_py.assert_that should be usable. If the assert_that assertion requires an argument to compare against then that should come from either the value argument or the value at the jsonpath match of host_data.

Parameters

xpath (str, optional) – xpath locator.
value (str, optional) – value for comparison can be empty but not usual.
host_data (str, optional) – jsonpath to get value from task.host.data.
one_of (bool, optional) – When found values is > 1, allow one match to pass otherwise all returned must match.
result_attr (str, optional) – Attribute to check in results (ie. stdout, result).
text (bool, optional) – compare text value ie. <element>text</element>.
attrib (str, optional) – compare attribute value ie. <element @attrib=’whatever’>.
fail_task (bool, optional) – Determines whether test failure results causes setting result failure.

Example:

nr.run(
    wrap_task(napalm_get), getters=['config'],
    tests=[
        xpath(xpath='.//ip-address', one_of=True, host_data='$..ethernet1-1', text=True)
    ]
)

@xpath(xpath='.//interfaces', value='ethernet1/1', attrib='name', one_of=True)
def check_ethernet11(task):
    return napalm_get(task, getters=['config'])

nr.run(check_ethernet11)