# validate-modules

Topics

- validate-modules
  - Usage
  - Help
  - Extending validate-modules
  - Codes
    - Errors
    - Warnings

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

### 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()` (or `removed_module()` in the case of deprecated & docs only modules)
104 | Call to `main()` not the last line (or `removed_module()` in the case of deprecated & docs only modules)
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`
108 | GPLv3 license header should be the short form for new modules
109 | Next to last line is not `if __name__ == "__main__":`
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 `*`
209 | Only the following `from __future__` imports are allowed: `absolute_import`, `division`, and `print_function`.
210 | `subprocess.Popen` used instead of `module.run_command`
211 | `os.call` used instead of `module.run_command`
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` was not provided as a dict, YAML not supported
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 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.
319 | `RETURN` fragments missing or invalid
320 | `DOCUMENTATION.options` must be a dictionary/hash when used
321 | `Exception` attempting to import module for `argument_spec` introspection
322 | argument is listed in the argument_spec, but not documented in the module
323 | argument is listed in DOCUMENTATION.options, but not accepted by the module
324 | Value for “default” from the argument_spec does not match the documentation
325 | argument_spec defines type=”bool” but documentation does not
326 | Value for “choices” from the argument_spec does not match the documentation
327 | Default value from the documentation is not compatible with type defined in the argument_spec
328 | Choices value from the documentation is not compatible with type defined in the argument_spec
329 | Default value from the argument_spec is not compatible with type defined in the argument_spec
330 | Choices value from the argument_spec is not compatible with type defined in the argument_spec
331 | argument in argument_spec must be a dictionary/hash when used
332 | `AnsibleModule` schema validation error
333 | `ANSIBLE_METADATA.status` of deprecated or removed can’t include other statuses
334 | `ANSIBLE_METADATA` cannot be changed in a point release for a stable branch
4xx | Syntax
401 | Python `SyntaxError` while parsing module
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