ansible/docs/docsite/rst/dev_guide/testing_validate-modules.rst

****************
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()``                                                                                                          |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| 104     | Call to ``main()`` not the last line                                                                                                       |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| 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``                                            |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| **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 ``*``                                                                      |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| **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`` is not valid YAML                                                                                                     |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| 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                                                                                                   |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| **4xx** | **Syntax**                                                                                                                                 |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| 401     | Python ``SyntaxError`` while parsing module                                                                                                |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| 402     | Indentation contains tabs                                                                                                                  |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+
| 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                                                                                            |
+---------+--------------------------------------------------------------------------------------------------------------------------------------------+