diff --git a/docs/developing.md b/docs/developing.md index ca04283..0434ed6 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -11,3 +11,24 @@ - `vars/` vs `defaults/` - internal or interpolated variables that don't need to change or be overridden by user go in `vars/`, those that a user would likely override, go under `defaults/` directory - All arguments have a specification in `meta/argument_specs.yml` - All playbooks/roles should be focused on compatibility with Ansible Automation Platform + +## Development environment + +To develop and to run tests you need to install `tox` and `tox-ansible` on +your machine. + +``` +pip install --user tox tox-ansible +``` + +### Virtualenv for development + +To build a virtualenv for development purposes run the following command: + +``` +make build-venv +``` + +The resulting virtualenv will be symlinked to `.venv`, which for example can +be selected as virtualenv in VSCode (`Shift+Ctrl+P` and then +`Python: Select Interpreter`). diff --git a/docs/testing.md b/docs/testing.md index 6ed0b3d..c71a1b6 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,9 +1,88 @@ # Testing -## Continuous integration +## Sanity and unit tests -The `hack/e2e-setup.sh` script contains the steps necessary to reproduce the CI test environment, which relies on `kubectl` and `kind`. +Sanity and unit tests can be run in two ways: +- with `tox` and the `tox-ansible` plugin (both need to be installed on the dev machine) +- with `ansible-test` + +For development purposes `tox` and `tox-ansible` are better suited, as they allow +debugging of issues in the collection on the developer's machine. + +For verification purposes of the collection the compatibility with `ansible-test` +is ensured. + +### Running tests with tox-ansible + +Run sanity tests with `tox-ansible` like so: + +``` +make test-sanity +``` + +Run unit tests with `tox-ansible` like so: + +``` +make test-unit +``` + +### Running tests with ansible-test + +In order to test changes with `ansible-test`, it is recommended to bind mount +the repository to `~/.ansible/collections/ansible_collections/kubevirt/core` +if you did not check it out into this location. + +This can be done with: + +``` +mkdir -p ~/.ansible/collections/ansible_collections/kubevirt/core +sudo mount --bind /kubevirt.core ~/.ansible/collections/ansible_collections/kubevirt/core +cd ~/.ansible/collections/ansible_collections/kubevirt/core +``` + +Run sanity tests with `ansible-test` like so: + +``` +ANSIBLE_TEST_PREFER_PODMAN=1 ansible-test sanity --docker +``` + +Run unit tests with `ansible-test` like so: + +``` +ANSIBLE_TEST_PREFER_PODMAN=1 ansible-test units --docker +``` + +## Integration tests + +Integration tests require a working cluster and can be run with +`ansible-test`. + +### Continuous integration + +The `hack/e2e-setup.sh` script contains the steps necessary to reproduce the +CI integration test environment, which relies on `docker` or `podman`, +`kubectl` and `kind`. + +To create the CI integration test environment on your machine run: + +``` +make cluster-up +``` + +To remove the test CI integration test environment run: + +``` +make cluster-down +``` + +### Running integration tests with ansible test + +Run integration tests with ansible-test like so: + +``` +ansible-test integration +``` ## Example config and playbooks diff --git a/galaxy.yml b/galaxy.yml index 4c15e9c..c598398 100644 --- a/galaxy.yml +++ b/galaxy.yml @@ -37,9 +37,11 @@ build_ignore: - OWNERS - REVIEW_CHECKLIST.md - tox.ini + - tox-ansible.ini - '*.tar.gz' - '*.zip' - docs/_gh_include - docs/conf.py - docs/roles.rst.template - docs/requirements.txt + - tests/requirements.txt diff --git a/test-requirements.txt b/test-requirements.txt index c826e5c..fa4ef3c 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -3,4 +3,3 @@ pytest pytest-ansible pytest-mock pytest-xdist -tox-ansible