~ Use of this source code is governed by the Apache License 2.0
~ that can be found in the LICENSE file.
-->
# How to contribute to ANTA
Contribution model is based on a fork-model. Don't push to arista-netdevops-community/anta directly. Always do a branch in your forked repository and create a PR.
To help development, open your PR as soon as possible even in draft mode. It helps other to know on what you are working on and avoid duplicate PRs.
> NOTE: Typing is configured quite strictly, do not hesitate to reach out if you have any questions, struggles, nightmares.
## Unit tests
To keep high quality code, we require to provide a Pytest for every tests implemented in ANTA.
All submodule should have its own pytest section under `tests/units/anta_tests/<submodule-name>.py`.
### How to write a unit test for an AntaTest subclass
The Python modules in the `tests/units/anta_tests` folder define test parameters for AntaTest subclasses unit tests.
A generic test function is written for all unit tests in `tests.lib.anta` module.
The `pytest_generate_tests` function definition in `conftest.py` is called during test collection.
The `pytest_generate_tests` function will parametrize the generic test function based on the `DATA` data structure defined in `tests.units.anta_tests` modules.
See https://docs.pytest.org/en/7.3.x/how-to/parametrize.html#basic-pytest-generate-tests-example
The `DATA` structure is a list of dictionaries used to parametrize the test.
The list elements have the following keys:
-`name` (str): Test name as displayed by Pytest.
-`test` (AntaTest): An AntaTest subclass imported in the test module - e.g. VerifyUptime.
-`eos_data` (list[dict]): List of data mocking EOS returned data to be passed to the test.
-`inputs` (dict): Dictionary to instantiate the `test` inputs as defined in the class from `test`.
-`expected` (dict): Expected test result structure, a dictionary containing a key
`result` containing one of the allowed status (`Literal['success', 'failure', 'unset', 'skipped', 'error']`) and optionally a key `messages` which is a list(str) and each message is expected to be a substring of one of the actual messages in the TestResult object.
In order for your unit tests to be correctly collected, you need to import the generic test function even if not used in the Python module.
Test example for `anta.tests.system.VerifyUptime` AntaTest.
``` python
# Import the generic test function
from tests.lib.anta import test # noqa: F401
# Import your AntaTest
from anta.tests.system import VerifyUptime
# Define test parameters
DATA: list[dict[str, Any]] = [
{
# Arbitrary test name
"name": "success",
# Must be an AntaTest definition
"test": VerifyUptime,
# Data returned by EOS on which the AntaTest is tested
> NOTE: It could happen that pre-commit and tox disagree on something, in that case please open an issue on Github so we can take a look.. It is most probably wrong configuration on our side.
## Configure MYPYPATH
In some cases, mypy can complain about not having `MYPYPATH` configured in your shell. It is especially the case when you update both an anta test and its unit test. So you can configure this environment variable with:
[`mkdocs`](https://www.mkdocs.org/) is used to generate the documentation. A PR should always update the documentation to avoid documentation debt.
### Install documentation requirements
Run pip to install the documentation requirements from the root of the repo:
```bash
pip install -e .[doc]
```
### Testing documentation
You can then check locally the documentation using the following command from the root of the repo:
```bash
mkdocs serve
```
By default, `mkdocs` listens to http://127.0.0.1:8000/, if you need to expose the documentation to another IP or port (for instance all IPs on port 8080), use the following command:
```bash
mkdocs serve --dev-addr=0.0.0.0:8080
```
### Build class diagram
To build class diagram to use in API documentation, you can use `pyreverse` part of `pylint` with [`graphviz`](https://graphviz.org/) installed for jpeg generation.
Image will be generated under `docs/imgs/uml/` and can be inserted in your documentation.
### Checking links
Writing documentation is crucial but managing links can be cumbersome. To be sure there is no dead links, you can use [`muffet`](https://github.com/raviqqe/muffet) with the following command:
GitHub actions is used to test git pushes and pull requests. The workflows are defined in this [directory](https://github.com/arista-netdevops-community/anta/tree/main/.github/workflows). We can view the results [here](https://github.com/arista-netdevops-community/anta/actions).
