From 55c70dfb72185ce594ef84074977917610b8f7c3 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 21 Jan 2022 19:55:16 +0100 Subject: [PATCH] Improve documentation on how to run tests (#4070) (#4072) * Improve documentation on how to run tests. * Fix incomplete sentence. * Apply suggestions from code review Co-authored-by: Andrew Klychkov * Improve separation. * Fix unrelated typo. Co-authored-by: Andrew Klychkov (cherry picked from commit 8a03d9f2868b85ee893534a22e0e9b51215e0902) Co-authored-by: Felix Fontein --- CONTRIBUTING.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 970786ff56..0593d1a7e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ Also, consider taking up a valuable, reviewed, but abandoned pull request which * Try committing your changes with an informative but short commit message. * Do not squash your commits and force-push to your branch if not needed. Reviews of your pull request are much easier with individual commits to comprehend the pull request history. All commits of your pull request branch will be squashed into one commit by GitHub upon merge. -* Do not add merge commits to your PR. The bot will complain and you will have to rebase ([instructions for rebasing](https://docs.ansible.com/ansible/latest/dev_guide/developing_rebasing.html)) to remove them before your PR can be merged. To avoid that git automatically does merges during pulls, you can configure it to do rebases instead by running `git config pull.rebase true` inside the respository checkout. +* Do not add merge commits to your PR. The bot will complain and you will have to rebase ([instructions for rebasing](https://docs.ansible.com/ansible/latest/dev_guide/developing_rebasing.html)) to remove them before your PR can be merged. To avoid that git automatically does merges during pulls, you can configure it to do rebases instead by running `git config pull.rebase true` inside the repository checkout. * Make sure your PR includes a [changelog fragment](https://docs.ansible.com/ansible/devel/community/development_process.html#changelogs-how-to). (You must not include a fragment for new modules or new plugins, except for test and filter plugins. Also you shouldn't include one for docs-only changes. If you're not sure, simply don't include one, we'll tell you whether one is needed or not :) ) * Avoid reformatting unrelated parts of the codebase in your PR. These types of changes will likely be requested for reversion, create additional work for reviewers, and may cause approval to be delayed. @@ -36,6 +36,54 @@ If you want to test a PR locally, refer to [our testing guide](https://github.co If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it. +## Run sanity, unit or integration tests locally + +You have to check out the repository into a specific path structure to be able to run `ansible-test`. The path to the git checkout must end with `.../ansible_collections/community/general`. Please see [our testing guide](https://github.com/ansible/community-docs/blob/main/test_pr_locally_guide.rst) for instructions on how to check out the repository into a correct path structure. The short version of these instructions is: + +```.bash +mkdir -p ~/dev/ansible_collections/community +git clone https://github.com/ansible-collections/community.general.git ~/dev/ansible_collections/community/general +cd ~/dev/ansible_collections/community/general +``` + +Then you can run `ansible-test` (which is a part of [ansible-core](https://pypi.org/project/ansible-core/)) inside the checkout. The following example commands expect that you have installed Docker or Podman. Note that Podman has only been supported by more recent ansible-core releases. If you are using Docker, the following will work with Ansible 2.9+. + +The following commands show how to run sanity tests: + +```.bash +# Run sanity tests for all files in the collection: +ansible-test sanity --docker -v + +# Run sanity tests for the given files and directories: +ansible-test sanity --docker -v plugins/modules/system/pids.py tests/integration/targets/pids/ +``` + +The following commands show how to run unit tests: + +```.bash +# Run all unit tests: +ansible-test units --docker -v + +# Run all unit tests for one Python version (a lot faster): +ansible-test units --docker -v --python 3.8 + +# Run a specific unit test (for the nmcli module) for one Python version: +ansible-test units --docker -v --python 3.8 tests/unit/plugins/modules/net_tools/test_nmcli.py +``` + +The following commands show how to run integration tests: + +```.bash +# Run integration tests for the interfaces_files module in a Docker container using the +# fedora35 operating system image (the supported images depend on your ansible-core version): +ansible-test integration --docker fedora35 -v interfaces_file + +# Run integration tests for the flattened lookup **without any isolation**: +ansible-test integration -v lookup_flattened +``` + +If you are unsure about the integration test target name for a module or plugin, you can take a look in `tests/integration/targets/`. Tests for plugins have the plugin type prepended. + ## Creating new modules or plugins Creating new modules and plugins requires a bit more work than other Pull Requests.