validate-modules¶
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-deprecated-version |
Documentation |
Error |
A feature is deprecated and supposed to be removed in the current or an earlier Ansible version |
ansible-invalid-version |
Documentation |
Error |
The Ansible version at which a feature is supposed to be removed cannot be parsed |
ansible-module-not-initialized |
Syntax |
Error |
Execution of the module did not result in initialization of AnsibleModule |
collection-deprecated-version |
Documentation |
Error |
A feature is deprecated and supposed to be removed in the current or an earlier collection version |
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/) |
deprecated-date |
Documentation |
Error |
A date before today appears as |
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-elements-invalid |
Documentation |
Error |
Documentation specifies elements for argument, when “type” is not |
doc-elements-mismatch |
Documentation |
Error |
Argument_spec defines elements different than documentation does |
doc-missing-type |
Documentation |
Error |
Documentation doesn’t specify a type but argument in |
doc-required-mismatch |
Documentation |
Error |
argument in argument_spec is required but documentation says it is not, or vice versa |
doc-type-does-not-match-spec |
Documentation |
Error |
Argument_spec defines type different than documentation does |
documentation-error |
Documentation |
Error |
Unknown |
documentation-syntax-error |
Documentation |
Error |
Invalid |
illegal-future-imports |
Imports |
Error |
Only the following |
import-before-documentation |
Imports |
Error |
Import found before documentation variables. All imports must appear below |
import-error |
Documentation |
Error |
|
import-placement |
Locations |
Warning |
Imports should be directly below |
imports-improper-location |
Imports |
Error |
Imports should be directly below |
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-name |
Documentation |
Error |
Argument in argument_spec must not be one of ‘message’, ‘syslog_facility’ as it is used internally by Ansible Core Engine |
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 |
|
invalid-documentation-options |
Documentation |
Error |
|
invalid-examples |
Documentation |
Error |
|
invalid-extension |
Naming |
Error |
Official Ansible modules must have a |
invalid-module-schema |
Documentation |
Error |
|
invalid-requires-extension |
Naming |
Error |
Module |
invalid-tagged-version |
Documentation |
Error |
All version numbers specified in code have to be explicitly tagged with the collection name, in other words, |
last-line-main-call |
Syntax |
Error |
Call to |
missing-doc-fragment |
Documentation |
Error |
|
missing-existing-doc-fragment |
Documentation |
Warning |
Pre-existing |
missing-documentation |
Documentation |
Error |
No |
missing-examples |
Documentation |
Error |
No |
missing-gplv3-license |
Documentation |
Error |
GPLv3 license header not found |
missing-if-name-main |
Syntax |
Error |
Next to last line is not |
missing-main-call |
Syntax |
Error |
Did not find a call to |
missing-module-utils-basic-import |
Imports |
Warning |
Did not find |
missing-module-utils-import-csharp-requirements |
Imports |
Error |
No |
missing-powershell-interpreter |
Syntax |
Error |
Interpreter line is not |
missing-python-doc |
Naming |
Error |
Missing python documentation file |
missing-python-interpreter |
Syntax |
Error |
Interpreter line is not |
missing-return |
Documentation |
Error |
No |
missing-return-legacy |
Documentation |
Warning |
No |
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 |
module-invalid-version-added |
Documentation |
Error |
Module level |
module-utils-specific-import |
Imports |
Error |
|
multiple-utils-per-requires |
Imports |
Error |
|
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 |
|
option-invalid-version-added |
Documentation |
Error |
|
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 |
implied-parameter-type-mismatch |
Documentation |
Error |
Argument_spec implies |
parameter-type-not-in-doc |
Documentation |
Error |
Type value is defined in |
parameter-alias-repeated |
Parameters |
Error |
argument in argument_spec has at least one alias specified multiple times in aliases |
parameter-alias-self |
Parameters |
Error |
argument in argument_spec is specified as its own alias |
parameter-documented-multiple-times |
Documentation |
Error |
argument in argument_spec with aliases is documented multiple times |
parameter-list-no-elements |
Parameters |
Error |
argument in argument_spec “type” is specified as |
parameter-state-invalid-choice |
Parameters |
Error |
Argument |
python-syntax-error |
Syntax |
Error |
Python |
return-syntax-error |
Documentation |
Error |
|
return-invalid-version-added |
Documentation |
Error |
|
subdirectory-missing-init |
Naming |
Error |
Ansible module subdirectories must contain an |
try-except-missing-has |
Imports |
Warning |
Try/Except |
undocumented-parameter |
Documentation |
Error |
Argument is listed in the argument_spec, but not documented in the module |
unidiomatic-typecheck |
Syntax |
Error |
Type comparison using |
unknown-doc-fragment |
Documentation |
Warning |
Unknown pre-existing |
use-boto3 |
Imports |
Error |
|
use-fail-json-not-sys-exit |
Imports |
Error |
|
use-module-utils-urls |
Imports |
Error |
|
use-run-command-not-os-call |
Imports |
Error |
|
use-run-command-not-popen |
Imports |
Error |
|
use-short-gplv3-license |
Documentation |
Error |
GPLv3 license header should be the short form for new modules |
mutually_exclusive-type |
Documentation |
Error |
mutually_exclusive entry contains non-string value |
mutually_exclusive-collision |
Documentation |
Error |
mutually_exclusive entry has repeated terms |
mutually_exclusive-unknown |
Documentation |
Error |
mutually_exclusive entry contains option which does not appear in argument_spec (potentially an alias of an option?) |
required_one_of-type |
Documentation |
Error |
required_one_of entry contains non-string value |
required_one_of-collision |
Documentation |
Error |
required_one_of entry has repeated terms |
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?) |
required_together-type |
Documentation |
Error |
required_together entry contains non-string value |
required_together-collision |
Documentation |
Error |
required_together entry has repeated terms |
required_together-unknown |
Documentation |
Error |
required_together entry contains option which does not appear in argument_spec (potentially an alias of an option?) |
required_if-is_one_of-type |
Documentation |
Error |
required_if entry has a fourth value which is not a bool |
required_if-requirements-type |
Documentation |
Error |
required_if entry has a third value (requirements) which is not a list or tuple |
required_if-requirements-collision |
Documentation |
Error |
required_if entry has repeated terms in requirements |
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?) |
required_if-unknown-key |
Documentation |
Error |
required_if entry’s key does not appear in argument_spec (potentially an alias of an option?) |
required_if-key-in-requirements |
Documentation |
Error |
required_if entry contains its key in requirements list/tuple |
required_if-value-type |
Documentation |
Error |
required_if entry’s value is not of the type specified for its key |
required_by-collision |
Documentation |
Error |
required_by entry has repeated terms |
required_by-unknown |
Documentation |
Error |
required_by entry contains option which does not appear in argument_spec (potentially an alias of an option?) |