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-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 |
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-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-metadata-status |
Documentation |
Error |
|
invalid-metadata-type |
Documentation |
Error |
|
invalid-module-schema |
Documentation |
Error |
|
invalid-requires-extension |
Naming |
Error |
Module |
last-line-main-call |
Syntax |
Error |
Call to |
metadata-changed |
Documentation |
Error |
|
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-metadata |
Documentation |
Error |
No |
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 |
python-syntax-error |
Syntax |
Error |
Python |
return-syntax-error |
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 |