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