You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+32-23Lines changed: 32 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Introduction
4
4
5
-
The NetTowel Network Unit Testing System or "nuts" in short is the testing component of the NetTowel Project.
5
+
The NetTowel Network Unit Testing System or "nuts" in short is the testing component of the NetTowel Project, which is developed at the Institute of Networked Solutions in Rapperswil, Switzerland.
6
6
It draws on the concept of unit tests, known from the domain of programming, and applies it to the domain of networking.
7
7
8
8
One major difference between unit tests in programming and
@@ -14,18 +14,34 @@ pre-defined test cases. Such a single test case might be "can host A reach neigh
14
14
This is what nuts tries to achieve:
15
15
Apply test cases based on your pre-defined network topology to your actual network and have the tests confirm the correct state.
16
16
17
+
## Installation Instructions
18
+
19
+
### Using pip
20
+
21
+
Run `pip install nuts`
22
+
23
+
### Using poetry
24
+
25
+
Nuts uses [poetry](https://python-poetry.org/) as a dependency manager.
## How It Works: Test Bundles and Test Definitions
32
+
17
33
The project relies on the [pytest framework](https://docs.pytest.org/) to setup and execute the tests.
18
34
Nuts itself is written as a custom pytest plugin. In the background, [nornir](https://nornir.readthedocs.io/)
19
35
executes specific network tasks for the actual tests.
20
36
21
-
Additionally, nuts treats the test definition and the so-called test bundle as separate entities. The *test definition* is modeled as a custom `pytest.Class`, and a predefined set of test definitions can be found in the module `base_tests`. New test definitions can be added easily by the user of the plugin.
37
+
Nuts treats the test definition and the so-called test bundle as separate entities. The *test definition* is modeled as a custom `pytest.Class`, and a predefined set of test definitions can be found in the nuts module `base_tests`. New test definitions can be added easily by the user of the plugin.
22
38
23
39
The *test bundle* is a file that is parsed by pytest. The file provides data on the desired network state and describes which test definitions should be collected and executed by pytest.
24
40
The structure of the test bundle should enable people without in-depth python knowledge to add new test bundles or update existing ones to reflect changes in the network.
25
41
26
42
While the readme here is only a short overview, find the [documentation of nuts on readthedocs](https://nuts.readthedocs.io/en/latest/).
27
43
28
-
## Test bundle structure
44
+
###Test Bundle Structure
29
45
30
46
Currently only yaml files are supported as test bundles,
31
47
but other sources such as other file formats or database entries can be considered in later nuts versions.
@@ -42,7 +58,7 @@ Each test bundle contains the following structure:
42
58
```
43
59
`test_module`: The full path of the python module that contains the test class to be used.
44
60
This value is optional if the test class is registered in `index.py` of the pytest-nuts plugin.
45
-
Note that it can be relevant in which directory `pytest` is started if local test modules are used.
61
+
Note that it can be relevant in which directory `pytest` is started if local test modules are used. Using `test_modules` allows you to write your own test classes. **Note: We currently do not support self-written test modules, since upcoming refactorings might introduce breaking changes.**
46
62
47
63
`test_class`: The name of the python class which contains the tests that should be executed.
48
64
Note that currently every test in this class will be executed.
@@ -58,7 +74,7 @@ This allows the additional `max_drop` parameter in `test_execution`, since it is
58
74
59
75
`test_data`: Data that is used to parametrize the tests in the test class which have the `pytest.mark.nuts` annotation. It is additionally part of the `nuts_parameters` property.
60
76
61
-
### Examples
77
+
### Example: CDP Neighbors
62
78
Example of a test bundle for `TestNetmikoCdpNeighbors` which tests that `R1` is a CDP Neighbor of both `R2` and `R3`.
63
79
This example creates three different tests, one for each entry in the `test_data` list.
64
80
@@ -85,14 +101,7 @@ This example creates three different tests, one for each entry in the `test_data
85
101
...
86
102
```
87
103
88
-
## Manual installation instructions
89
-
Nuts uses [poetry](https://python-poetry.org/) as a dependency manager.
### How the Test Bundle Is Converted to a Pytest Test
96
105
97
106
When nuts is executed, pytest converts the test bundles (the yaml files) into tests. During test collection, the custom pytest marker `nuts` uses the data that has been defined in the test bundle mentioned above.
98
107
This annotation is a wrapper around the `pytest.mark.parametrize` annotation and allows the plugin to use the data entries from the test bundle. For each entry in the `test_data` section of the test bundle, the custom marker generates a single test case. To achieve this, the plugin transforms the entries into n-tuples, since `pytest.mark.parametrize` expects a list of n-tuples as input.
@@ -102,18 +111,16 @@ For each entry in `test_data` these fields are extracted and transformed to a tu
102
111
If any of these fields are not present in an entry of `test_data`, the corresponding test case will be skipped.
103
112
A second argument determines optional fields that can also be used in a test case as well - non-present values are passed into the function as `None`.
104
113
105
-
#### Example of a test class with custom marker
114
+
The following test-run of CDP neighbors for example checks the local port:
106
115
107
116
```python
108
-
@pytest.mark.usefixtures("check_nuts_result")# see below
This test-run of CDP neighbors checks the local port.
116
-
117
124
Before each test evaluation, the fixture `@pytest.mark.usefixtures("check_nuts_result")` checks the result of the network information that has been gathered by nornir in the background: It asserts that that no exception was thrown while doing so.
118
125
119
126
The required fields are `host`, `remote_host` and `local_port` - they must be present in the custom marker,
@@ -125,16 +132,18 @@ but also be provided as argument to the test method itself.
125
132
Each test module implements a context class to provide module-specific functionality to its tests. This context class is a `NutsContext` or a subclass of it.
126
133
This guarantees a consistent interface across all tests for test setup and execution.
127
134
Currently, the predefined test classes use [nornir](https://nornir.readthedocs.io/en/latest/) in order to communicate
128
-
with the network devices, therefore the test classes derive all from a more specific `NornirNutsContext`,
129
-
which provides a nornir instance and nornir-specific helpers.
135
+
with the network devices. Those test classes derive all from a more specific `NornirNutsContext`,
136
+
which provides a nornir instance and nornir-specific helpers. In the example above, it is a class called `CdpNeighborsContext` that derives from `NornirNutsContext`.
137
+
138
+
If you want to learn more how nuts works but do not have a running network in the background, there's a nuts showcase - an offline test class that displays the basic functionality of nuts. See the [tutorial](https://nuts.readthedocs.io/en/latest/tutorial/firststeps.html) for further information.
130
139
131
-
## Development
140
+
## Develop Your Own Test Classes
132
141
133
142
Nuts is essentially designed as a pytest-plugin and it is possible to add your own, self-written test classes.
134
-
A dev documentation on how to write your own test classes is planned for the future.
135
-
Until then, please read the regular [documentation of nuts](https://nuts.readthedocs.io/en/latest/) on how to use it.
143
+
A dev documentation on how to write your own test classes is planned for a future release.
144
+
Still, it is possible to write your own test classes nevertheless, even if we cannot guarantee that upcoming planned refactorings do not introduce breaking changes.
136
145
137
146
# Thanks
138
147
139
148
*[Matthias Gabriel](https://github.com/MatthiasGabriel), who laid the foundations of nuts.
140
-
*[Florian Bruhin](https://github.com/The-Compiler) for invaluable feedback.
149
+
*[Florian Bruhin (The Compiler)](https://github.com/The-Compiler) for invaluable feedback and advice.
Copy file name to clipboardExpand all lines: docs/source/index.rst
+22-24Lines changed: 22 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,41 +6,40 @@ Documentation of NUTS
6
6
Introduction
7
7
------------
8
8
9
-
The NetTowel Network Unit Testing System or "NUTS" for short is the
10
-
testing component of the NetTowel Project, which is developed at the Institute of Networked Solutions in Rapperswil, Switzerland.
11
-
NUTS draws on the concept of unit tests, known from the domain of
12
-
software development, and applies it to the domain of networking.
13
-
14
-
One major difference between unit tests in software development and
15
-
network tests is the definition of a test.
16
-
In software development, unit tests normally focus on testing edge cases,
17
-
since the amount of non-edge cases is not definable.
18
-
In the network testing domain, tests are less about edge cases, but more about testing network functionalities with pre-defined test cases. Such a single test case might be "can host A
19
-
reach neighbors X, Y, Z?" or "has host A all BGP neighbors configured correctly?" on many different devices.
20
-
21
-
This is what NUTS tries to achieve:
22
-
Use pre-defined test cases together with your network topology, apply this to your actual network and have the tests confirm that the network has the expected functionalities.
23
-
24
-
How NUTS works
9
+
The NetTowel Network Unit Testing System or "nuts" in short is the testing component of the NetTowel Project, which is developed at the Institute of Networked Solutions in Rapperswil, Switzerland.
10
+
It draws on the concept of unit tests, known from the domain of programming, and applies it to the domain of networking.
11
+
12
+
One major difference between unit tests in programming and
13
+
network tests is the definition of what a test actually is.
14
+
In programming, unit tests normally focus on testing edge cases,
15
+
since the amount of non-edge cases is not definable.
16
+
In the network testing domain, tests are less about edge cases, but more about testing existing network states with
17
+
pre-defined test cases. Such a single test case might be "can host A reach neighbors X, Y, Z?" on many different devices.
18
+
This is what nuts tries to achieve:
19
+
Apply test cases based on your pre-defined network topology to your actual network and have the tests confirm the correct state.
20
+
21
+
How nuts works
25
22
--------------
26
23
27
-
In order to run NUTS, two components are required:
24
+
In order to run nuts, two components are required:
28
25
29
26
#. **Inventory of the network**. Currently, these are YAML-files in the form of a `nornir inventory <https://nornir.readthedocs.io/en/latest/tutorial/inventory.html>`__. They contain all details of your network, such as hosts, login-information and other configuration.
30
27
31
28
#. **Test bundles** in the form of YAML-files that specify the actual tests. A test bundle is a series of tests that are logically related to each other. Each test bundle is structured in a similar way, but has specific fields tailored to the test bundle. Some field values in a test bundle are directly related to your inventory.
32
29
33
-
Head over to the :doc:`Usage section <tutorial/firststeps>` to see how those two components are structured and how you get NUTS up and running.
30
+
Head over to the :doc:`Usage section <tutorial/firststeps>` to see how those two components are structured and how you get nuts up and running.
34
31
35
32
The project relies on the `pytest framework <https://docs.pytest.org/>`__ to setup and execute the
36
-
tests. NUTS itself is written as a custom pytest plugin. In the background, `nornir <https://nornir.readthedocs.io/>`__ executes specific network tasks for the actual tests.
33
+
tests. Nuts itself is written as a custom pytest plugin. In the background, `nornir <https://nornir.readthedocs.io/>`__ executes specific network tasks for the actual tests.
37
34
38
-
Pytest reads in the test bundle (2.) and transforms it into test runs. In the background, nornir uses the network information provided in the inventory (1.), queries the network based on the specific test bundle and passes the results of those queries to pytest. Pytest then evaluates if the expectations defined in the test bundle match those results.
35
+
Pytest reads in the test bundle (step 2 above) and transforms it into test runs. In the background, nornir uses the network information provided in the inventory (step 1 above), queries the network based on the specific test bundle and passes the results of those queries to pytest. Pytest then evaluates if the expectations defined in the test bundle match those results.
39
36
40
-
Enhance NUTS
37
+
Enhance nuts
41
38
------------
42
-
Since NUTS is written as a pytest plugin and in python, you can customize it yourself and write your own test classes. Please see the :doc:`development section <dev/index>` to see how NUTS is structured and how to write your own test classes.
39
+
Nuts is written in python and designed as a pytest plugin. It provides some base tests described in :doc:`the section about all test bundles <testbundles/alltestbundles>`, but since it's a plugin, you can write your own, self-written test classes for your custom tests.
40
+
A dev documentation on how to write your own test classes is planned for a future release.
43
41
42
+
We do not support self-written tests at the moment, since planned refactorings might introduce breaking changes. Still, you can already write your own test classes - see the ``nuts/base_tests`` folder in the code repository to learn how test classes are written.
Copy file name to clipboardExpand all lines: docs/source/testbundles/alltestbundles.rst
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ A test bundle contains one ore more tests that are logically related to each oth
5
5
6
6
This section contains all test bundles which have been implemented in NUTS, you can incorporate them in your own bundles. They can be executed with the command ``$ pytest <test>.yaml`` from your project root.
7
7
8
-
Note that you need an inventory for the tests to work. Please see :doc:`First Steps with NUTS <../tutorial/firststeps>` for more information.
8
+
Note that you need an inventory of network devices for the tests to work. Please see :doc:`First Steps with NUTS <../tutorial/firststeps>` for more information.
9
9
10
10
In some test bundles you can directly pass arguments to the nornir task, i.e. the network query that is executed in the background. For those test bundles we indicate the specific task which is used to query the devices, so that you can look up all available arguments.
0 commit comments