Merge branch 'master' into 58-write-wrapper-so-that-path-fspath-deprecation-warning-in-pytest-is-not-triggered

# Conflicts:
#	nuts/yamlloader.py
#	poetry.lock

Author: bytinbit

.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,37 @@
+# https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+# https://www.ianwootten.co.uk/2020/10/23/publishing-to-pypi-using-github-actions/
+name: Publish nuts to PyPI and release on GitHub
+on: [push]
+jobs:
+  build-and-publish-to-pypi:
+    if: startsWith(github.ref, 'refs/tags')
+    name: Build and publish nuts to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install poetry
+        run: pip install poetry
+      - name: Configure API token
+        run: poetry config pypi-token.pypi "${{ secrets.PYPI_API_TOKEN }}"
+      - name: Build and then publish nuts to PyPI
+        run: poetry publish --build
+  relase-on-github:
+    if: startsWith(github.ref, 'refs/tags')
+    name: Release on GitHub
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set tag value
+        id: tag-val
+        run: echo ::set-output name=SOURCE_TAG::${GITHUB_REF#refs/tags/}
+      - name: Release on Github
+        uses: softprops/action-gh-release@v1
+        with:
+          body_path: release_notes/${{ steps.tag-val.outputs.SOURCE_TAG }}.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: INSRapperswil/nuts

.gitignore

@@ -11,3 +11,6 @@ docs/build/
 
 test-reports/
 .coverage
+
+# ignore dists
+dist/

.gitlab-ci.yml

@@ -1,3 +1,11 @@
+default:
+  image: python:3.7
+  before_script:
+    - echo ===== update pip =====
+    - python -m pip install -U pip
+    - echo ===== install tox =====
+    - pip install tox
+
 stages:
   - pytest
   - quality
@@ -13,16 +21,9 @@ cache:
 
 pytest:
   stage: pytest
-  image: python:3.7 
-  # several python versions in 1 image: quay.io/python-devs/ci-image
-  before_script:
-    - echo ===== update pip =====
-    - python -m pip install -U pip
-    - echo ===== install tox =====
-    - pip install tox
+  script:
     - echo ===== create folder for artifacts =====
     - mkdir test-reports
-  script:
     - tox -e py
   artifacts:
     when: always
@@ -35,48 +36,25 @@ pytest:
 black:
   stage: quality
   image: python:3.7 
-  before_script:
-    - echo ===== update pip =====
-    - python -m pip install -U pip
-    - echo ===== install tox =====
-    - pip install tox
   script:
     - tox -e black
 
 mypy:
   stage: quality
-  image: python:3.7
-  before_script:
-    - echo ===== update pip =====
-    - python -m pip install -U pip
-    - echo ===== install tox =====
-    - pip install tox
   script:
     - tox -e mypy
 
 docs:
   stage: quality
-  image: python:3.7
-  before_script:
-    - echo ===== update pip =====
-    - python -m pip install -U pip
-    - echo ===== install tox =====
-    - pip install tox
   script:
     - tox -e docs    
 
 pytest-main:
 # run test using directly the pytest main branch  
   stage: pytest
-  image: python:3.7
-  before_script:
-    - echo ===== update pip =====
-    - python -m pip install -U pip
-    - echo ===== install tox =====
-    - pip install tox
+  script:
     - echo ===== create folder for artifacts =====
     - mkdir test-reports
-  script:
     - tox -e pytest-main
   artifacts:
     when: always
@@ -89,12 +67,12 @@ pytest-main:
     - if: $CI_PIPELINE_SOURCE == "schedule"
 
 sonar:
+  image: sonarsource/sonar-scanner-cli
   stage: sonar
+  before_script: []
   variables:
     SONAR_HOST_URL: $INS_SONAR_URL
     SONAR_LOGIN: $INS_SONAR_LOGIN
-  image:
-    name: sonarsource/sonar-scanner-cli
   script:
     - sonar-scanner -Dsonar.projectKey=$CI_PROJECT_NAME -Dsonar.branch.name=$CI_BUILD_REF_NAME -Dsonar.python.coverage.reportPaths=test-reports/coverage.xml
   allow_failure: true

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Institue of Networked Solutions (INS), Rapperswil/ NetTowel Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -9,26 +9,26 @@ One major difference between unit tests in programming and
 network tests is the definition of what a test actually is. 
 In programming, unit tests normally focus on testing edge cases, 
 since the amount of non-edge cases is not definable.
-In the network testing domain, tests are less about edge cases, but more about testing existing configurations with 
+In the network testing domain, tests are less about edge cases, but more about testing existing network states with 
 pre-defined test cases. Such a single test case might be "can host A reach neighbors X, Y, Z?" on many different devices. 
 This is what nuts tries to achieve:
-Apply test cases based on your pre-defined network topology to your actual network and have the tests confirm the correct configuration.
+Apply test cases based on your pre-defined network topology to your actual network and have the tests confirm the correct state.
 
 The project relies on the [pytest framework](https://docs.pytest.org/) to setup and execute the 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.
 
-Additionally, nuts treats the test definition and the so-called test bundle as separate entities.
+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.
 
-The test definition is modelled 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.
-
-The test bundle is a file that is parsed by pytest. The file provides data on the actual network configuration and describes which test definitions should be collected and executed by pytest. 
+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. 
 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. 
 
+While the readme here is only a short overview, find the [documentation of nuts on readthedocs](https://nuts.readthedocs.io/en/latest/).
+
 ## Test bundle structure
 
 Currently only yaml files are supported as test bundles, 
-but other sources such as other file formats or database entries can be considered in later versions.
+but other sources such as other file formats or database entries can be considered in later nuts versions.
 
 Each test bundle contains the following structure:
 ```yaml
@@ -50,11 +50,11 @@ Note that currently every test in this class will be executed.
 `label`: Additional identifier that can be used to distinguish between multiple occurrences of the same 
  test class in a test bundle.
 
-`test_execution`: Data that is exposed as part of the `nuts_parameters` property (explanation see below). 
+`test_execution`: Data that is exposed as part of the `nuts_parameters` property. 
 By convention this contains additional information that is passed directly to the nornir task in the background. 
 Therefore the key-value pairs must be consistent with the key-value pairs of the specific nornir task. 
 As an example, the test definition `napalm_ping.py` calls a nornir task to execute napalm's ping-command. 
-This allows the additional `max_drop` parameter in `test execution`, since it is in turn pre-defined by napalm.
+This allows the additional `max_drop` parameter in `test_execution`, since it is in turn pre-defined by napalm.
 
 `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.
 
@@ -64,68 +64,60 @@ This example creates three different tests, one for each entry in the `test_data
 
 ```yaml
 ---
-- test_module: pytest_nuts.base_tests.netmiko_cdp_neighbors
+- test_module: nuts.base_tests.netmiko_cdp_neighbors
   test_class: TestNetmikoCdpNeighbors
   test_data:
-    - source: R1
+    - host: R1
       local_port: GigabitEthernet3
       destination_host: R2
       management_ip: 172.16.12.2
       remote_port: GigabitEthernet2
-    - source: R1
+    - host: R1
       local_port: GigabitEthernet4
       destination_host: R3
       management_ip: 172.16.13.3
       remote_port: GigabitEthernet2
-    - source: R2
+    - host: R2
       local_port: GigabitEthernet2
       destination_host: R1
       management_ip: 172.16.12.1
       remote_port: GigabitEthernet3
 ...
 ```
 
-## Installation instructions
-NetTowel nuts is currently not published via pip. It has to be cloned and installed manually.
+## Manual installation instructions
+Nuts uses [poetry](https://python-poetry.org/) as a dependency manager.
 
-```
-git clone ssh://git@gitlab.ost.ch:45022/ins/nettowel/nettowel-nuts.git
-pip install <your_nuts_directory>
-```
+1. [Install poetry](https://python-poetry.org/docs/#installation).
+2. Clone this repository.
+3. Run `$ poetry install`
 
 ## Technical Overview
 
-### Nuts custom marker
-
-During test collection, the custom pytest marker "nuts" uses the data that has been defined in the test bundle mentioned above. 
-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.
-Each entry is a dictionary, but `pytest.mark.parametrize` expects a list of n-tuples as input. 
-The plugin therefore transforms those dictionary entries from `test_data` into tuples. 
-This transformation is currently fixed, but more flexibility is very likely to come at a later stage.
+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. 
+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. 
 
 The custom nuts marker takes two arguments: The first argument of the annotation determines the required fields. 
 For each entry in `test_data` these fields are extracted and transformed to a tuple considering the correct order.
 If any of these fields are not present in an entry of `test_data`, the corresponding test case will be skipped.
-The 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`.
+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`.
 
 #### Example of a test class with custom marker
 
 ```python
 @pytest.mark.usefixtures("check_nuts_result")  # see below
-class TestNetmikoCdpNeighbors:
-    @pytest.mark.nuts("host,remote_host,local_port,management_ip", "management_ip")
+class TestNetmikoCdpNeighbors:       
+    @pytest.mark.nuts("host,remote_host,local_port")
     def test_local_port(self, single_result, remote_host, local_port):
-        assert single_result.result[remote_host]["local_port"] == local_port
+        assert single_result.result[remote_host]["local_port"] == local_port        
 ```
 
-This test run of CDP neighbors checks the local port. 
+This test-run of CDP neighbors checks the local port. 
 
 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.
 
 The required fields are `host`, `remote_host` and `local_port` - they must be present in the custom marker, 
 but also be provided as argument to the test method itself.
-`management_ip` is an optional field and not necessary for the test - an entry in `test_data` is not required to have it.
 
 `single_result` uses the `host` field and provides the result that has been processed via the specific context of a test.
 
@@ -136,40 +128,13 @@ Currently, the predefined test classes use [nornir](https://nornir.readthedocs.i
 with the network devices, therefore the test classes derive all from a more specific `NornirNutsContext`, 
 which provides a nornir instance and nornir-specific helpers.
 
-This context class is then integrated into pytest fixtures. It is passed on to another fixture called `sincle_result` that returns a per-host result of one test.
-
 ## Development
-Nuts uses [poetry](https://python-poetry.org/) as a dependency manager.
-If you have not installed poetry, please read their [installation instructions](https://python-poetry.org/docs/#installation).
-
-### Installation requirements
 
-```bash
-poetry install
-```
-
-### Open shell with venv
-
-```bash
-poetry shell
-```
-
-### SonarQube
-Our [sonarqube server](sonarqube.ins.work) automatically analyses our project via Gitlab CI.
-If you prefer to run your analysis without pushing, you can trigger the analysis locally after executing the tests with coverage.
-
-Windows PowerShell:
-```bash
-$token=<your_token>
-docker run --volume ${pwd}:/usr/src --workdir /usr/src --rm -e SONAR_HOST_URL="https://sonarqube.ins.work" -e SONAR_LOGIN=$token sonarsource/sonar-scanner-cli "-Dsonar.projectKey=nettowel-nuts" "-Dsonar.branch.name=$(git rev-parse --abbrev-ref HEAD)" "-Dsonar.python.coverage.reportPaths=/usr/src/test-reports/coverage.xml"
-```
-UNIX:
-```bash
-token=<your_token>
-docker run --volume $PWD:/usr/src --workdir /usr/src --rm -e SONAR_HOST_URL="https://sonarqube.ins.work" -e SONAR_LOGIN=$token sonarsource/sonar-scanner-cli -Dsonar.projectKey=nettowel-nuts -Dsonar.branch.name=$(git rev-parse --abbrev-ref HEAD) -Dsonar.python.coverage.reportPaths=/usr/src/test-reports/coverage.xml
-```
+Nuts is essentially designed as a pytest-plugin and it is possible to add your own, self-written test classes. 
+A dev documentation on how to write your own test classes is planned for the future. 
+Until then, please read the regular [documentation of nuts](https://nuts.readthedocs.io/en/latest/) on how to use it.
 
 # Thanks
 
-* [Matthias Gabriel](https://github.com/MatthiasGabriel), who laid the foundations of NUTS.
+* [Matthias Gabriel](https://github.com/MatthiasGabriel), who laid the foundations of nuts.
 * [Florian Bruhin](https://github.com/The-Compiler) for invaluable feedback.

docs/source/index.rst

@@ -42,7 +42,6 @@ Enhance NUTS
 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.
 
 
-
 Contents
 ========
 

docs/source/installation/index.rst

@@ -25,6 +25,9 @@ NUTS is currently not published on the Python Package Index (`PyPI <https://pypi
    # install NUTS
    pip install <your_nuts_directory>
 
+   # install NUTS directly from git without clone first
+   pip install git+https://github.com/INSRapperswil/Nuts.git
+
 Parsing with ntc-templates
 --------------------------
 

docs/source/tutorial/firststeps.rst

@@ -1,9 +1,9 @@
 First Steps with NUTS
 =====================
 
-This tutorial guides you through a minimal setup of NUTS.
+This tutorial guides you through a minimal setup of the NetTowel Unit Testing System (NUTS, or nuts).
 
-Two major components are needed for NUTS:
+Two major components are needed for nuts:
 
     #. A network inventory
     #. Test bundles
@@ -71,7 +71,7 @@ If you set up the above folders and files, you're ready to write test bundles.
 
 A test bundle is a collection of tests are logically related to each other, for example tests that all revolve around "information on BGP neighbors". The test bundle describes which test definition should be collected and executed and provides data for those tests. The bundles are written as individual entries in a YAML file.
 
-Currently only YAML files are supported as test bundle format, but other data sources could be integrated in later versions of NUTS.
+Currently only YAML files are supported as test bundle format, but other data sources could be integrated in later versions of nuts.
 
 Structure of a Test Bundle
 **************************
@@ -93,7 +93,7 @@ Each test bundle contains the following structure:
 ``label``: Optional. Additional identifier that can be used to distinguish between multiple occurrences of the same 
 test class in a test bundle.
 
-``test_execution``: Optional. NUTS uses nornir tasks to automatically interact with the network. This field contains additional information that is directly passed to the nornir task in the background. Therefore the key-value pairs must be consistent with the key-value pairs of the specific nornir task. 
+``test_execution``: Optional. Nuts uses nornir tasks to automatically interact with the network. This field contains additional information that is directly passed to the nornir task in the background. Therefore the key-value pairs must be consistent with the key-value pairs of the specific nornir task. 
 As an example, the test definition ``TestNapalmPing`` calls a nornir task to execute napalm's ping-command. 
 This allows the additional ``count`` parameter in ``test execution``, since it is in turn pre-defined by napalm. Please see the :doc:`chapter on test bundles <../testbundles/alltestbundles>` for more detailed explanations.