ansible/docs/docsite/rst/dev_guide/developing_modules_general.rst

230 lines
11 KiB
ReStructuredText
Raw Normal View History

.. _developing_modules_general:
.. _module_dev_tutorial_sample:
*******************************************
Ansible module development: getting started
*******************************************
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the :command:`ansible` or :command:`ansible-playbook` programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting.
If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see :ref:`developing_locally`.
.. contents:: Topics
:local:
.. _environment_setup:
Environment setup
=================
Prerequisites via apt (Ubuntu)
------------------------------
Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):
.. code:: bash
sudo apt update
sudo apt install build-essential libssl-dev libffi-dev python-dev
Common environment setup
------------------------------
1. Clone the Ansible repository:
``$ git clone https://github.com/ansible/ansible.git``
2. Change directory into the repository root dir: ``$ cd ansible``
3. Create a virtual environment: ``$ python3 -m venv venv`` (or for
Python 2 ``$ virtualenv venv``. Note, this requires you to install
the virtualenv package: ``$ pip install virtualenv``)
4. Activate the virtual environment: ``$ . venv/bin/activate``
5. Install development requirements:
``$ pip install -r requirements.txt``
6. Run the environment setup script for each new dev shell process:
``$ . hacking/env-setup``
.. note:: After the initial setup above, every time you are ready to start
developing Ansible you should be able to just run the following from the
root of the Ansible repo:
``$ . venv/bin/activate && . hacking/env-setup``
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
Creating an info or a facts module
==================================
Ansible gathers information about the target machines using facts modules, and gathers information on other objects or files using info modules.
If you find yourself trying to add ``state: info`` or ``state: list`` to an existing module, that is often a sign that a new dedicated ``_facts`` or ``_info`` module is needed.
In Ansible 2.8 and onwards, we have two type of information modules, they are ``*_info`` and ``*_facts``.
If a module is named ``<something>_facts``, it should be because its main purpose is returning ``ansible_facts``. Do not name modules that do not do this with ``_facts``.
Only use ``ansible_facts`` for information that is specific to the host machine, for example network interfaces and their configuration, which operating system and which programs are installed.
Modules that query/return general information (and not ``ansible_facts``) should be named ``_info``.
General information is non-host specific information, for example information on online/cloud services (you can access different accounts for the same online service from the same host), or information on VMs and containers accessible from the machine, or information on individual files or programs.
Info and facts modules, are just like any other Ansible Module, with a few minor requirements:
1. They MUST be named ``<something>_info`` or ``<something>_facts``, where <something> is singular.
2. Info ``*_info`` modules MUST return in the form of the :ref:`result dictionary<common_return_values>` so other modules can access them.
3. Fact ``*_facts`` modules MUST return in the ``ansible_facts`` field of the :ref:`result dictionary<common_return_values>` so other modules can access them.
4. They MUST support :ref:`check_mode <check_mode_dry>`.
5. They MUST NOT make any changes to the system.
6. They MUST document the :ref:`return fields<return_block>` and :ref:`examples<examples_block>`.
To create an info module:
1. Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing module using collection, ``$ cd plugins/modules/`` inside your collection development tree.
2. Create your new module file: ``$ touch my_test_info.py``.
3. Paste the content below into your new info module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>` and some example code.
4. Modify and extend the code to do what you want your new info module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code.
.. literalinclude:: ../../../../examples/scripts/my_test_info.py
:language: python
Use the same process to create a facts module.
.. literalinclude:: ../../../../examples/scripts/my_test_facts.py
:language: python
Creating a module
=================
To create a new module:
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
1. Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing module using collection, ``$ cd plugins/modules/`` inside your collection development tree.
2. Create your new module file: ``$ touch my_test.py``.
3. Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>` and some example code.
4. Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean, concise module code.
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
.. literalinclude:: ../../../../examples/scripts/my_test.py
:language: python
Exercising your module code
===========================
Once you've modified the sample code above to do what you want, you can try out your module.
Our :ref:`debugging tips <debugging_modules>` will help if you run into bugs as you exercise your module code.
Exercising module code locally
------------------------------
If your module does not need to target a remote host, you can quickly and easily exercise your code locally like this:
- Create an arguments file, a basic JSON config file that passes parameters to your module so you can run it. Name the arguments file ``/tmp/args.json`` and add the following content:
.. code:: json
{
"ANSIBLE_MODULE_ARGS": {
"name": "hello",
"new": true
}
}
- If you are using a virtual environment (highly recommended for
development) activate it: ``$ . venv/bin/activate``
- Setup the environment for development: ``$ . hacking/env-setup``
- Run your test module locally and directly:
[backport][2.10]Docs backportapalooza3 (#70695) * Suggest ansible ad-hoc command while developing module (#70308) If a local module has no documentation, the doc command will fail without any hints of what is wrong. Add another way to confirm the presence of a local module. * Update docs/docsite/rst/dev_guide/developing_locally.rst Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 82e5d03bdb6ebff0d8548a5d78296a6c96c8ea32) * Update AWS Integration test docmentation (#70454) (cherry picked from commit e1ba7dc52a0a9d8c81e92323a4d15c11171dba5c) * Update hacking/shippable docs. The `--all` option downloads more than is needed for analyzing code coverage. (cherry picked from commit fb7740ae3b5b660bd7f4a845293aab1612b24b9b) * Document that subversion module requires subversion (#70537) (cherry picked from commit 64c2cb273f91ea54275db85b5cee1d3e7ad117da) * update documentation link to python 3 (#70509) update the docs link for strftime on the filters page to point to the python3 docs (cherry picked from commit f7db428375bc39ce3e71c5a595dcd53bfe0d7425) * Update windows_winrm.rst (#70306) gcc also needed to be installed alongside python-devel, krb5-devel, krb5-libs, and krb5-workstation. (cherry picked from commit f4ea43c4a0c0bc718136de6c7e33a7ae111c1fad) * updated requirements file for docs build (#70609) (cherry picked from commit 38ccfb4a3e33fcaec54d82900d67e20226374f65) * Clarify that index_var is 0 indexed (#70548) A little further down the page is another index, ansible_loop.index, which shares a similar description but is 1 indexed. Its zero indexed twin has a 0 suffix. ``ansible_loop.index`` The current iteration of the loop. (1 indexed) ``ansible_loop.index0`` The current iteration of the loop. (0 indexed) To remove ambiguity around the usage of index_var, explicitly mention that this variable is 0 indexed. (cherry picked from commit c410311f55b3f00831b8d3de06fbd3084f705a3d) * docs: update module development docs (#70594) Update module development docs for flattened modules directory. Fixes: #70261 (at least partially) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 20209c508f13b018b8f44f77749001979aa5f048) * Doc: fix examples of changelog entries. (#70551) (cherry picked from commit edcd1a1a7003dd918f312919ce3bc043d7d4e8c9) * Document tags are not supported with task meta. (#70590) fixes #70338 (cherry picked from commit 40591d5fbbe9878427fc5b1b46ec820f69feba1a) * docs: update date format in removed_at_date (#70597) removed_at_date requires YYYY-MM-DD format. Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 375c6b4ae4b809eace0ef6783e70349d04d5dc6a) * partial update of community docs to reflect collections transition (#70488) (cherry picked from commit f1f782fc371e239a3f18aa3551506e8a4326b72e) Co-authored-by: Michael Ritsema <michaelritsema@users.noreply.github.com> Co-authored-by: Mark Chappell <mchappel@redhat.com> Co-authored-by: Matt Clay <matt@mystile.com> Co-authored-by: Alan Rominger <arominge@redhat.com> Co-authored-by: FloMiau <37121807+FloMiau@users.noreply.github.com> Co-authored-by: mahadelmi <mahadelmi@cmail.carleton.ca> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Karl Goetz <goetzk@users.noreply.github.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
2020-07-17 20:50:40 +02:00
``$ python -m ansible.modules.my_test /tmp/args.json``
This should return output like this:
.. code:: json
{"changed": true, "state": {"original_message": "hello", "new_message": "goodbye"}, "invocation": {"module_args": {"name": "hello", "new": true}}}
Exercising module code in a playbook
------------------------------------
The next step in testing your new module is to consume it with an Ansible playbook.
- Create a playbook in any directory: ``$ touch testmod.yml``
2017-08-14 02:09:19 +02:00
- Add the following to the new playbook file::
2017-08-14 02:09:19 +02:00
- name: test my new module
hosts: localhost
tasks:
- name: run the new module
my_test:
2017-08-14 02:09:19 +02:00
name: 'hello'
new: true
register: testout
- name: dump test output
debug:
msg: '{{ testout }}'
- Run the playbook and analyze the output: ``$ ansible-playbook ./testmod.yml``
Testing basics
====================
These two examples will get you started with testing your module code. Please review our :ref:`testing <developing_testing>` section for more detailed
information, including instructions for :ref:`testing module documentation <testing_module_documentation>`, adding :ref:`integration tests <testing_integration>`, and more.
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
.. note::
Every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure.
In this case, the tests should be marked with the ``unsupported`` alias in `aliases file <https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html>`_.
Performing sanity tests
-----------------------
You can run through Ansible's sanity checks in a container:
``$ ansible-test sanity -v --docker --python 2.7 MODULE_NAME``
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
.. note::
Note that this example requires Docker to be installed and running. If you'd rather not use a container for this, you can choose to use ``--venv`` instead of ``--docker``.
Unit tests
----------
You can add unit tests for your module in ``./test/units/modules``. You must first setup your testing environment. In this example, we're using Python 3.5.
- Install the requirements (outside of your virtual environment): ``$ pip3 install -r ./test/lib/ansible_test/_data/requirements/units.txt``
[backport][docs][2.10]Docsbackportapalooza 8 (#71379) * Move 2.10.0rc1 release date a few days forward. (#71270) At yesterday's meeting it was decided to have ansible-2.10.0 depend on ansible-base-2.10.1 so that we can get several fixes for ansible-base's routing (including adding the gluster.gluster collection). ansible-base-2.10.1 will release on September 8th. So we will plan on releasing ansible-2.10.0rc1 on the 10th. https://meetbot.fedoraproject.org/ansible-community/2020-08-12/ansible_community_meeting.2020-08-12-18.00.html (cherry picked from commit e507c127e58791755d207b46f6c829dacd7ad55c) * a few writing style updates (#71212) (cherry picked from commit 4f0bd5de38fb72c4aa686fa8736a3d8cc75393c0) * Fix code markups and add link to CVE (#71082) (cherry picked from commit 92d59a58c09f2a8baf811abe1beb09e4f911eb54) * Fix 404 links (#71256) Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit ecea0185064b4ce8932917702a84962a75280fcf) * Writing style updates to Developing dynamic inventory topic (#71245) * modified the writing style * incorporated peer feedback (cherry picked from commit ecd3b52ad7e0dbe9042b71b2e22b33e5cef79141) * Fix roadmap formatting. (#71275) (cherry picked from commit ee48e0b0ad33dab245ff6a64f3ac0344de06ae56) * Update password.py (#71295) List md5_crypt, bcrypt, sha256_crypt, sha512_crypt as hash schemes in the password plugin. (cherry picked from commit 1d1de2c6fd2231a88b494574eba7f4d3fd7ba5b5) * Update ansible european IRC channel (#71326) Signed-off-by: Rémi VERCHERE <remi@verchere.fr> (cherry picked from commit 824cd4cbeb0a576bcd9b8a118c1f9fdcc7816ce1) * Add warning about copyright year change (#71251) To simplify project administration and avoid any legal issues, add a warning in the docs. This reflects - https://github.com/ansible/ansible/issues/45989#issuecomment-423635622 and fixes: #45989 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 606604bb97ab7ab94b42a53669f09c51f7e4d818) * subelements: Clarify parameter docs (#71177) skip_missing parameter in subelements lookup plugin is accepted from inside the dictionary. Fixes: #38182 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 6d17736ef45cbb81bdcbafd5b52dc45f75535baf) * Writing style updates to Using Variables topic (#71194) * updated topic title, underline length for headings, and incorporated peer feedback (cherry picked from commit 4d68efbe248cdf75b4a9d87c9a04bd19db81a1d1) * cron module defaults to current user, not root (#71337) (cherry picked from commit 4792d83e13d7622832e3885ffa2d3d0e543d42b6) * Update Network Getting Started for FQCN/collection world (#71188) * pull out network roles, cleanup, update first playbook examples, update gather facts section, some inventory conversion to .yml, update inventory and roles, simplify the navigation titles, fix tocs, feedback comments (cherry picked from commit f79a7c558574a44016d2ff978aaddf00f241a08c) * Add documentation about info/facts module development (#71250) Fixes: #40151 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit 4f993922c87a6f12821f40c460750471bd6ee1e7) * network: Correct documentation (#71246) ini-style inventory does not support Ansible Vault password. This fixes network_best_practices_2.5 doc. Fixes: #69039 Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com> (cherry picked from commit a1257d75aa2f874ea2768dd99c4affe8b37a886f) * tidies up vars page (#71339) (cherry picked from commit 02ea80f6d77f03ebb06ac78efc4bff183afe3c6e) * base.yml: Fix typos (#71346) (cherry picked from commit 41d7d53573e4f1bf366299b7f1eff15d6643c7ab) * quick fix to change main back to devel (#71342) * quick fix to change main back to devel * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-authored-by: Felix Fontein <felix@fontein.de> (cherry picked from commit 74f88c56a515d7edbc2c0572ad56c367a3775fd0) * Add note about integration tests for new modules to the dev guide (#71345) (cherry picked from commit b82889eef550cbb4074859b9fa0c38b6c04f56f1) * update fest link (#71376) (cherry picked from commit 80b8fde94652ba5a183a8dd3df64c1780a86c57d) * incorporate minimalism feedback on debugging page (#71272) Co-authored-by: bobjohnsrh <50667510+bobjohnsrh@users.noreply.github.com> (cherry picked from commit 5073cfc8bc0dbd3c8796e460891aee971921faa2) * fix header problem Co-authored-by: Toshio Kuratomi <a.badger@gmail.com> Co-authored-by: Sayee <57951841+sayee-jadhav@users.noreply.github.com> Co-authored-by: Baptiste Mille-Mathias <baptiste.millemathias@gmail.com> Co-authored-by: Abhijeet Kasurde <akasurde@redhat.com> Co-authored-by: Felix Fontein <felix@fontein.de> Co-authored-by: rovshango <rovshan.go@gmail.com> Co-authored-by: Remi Verchere <rverchere@users.noreply.github.com> Co-authored-by: Jake Howard <RealOrangeOne@users.noreply.github.com> Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com> Co-authored-by: Per Lundberg <perlun@gmail.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
2020-08-21 00:44:50 +02:00
- Run ``. hacking/env-setup``
- To run all tests do the following: ``$ ansible-test units --python 3.5``. If you are using a CI environment, these tests will run automatically.
.. note:: Ansible uses pytest for unit testing.
To run pytest against a single test module, you can do the following (provide the path to the test module appropriately):
``$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes
test/units/modules/.../test/my_test.py``
Contributing back to Ansible
============================
If you would like to contribute to the main Ansible repository
by adding a new feature or fixing a bug, `create a fork <https://help.github.com/articles/fork-a-repo/>`_
of the Ansible repository and develop against a new feature
branch using the ``devel`` branch as a starting point.
When you you have a good working code change, you can
submit a pull request to the Ansible repository by selecting
your feature branch as a source and the Ansible devel branch as
a target.
If you want to contribute your module back to the upstream Ansible repo,
review our :ref:`submission checklist <developing_modules_checklist>`, :ref:`programming tips <developing_modules_best_practices>`,
and :ref:`strategy for maintaining Python 2 and Python 3 compatibility <developing_python_3>`, as well as
information about :ref:`testing <developing_testing>` before you open a pull request.
The :ref:`Community Guide <ansible_community_guide>` covers how to open a pull request and what happens next.
Communication and development support
=====================================
Join the IRC channel ``#ansible-devel`` on freenode for discussions
surrounding Ansible development.
For questions and discussions pertaining to using the Ansible product,
use the ``#ansible`` channel.
For more specific IRC channels look at :ref:`Community Guide, Communicating <communication_irc>`.
Credit
======
Thank you to Thomas Stringer (`@trstringer <https://github.com/trstringer>`_) for contributing source
material for this topic.