You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
ansible/docs/docsite/rst/dev_guide/testing_validate-modules.rst

159 lines
6.9 KiB
ReStructuredText

****************
validate-modules
****************
.. contents:: Topics
Python program to help test or validate Ansible modules.
``validate-modules`` is one of the ``ansible-test`` Sanity Tests, see :doc:`testing_sanity` for more information.
Originally developed by Matt Martz (@sivel)
Usage
=====
.. code:: shell
cd /path/to/ansible/source
source hacking/env-setup
ansible-test sanity --test validate-modules
Help
====
.. code:: shell
usage: validate-modules [-h] [-w] [--exclude EXCLUDE] [--arg-spec]
[--base-branch BASE_BRANCH] [--format {json,plain}]
[--output OUTPUT]
modules [modules ...]
positional arguments:
modules Path to module or module directory
optional arguments:
-h, --help show this help message and exit
-w, --warnings Show warnings
--exclude EXCLUDE RegEx exclusion pattern
--arg-spec Analyze module argument spec
--base-branch BASE_BRANCH
Used in determining if new options were added
--format {json,plain}
Output format. Default: "plain"
--output OUTPUT Output location, use "-" for stdout. Default "-"
Extending validate-modules
==========================
The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/sanity/validate-modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``.
Codes
=====
Errors
------
========= ===================
code sample message
--------- -------------------
**1xx** **Locations**
101 Interpreter line is not ``#!/usr/bin/python``
102 Interpreter line is not ``#!powershell``
103 Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs only modules)
104 Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules)
105 GPLv3 license header not found
106 Import found before documentation variables. All imports must appear below
``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA``
107 Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA``
108 GPLv3 license header should be the :ref:`short form <copyright>` for new modules
109 Next to last line is not ``if __name__ == "__main__":``
..
--------- -------------------
**2xx** **Imports**
201 Did not find a ``module_utils`` import
203 ``requests`` import found, should use ``ansible.module_utils.urls`` instead
204 ``boto`` import found, new modules should use ``boto3``
205 ``sys.exit()`` call found. Should be ``exit_json``/``fail_json``
206 ``WANT_JSON`` not found in module
207 ``REPLACER_WINDOWS`` not found in module
208 ``module_utils`` imports should import specific components, not ``*``
209 Only the following ``from __future__`` imports are allowed:
``absolute_import``, ``division``, and ``print_function``.
210 ``subprocess.Popen`` used instead of ``module.run_command``
211 ``os.call`` used instead of ``module.run_command``
..
--------- -------------------
**3xx** **Documentation**
301 No ``DOCUMENTATION`` provided
302 ``DOCUMENTATION`` is not valid YAML
303 ``DOCUMENTATION`` fragment missing
304 Unknown ``DOCUMENTATION`` error
305 Invalid ``DOCUMENTATION`` schema
306 Module level ``version_added`` is not a valid version number
307 Module level ``version_added`` is incorrect
308 ``version_added`` for new option is not a valid version number
309 ``version_added`` for new option is incorrect
310 No ``EXAMPLES`` provided
311 ``EXAMPLES`` is not valid YAML
312 No ``RETURN`` documentation provided
313 ``RETURN`` is not valid YAML
314 No ``ANSIBLE_METADATA`` provided
315 ``ANSIBLE_METADATA`` was not provided as a dict, YAML not supported
316 Invalid ``ANSIBLE_METADATA`` schema
317 option is marked as required but specifies a default.
Arguments with a default should not be marked as required
318 Module deprecated, but DOCUMENTATION.deprecated is missing
319 ``RETURN`` fragments missing or invalid
320 ``DOCUMENTATION.options`` must be a dictionary/hash when used
321 ``Exception`` attempting to import module for ``argument_spec`` introspection
322 argument is listed in the argument_spec, but not documented in the module
323 argument is listed in DOCUMENTATION.options, but not accepted by the module
324 Value for "default" from the argument_spec does not match the documentation
325 argument_spec defines type="bool" but documentation does not
326 Value for "choices" from the argument_spec does not match the documentation
327 Default value from the documentation is not compatible with type defined in the argument_spec
328 Choices value from the documentation is not compatible with type defined in the argument_spec
329 Default value from the argument_spec is not compatible with type defined in the argument_spec
330 Choices value from the argument_spec is not compatible with type defined in the argument_spec
331 argument in argument_spec must be a dictionary/hash when used
332 ``AnsibleModule`` schema validation error
..
--------- -------------------
**4xx** **Syntax**
401 Python ``SyntaxError`` while parsing module
403 Type comparison using ``type()`` found. Use ``isinstance()`` instead
..
--------- -------------------
**5xx** **Naming**
501 Official Ansible modules must have a ``.py`` extension for python
modules or a ``.ps1`` for powershell modules
502 Ansible module subdirectories must contain an ``__init__.py``
503 Missing python documentation file
========= ===================
Warnings
--------
========= ===================
code sample message
--------- -------------------
**1xx** **Locations**
107 Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN``/``ANSIBLE_METADATA`` for legacy modules
..
--------- -------------------
**2xx** **Imports**
208 ``module_utils`` imports should import specific components for legacy module, not ``*``
291 Try/Except ``HAS_`` expression missing
292 Did not find ``ansible.module_utils.basic`` import
..
--------- -------------------
**3xx** **Documentation**
312 No ``RETURN`` documentation provided for legacy module
391 Unknown pre-existing ``DOCUMENTATION`` error
392 Pre-existing ``DOCUMENTATION`` fragment missing
========= ===================