# validate-modules

Topics

- validate-modules
  - Usage
  - Help
  - Extending validate-modules
  - Codes

Python program to help test or validate Ansible modules.

`validate-modules` is one of the `ansible-test` Sanity Tests, see Sanity Tests for more information.

Originally developed by Matt Martz (@sivel)

## Usage

    cd /path/to/ansible/source
    source hacking/env-setup
    ansible-test sanity --test validate-modules

## Help

    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 that is used to validate the YAML blocks, such as `DOCUMENTATION` and `RETURNS`.

## Codes

Error Code | Type | Level | Sample Message
ansible-module-not-initialized | Syntax | Error | Execution of the module did not result in initialization of AnsibleModule
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.
doc-choices-do-not-match-spec | Documentation | Error | Value for “choices” from the argument_spec does not match the documentation
doc-choices-incompatible-type | Documentation | Error | Choices value from the documentation is not compatible with type defined in the argument_spec
doc-default-does-not-match-spec | Documentation | Error | Value for “default” from the argument_spec does not match the documentation
doc-default-incompatible-type | Documentation | Error | Default value from the documentation is not compatible with type defined in the argument_spec
doc-missing-type | Documentation | Error | Documentation doesn’t specify a type but argument in `argument_spec` use default type (`str`)
doc-type-does-not-match-spec | Documentation | Error | Argument_spec defines type different than documentation does
documentation-error | Documentation | Error | Unknown `DOCUMENTATION` error
documentation-syntax-error | Documentation | Error | Invalid `DOCUMENTATION` schema
illegal-future-imports | Imports | Error | Only the following `from __future__` imports are allowed: `absolute_import`, `division`, and `print_function`.
import-before-documentation | Imports | Error | Import found before documentation variables. All imports must appear below `DOCUMENTATION`/`EXAMPLES`/`RETURN`/`ANSIBLE_METADATA`
import-error | Documentation | Error | `Exception` attempting to import module for `argument_spec` introspection
import-placement | Locations | Warning | Imports should be directly below `DOCUMENTATION`/`EXAMPLES`/`RETURN`/`ANSIBLE_METADATA` for legacy modules
imports-improper-location | Imports | Error | Imports should be directly below `DOCUMENTATION`/`EXAMPLES`/`RETURN`/`ANSIBLE_METADATA`
incompatible-choices | Documentation | Error | Choices value from the argument_spec is not compatible with type defined in the argument_spec
incompatible-default-type | Documentation | Error | Default value from the argument_spec is not compatible with type defined in the argument_spec
invalid-argument-spec | Documentation | Error | Argument in argument_spec must be a dictionary/hash when used
invalid-argument-spec-options | Documentation | Error | Suboptions in argument_spec are invalid
invalid-documentation | Documentation | Error | `DOCUMENTATION` is not valid YAML
invalid-documentation-options | Documentation | Error | `DOCUMENTATION.options` must be a dictionary/hash when used
invalid-examples | Documentation | Error | `EXAMPLES` is not valid YAML
invalid-extension | Naming | Error | Official Ansible modules must have a `.py` extension for python modules or a `.ps1` for powershell modules
invalid-metadata-status | Documentation | Error | `ANSIBLE_METADATA.status` of deprecated or removed can’t include other statuses
invalid-metadata-type | Documentation | Error | `ANSIBLE_METADATA` was not provided as a dict, YAML not supported, Invalid `ANSIBLE_METADATA` schema
invalid-module-schema | Documentation | Error | `AnsibleModule` schema validation error
invalid-requires-extension | Naming | Error | Module `#AnsibleRequires -CSharpUtil` should not end in .cs, Module `#Requires` should not end in .psm1
last-line-main-call | Syntax | Error | Call to `main()` not the last line (or `removed_module()` in the case of deprecated & docs only modules)
metadata-changed | Documentation | Error | `ANSIBLE_METADATA` cannot be changed in a point release for a stable branch
missing-doc-fragment | Documentation | Error | `DOCUMENTATION` fragment missing
missing-existing-doc-fragment | Documentation | Warning | Pre-existing `DOCUMENTATION` fragment missing
missing-documentation | Documentation | Error | No `DOCUMENTATION` provided
missing-examples | Documentation | Error | No `EXAMPLES` provided
missing-gplv3-license | Documentation | Error | GPLv3 license header not found
missing-if-name-main | Syntax | Error | Next to last line is not `if __name__ == "__main__":`
missing-main-call | Syntax | Error | Did not find a call to `main()` (or `removed_module()` in the case of deprecated & docs only modules)
missing-metadata | Documentation | Error | No `ANSIBLE_METADATA` provided
missing-module-utils-basic-import | Imports | Warning | Did not find `ansible.module_utils.basic` import
missing-module-utils-import-csharp-requirements | Imports | Error | No `Ansible.ModuleUtils` or C# Ansible util requirements/imports found
missing-powershell-interpreter | Syntax | Error | Interpreter line is not `#!powershell`
missing-python-doc | Naming | Error | Missing python documentation file
missing-python-interpreter | Syntax | Error | Interpreter line is not `#!/usr/bin/python`
missing-return | Documentation | Error | No `RETURN` documentation provided
missing-return-legacy | Documentation | Warning | No `RETURN` documentation provided for legacy module
missing-suboption-docs | Documentation | Error | Argument in argument_spec has sub-options but documentation does not define sub-options
module-incorrect-version-added | Documentation | Error | Module level `version_added` is incorrect
module-invalid-version-added | Documentation | Error | Module level `version_added` is not a valid version number
module-utils-specific-import | Imports | Error | `module_utils` imports should import specific components, not `*`
multiple-utils-per-requires | Imports | Error | `Ansible.ModuleUtils` requirements do not support multiple modules per statement
multiple-csharp-utils-per-requires | Imports | Error | Ansible C# util requirements do not support multiple utils per statement
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
nonexistent-parameter-documented | Documentation | Error | Argument is listed in DOCUMENTATION.options, but not accepted by the module
option-incorrect-version-added | Documentation | Error | `version_added` for new option is incorrect
option-invalid-version-added | Documentation | Error | `version_added` for new option is not a valid version number
parameter-invalid | Documentation | Error | Argument in argument_spec is not a valid python identifier
parameter-invalid-elements | Documentation | Error | Value for “elements” is valid only when value of “type” is `list`
implied-parameter-type-mismatch | Documentation | Error | Argument_spec implies `type="str"` but documentation defines it as different data type
parameter-type-not-in-doc | Documentation | Error | Type value is defined in `argument_spec` but documentation doesn’t specify a type
python-syntax-error | Syntax | Error | Python `SyntaxError` while parsing module
return-syntax-error | Documentation | Error | `RETURN` is not valid YAML, `RETURN` fragments missing or invalid
subdirectory-missing-init | Naming | Error | Ansible module subdirectories must contain an `__init__.py`
try-except-missing-has | Imports | Warning | Try/Except `HAS_` expression missing
undocumented-parameter | Documentation | Error | Argument is listed in the argument_spec, but not documented in the module
unidiomatic-typecheck | Syntax | Error | Type comparison using `type()` found. Use `isinstance()` instead
unknown-doc-fragment | Documentation | Warning | Unknown pre-existing `DOCUMENTATION` error
use-boto3 | Imports | Error | `boto` import found, new modules should use `boto3`
use-fail-json-not-sys-exit | Imports | Error | `sys.exit()` call found. Should be `exit_json`/`fail_json`
use-module-utils-urls | Imports | Error | `requests` import found, should use `ansible.module_utils.urls` instead
use-run-command-not-os-call | Imports | Error | `os.call` used instead of `module.run_command`
use-run-command-not-popen | Imports | Error | `subprocess.Popen` used instead of `module.run_command`
use-short-gplv3-license | Documentation | Error | GPLv3 license header should be the short form for new modules