# 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

### 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