1.. _VMware_REST_module_development: 2 3********************************************* 4Guidelines for VMware REST module development 5********************************************* 6 7The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) is maintained by Red Hat and the community. 8 9.. contents:: 10 :local: 11 12Contribution process 13==================== 14 15The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>`. 16 17If you would like to contribute a change, we would appreciate if you: 18 19- submit a Github Pull Request (PR) against the vmware_rest_code_generator project 20- but also ensure the generated modules are compliant with our quality criteria. 21 22Requirements 23============ 24 25You will need: 26 27- Python 3.6 or greater 28- the `tox <https://tox.readthedocs.io/en/latest/install.html>` command 29 30 31vmware_rest_code_generator 32========================== 33 34Your contribution should follow the coding style of `Black <https://github.com/psf/black>`. 35To run the code formatter, just run: 36 37.. code-block:: shell 38 39 tox -e black 40 41To regenerate the vmware_rest collection, you can use the following commands: 42 43.. code-block:: shell 44 45 tox -e refresh_modules -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest 46 47If you also want to update the EXAMPLE section of the modules, run: 48 49.. code-block:: shell 50 51 tox -e refresh_examples -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest 52 53Testing with ansible-test 54========================= 55 56All the modules are covered by a functional test. The tests are located in the :file:`tests/integration/targets/`. 57 58To run the tests, you will need a vcenter instance and an ESXi. 59 60black code formatter 61~~~~~~~~~~~~~~~~~~~~ 62 63We follow the coding style of `Black <https://github.com/psf/black>`. 64You can run the code formatter with the following command. 65 66 67.. code-block:: shell 68 69 tox -e black 70 71sanity tests 72~~~~~~~~~~~~ 73 74Here we use Python 3.8, the minimal version is 3.6. 75 76.. code-block:: shell 77 78 tox -e black 79 ansible-test sanity --debug --requirements --local --skip-test future-import-boilerplate --skip-test metaclass-boilerplate --python 3.8 -vvv 80 81 82integration tests 83~~~~~~~~~~~~~~~~~ 84 85These tests should be run against your test environment. 86 87..warning:: The test suite will delete all the existing DC from your test environment. 88 89First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in 90this example: 91 92.. code-block:: ini 93 94 [vmware_rest] 95 localhost ansible_connection=local ansible_python_interpreter=python 96 97 [vmware_rest:vars] 98 vcenter_hostname=vcenter.test 99 vcenter_username=administrator@vsphere.local 100 vcenter_password=kLRy|FXwZSHXW0w?Q:sO 101 esxi1_hostname=esxi1.test 102 esxi1_username=zuul 103 esxi1_password=f6QYNi65k05kv8m56 104 105 106To run the tests, use the following command. You may want to adjust the Python version. 107 108.. code-block:: shell 109 110 ansible-test network-integration --diff --no-temp-workdir --python 3.8 --inventory /tmp/inventory-vmware_rest zuul/ 111 112