From 849bf991c8aa41212faa30e2c87720df4569c33a Mon Sep 17 00:00:00 2001 From: Nitish K Mishra Date: Wed, 26 Jul 2023 11:22:00 +0530 Subject: [PATCH] Including readme file for creating test and development environment. Signed-off-by: Nitish K Mishra --- tests/README.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 tests/README.md diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..4a56bbd --- /dev/null +++ b/tests/README.md @@ -0,0 +1,133 @@ +## Creating a Testing and Virtual Environment +REQUIREMENTS: +- you need python3 to create a virtual environment + +Steps: + +(1) clone the repository into your local environment inside the +directort structure `ansible_collections/ibm/power_vios +``` +git clone git@github.com:nitismis/ansible-power-vios.git ansible_collections/ibm/power_vios +``` + +(2) `cd ansible_collections/ibm/power_vios` + +(3) create a virtual environment using the built-in `venv` module of `python3` +``` +python3 -m venv +``` +**NOTE**: This will create a directory named `` in the +current working directory. Make sure you DO NOT push this to your remote repository. + +(4) activate virtual environment +``` +source /bin/activate +``` +**NOTE**: to deactivate virtual environment just run the command `deactivate` whilst +the virtual environment is active. + +(5) install ansible 2.9 (if any issue, then install 2.10.7) +``` +python -m pip install --upgrade pip +python -m pip install ansible==2.9.* +``` +**NOTE**: You can also use the utility `Makefile` included in the repo by running +`make install-ansible ANSIBLE_VERSION=2.9` + +(6) `export ANSIBLE_COLLECTIONS_PATHS=` + +e.g. if `ansible_collections/ibm/power_vios` is in `$(HOME)/Ansible/ansible_collections/ibm/power_vios` +then run `export ANSIBLE_COLLECTIONS_PATHS=$(HOME)/Ansible` + +-------------------------------------------------------------------------------------------------------- +## Running Sanity Tests Locally +REQUIREMENTS: +- must use python **3.8**>= + +Steps: + +(1) setup testing and virtual environment + +(2) install sanity test requirements +``` +python -m pip install -r tests/sanity/sanity.requirements +``` +**NOTE**: You can also run `make install-sanity-test-requirements` + +(3) run the sanity test +``` +ansible-test sanity -v --python 3.8 --exclude plugins/modules/_*.py plugins/modules/ +``` +**NOTE**: you can also just use `make sanity-test` instead + +-------------------------------------------------------------------------------------------------------- +## Running Unit Tests Locally +Steps: + +(1) setup testing and virtual environment + +(2) install unit test requirements +``` +python -m pip install -r tests/unit/unit.requirements +``` +**NOTE**: You can also run `make install-unit-test-requirements` + +(3) run the sanity test +``` +ansible-test units -v --python 3.8 +``` +**NOTE**: you can also just use `make unit-test` instead + +-------------------------------------------------------------------------------------------------------- +## Running PEP8 linting locally +Steps: + +(1) follow **Running Sanity Tests Locally** up until step (2) + +(2) run `make lint` + +**NOTE**: +if it does not work use +`flake8 plugins/modules/*.py --ignore=E402,W503 --max-line-length=160 --exclude=plugins/modules/_*.py` and +`python -m pycodestyle --ignore=E402,W503 --max-line-length=160 --exclude=plugins/modules/_*.py plugins/modules/*.py` +instead + +-------------------------------------------------------------------------------------------------------- +## Running compile test locally +**NOTE**: to make sure that the collection's modules are compatible with the +specified python version +Steps: + +(1) follow **Running Sanity Tests Locally** up until step (2) + +(2) run `make compile` + +**NOTE**: +- to run on a specific python version `make compile PYTHON_VERSION=<*.* version>` +- if it does not work use `ansible-test sanity --test compile --python <*.* version> plugins/modules/*.py + +-------------------------------------------------------------------------------------------------------- +## CI Testing +- on pull request to `dev-collection` branch, the github actions workflow will trigger +sanity and unit testing. +- sanity testing will include PEP8 linting, compile testing, and ansible sanity test + +-------------------------------------------------------------------------------------------------------- +## Guidelines For Creating Unit Tests +- creating unit tests for `plugins/modules/.py` must be written in the corresponding +`tests/unit/plugins/modules/test_.py` test module +- creating unit tests for `plugins/action/.py` must be written in the corresponding +`tests/unit/plugins/action/test_.py` test module +- for mocking purposes we are using the built-in python module `unittest.mock` +- for running the test we use `ansible-test units` as a test runner +- (soft suggestion) when mocking, use a context manager method instead of decorators, etc. +- for common utility functions used in unit testings, add them to `tests/unit/plugins/modules/common/util.py` +- if you need files which contains text information needed for unit testing (such as mocking an expected text +output from a call), store them in `tests/unit/plugins/module/common` + + +-------------------------------------------------------------------------------------------------------- +## Resources +- [unittest](https://docs.python.org/3.7/library/unittest.html) documentation +- [regular expressions](https://docs.python.org/3.7/library/re.html) documentation +- [ansible unit testing](https://docs.ansible.com/ansible/latest/dev_guide/testing_units.html) documentation