1:orphan: 2 3.. _testing_validate-modules: 4 5**************** 6validate-modules 7**************** 8 9.. contents:: Topics 10 11Python program to help test or validate Ansible modules. 12 13``validate-modules`` is one of the ``ansible-test`` Sanity Tests, see :ref:`testing_sanity` for more information. 14 15Originally developed by Matt Martz (@sivel) 16 17 18Usage 19===== 20 21.. code:: shell 22 23 cd /path/to/ansible/source 24 source hacking/env-setup 25 ansible-test sanity --test validate-modules 26 27Help 28==== 29 30.. code:: shell 31 32 usage: validate-modules [-h] [-w] [--exclude EXCLUDE] [--arg-spec] 33 [--base-branch BASE_BRANCH] [--format {json,plain}] 34 [--output OUTPUT] 35 modules [modules ...] 36 37 positional arguments: 38 modules Path to module or module directory 39 40 optional arguments: 41 -h, --help show this help message and exit 42 -w, --warnings Show warnings 43 --exclude EXCLUDE RegEx exclusion pattern 44 --arg-spec Analyze module argument spec 45 --base-branch BASE_BRANCH 46 Used in determining if new options were added 47 --format {json,plain} 48 Output format. Default: "plain" 49 --output OUTPUT Output location, use "-" for stdout. Default "-" 50 51 52Extending validate-modules 53========================== 54 55The ``validate-modules`` tool has a `schema.py <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py>`_ that is used to validate the YAML blocks, such as ``DOCUMENTATION`` and ``RETURNS``. 56 57 58Codes 59===== 60 61============================================================ ================== ==================== ========================================================================================= 62 **Error Code** **Type** **Level** **Sample Message** 63------------------------------------------------------------ ------------------ -------------------- ----------------------------------------------------------------------------------------- 64 ansible-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier Ansible version 65 ansible-invalid-version Documentation Error The Ansible version at which a feature is supposed to be removed cannot be parsed 66 ansible-module-not-initialized Syntax Error Execution of the module did not result in initialization of AnsibleModule 67 collection-deprecated-version Documentation Error A feature is deprecated and supposed to be removed in the current or an earlier collection version 68 collection-invalid-version Documentation Error The collection version at which a feature is supposed to be removed cannot be parsed (it must be a semantic version, see https://semver.org/) 69 deprecated-date Documentation Error A date before today appears as ``removed_at_date`` or in ``deprecated_aliases`` 70 deprecation-mismatch Documentation Error Module marked as deprecated or removed in at least one of the filename, its metadata, or in DOCUMENTATION (setting DOCUMENTATION.deprecated for deprecation or removing all Documentation for removed) but not in all three places. 71 doc-choices-do-not-match-spec Documentation Error Value for "choices" from the argument_spec does not match the documentation 72 doc-choices-incompatible-type Documentation Error Choices value from the documentation is not compatible with type defined in the argument_spec 73 doc-default-does-not-match-spec Documentation Error Value for "default" from the argument_spec does not match the documentation 74 doc-default-incompatible-type Documentation Error Default value from the documentation is not compatible with type defined in the argument_spec 75 doc-elements-invalid Documentation Error Documentation specifies elements for argument, when "type" is not ``list``. 76 doc-elements-mismatch Documentation Error Argument_spec defines elements different than documentation does 77 doc-missing-type Documentation Error Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``) 78 doc-required-mismatch Documentation Error argument in argument_spec is required but documentation says it is not, or vice versa 79 doc-type-does-not-match-spec Documentation Error Argument_spec defines type different than documentation does 80 documentation-error Documentation Error Unknown ``DOCUMENTATION`` error 81 documentation-syntax-error Documentation Error Invalid ``DOCUMENTATION`` schema 82 illegal-future-imports Imports Error Only the following ``from __future__`` imports are allowed: ``absolute_import``, ``division``, and ``print_function``. 83 import-before-documentation Imports Error Import found before documentation variables. All imports must appear below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` 84 import-error Documentation Error ``Exception`` attempting to import module for ``argument_spec`` introspection 85 import-placement Locations Warning Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` 86 imports-improper-location Imports Error Imports should be directly below ``DOCUMENTATION``/``EXAMPLES``/``RETURN`` 87 incompatible-choices Documentation Error Choices value from the argument_spec is not compatible with type defined in the argument_spec 88 incompatible-default-type Documentation Error Default value from the argument_spec is not compatible with type defined in the argument_spec 89 invalid-argument-name Documentation Error Argument in argument_spec must not be one of 'message', 'syslog_facility' as it is used internally by Ansible Core Engine 90 invalid-argument-spec Documentation Error Argument in argument_spec must be a dictionary/hash when used 91 invalid-argument-spec-options Documentation Error Suboptions in argument_spec are invalid 92 invalid-documentation Documentation Error ``DOCUMENTATION`` is not valid YAML 93 invalid-documentation-options Documentation Error ``DOCUMENTATION.options`` must be a dictionary/hash when used 94 invalid-examples Documentation Error ``EXAMPLES`` is not valid YAML 95 invalid-extension Naming Error Official Ansible modules must have a ``.py`` extension for python modules or a ``.ps1`` for powershell modules 96 invalid-module-schema Documentation Error ``AnsibleModule`` schema validation error 97 invalid-requires-extension Naming Error Module ``#AnsibleRequires -CSharpUtil`` should not end in .cs, Module ``#Requires`` should not end in .psm1 98 invalid-tagged-version Documentation Error All version numbers specified in code have to be explicitly tagged with the collection name, in other words, ``community.general:1.2.3`` or ``ansible.builtin:2.10`` 99 last-line-main-call Syntax Error Call to ``main()`` not the last line (or ``removed_module()`` in the case of deprecated & docs only modules) 100 missing-doc-fragment Documentation Error ``DOCUMENTATION`` fragment missing 101 missing-existing-doc-fragment Documentation Warning Pre-existing ``DOCUMENTATION`` fragment missing 102 missing-documentation Documentation Error No ``DOCUMENTATION`` provided 103 missing-examples Documentation Error No ``EXAMPLES`` provided 104 missing-gplv3-license Documentation Error GPLv3 license header not found 105 missing-if-name-main Syntax Error Next to last line is not ``if __name__ == "__main__":`` 106 missing-main-call Syntax Error Did not find a call to ``main()`` (or ``removed_module()`` in the case of deprecated & docs only modules) 107 missing-module-utils-basic-import Imports Warning Did not find ``ansible.module_utils.basic`` import 108 missing-module-utils-import-csharp-requirements Imports Error No ``Ansible.ModuleUtils`` or C# Ansible util requirements/imports found 109 missing-powershell-interpreter Syntax Error Interpreter line is not ``#!powershell`` 110 missing-python-doc Naming Error Missing python documentation file 111 missing-python-interpreter Syntax Error Interpreter line is not ``#!/usr/bin/python`` 112 missing-return Documentation Error No ``RETURN`` documentation provided 113 missing-return-legacy Documentation Warning No ``RETURN`` documentation provided for legacy module 114 missing-suboption-docs Documentation Error Argument in argument_spec has sub-options but documentation does not define sub-options 115 module-incorrect-version-added Documentation Error Module level ``version_added`` is incorrect 116 module-invalid-version-added Documentation Error Module level ``version_added`` is not a valid version number 117 module-utils-specific-import Imports Error ``module_utils`` imports should import specific components, not ``*`` 118 multiple-utils-per-requires Imports Error ``Ansible.ModuleUtils`` requirements do not support multiple modules per statement 119 multiple-csharp-utils-per-requires Imports Error Ansible C# util requirements do not support multiple utils per statement 120 no-default-for-required-parameter Documentation Error Option is marked as required but specifies a default. Arguments with a default should not be marked as required 121 nonexistent-parameter-documented Documentation Error Argument is listed in DOCUMENTATION.options, but not accepted by the module 122 option-incorrect-version-added Documentation Error ``version_added`` for new option is incorrect 123 option-invalid-version-added Documentation Error ``version_added`` for option is not a valid version number 124 parameter-invalid Documentation Error Argument in argument_spec is not a valid python identifier 125 parameter-invalid-elements Documentation Error Value for "elements" is valid only when value of "type" is ``list`` 126 implied-parameter-type-mismatch Documentation Error Argument_spec implies ``type="str"`` but documentation defines it as different data type 127 parameter-type-not-in-doc Documentation Error Type value is defined in ``argument_spec`` but documentation doesn't specify a type 128 parameter-alias-repeated Parameters Error argument in argument_spec has at least one alias specified multiple times in aliases 129 parameter-alias-self Parameters Error argument in argument_spec is specified as its own alias 130 parameter-documented-multiple-times Documentation Error argument in argument_spec with aliases is documented multiple times 131 parameter-list-no-elements Parameters Error argument in argument_spec "type" is specified as ``list`` without defining "elements" 132 parameter-state-invalid-choice Parameters Error Argument ``state`` includes ``get``, ``list`` or ``info`` as a choice. Functionality should be in an ``_info`` or (if further conditions apply) ``_facts`` module. 133 python-syntax-error Syntax Error Python ``SyntaxError`` while parsing module 134 return-syntax-error Documentation Error ``RETURN`` is not valid YAML, ``RETURN`` fragments missing or invalid 135 return-invalid-version-added Documentation Error ``version_added`` for return value is not a valid version number 136 subdirectory-missing-init Naming Error Ansible module subdirectories must contain an ``__init__.py`` 137 try-except-missing-has Imports Warning Try/Except ``HAS_`` expression missing 138 undocumented-parameter Documentation Error Argument is listed in the argument_spec, but not documented in the module 139 unidiomatic-typecheck Syntax Error Type comparison using ``type()`` found. Use ``isinstance()`` instead 140 unknown-doc-fragment Documentation Warning Unknown pre-existing ``DOCUMENTATION`` error 141 use-boto3 Imports Error ``boto`` import found, new modules should use ``boto3`` 142 use-fail-json-not-sys-exit Imports Error ``sys.exit()`` call found. Should be ``exit_json``/``fail_json`` 143 use-module-utils-urls Imports Error ``requests`` import found, should use ``ansible.module_utils.urls`` instead 144 use-run-command-not-os-call Imports Error ``os.call`` used instead of ``module.run_command`` 145 use-run-command-not-popen Imports Error ``subprocess.Popen`` used instead of ``module.run_command`` 146 use-short-gplv3-license Documentation Error GPLv3 license header should be the :ref:`short form <copyright>` for new modules 147 mutually_exclusive-type Documentation Error mutually_exclusive entry contains non-string value 148 mutually_exclusive-collision Documentation Error mutually_exclusive entry has repeated terms 149 mutually_exclusive-unknown Documentation Error mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?) 150 required_one_of-type Documentation Error required_one_of entry contains non-string value 151 required_one_of-collision Documentation Error required_one_of entry has repeated terms 152 required_one_of-unknown Documentation Error required_one_of entry contains option which does not appear in argument_spec (potentially an alias of an option?) 153 required_together-type Documentation Error required_together entry contains non-string value 154 required_together-collision Documentation Error required_together entry has repeated terms 155 required_together-unknown Documentation Error required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?) 156 required_if-is_one_of-type Documentation Error required_if entry has a fourth value which is not a bool 157 required_if-requirements-type Documentation Error required_if entry has a third value (requirements) which is not a list or tuple 158 required_if-requirements-collision Documentation Error required_if entry has repeated terms in requirements 159 required_if-requirements-unknown Documentation Error required_if entry's requirements contains option which does not appear in argument_spec (potentially an alias of an option?) 160 required_if-unknown-key Documentation Error required_if entry's key does not appear in argument_spec (potentially an alias of an option?) 161 required_if-key-in-requirements Documentation Error required_if entry contains its key in requirements list/tuple 162 required_if-value-type Documentation Error required_if entry's value is not of the type specified for its key 163 required_by-collision Documentation Error required_by entry has repeated terms 164 required_by-unknown Documentation Error required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?) 165============================================================ ================== ==================== ========================================================================================= 166