diff options
Diffstat (limited to 'test/integration/targets/ansible-doc')
29 files changed, 1016 insertions, 0 deletions
diff --git a/test/integration/targets/ansible-doc/aliases b/test/integration/targets/ansible-doc/aliases new file mode 100644 index 00000000..a6dafcf8 --- /dev/null +++ b/test/integration/targets/ansible-doc/aliases @@ -0,0 +1 @@ +shippable/posix/group1 diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/MANIFEST.json b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/MANIFEST.json new file mode 100644 index 00000000..243a5e43 --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/MANIFEST.json @@ -0,0 +1,30 @@ +{ + "collection_info": { + "description": null, + "repository": "", + "tags": [], + "dependencies": {}, + "authors": [ + "Ansible (https://ansible.com)" + ], + "issues": "", + "name": "testcol", + "license": [ + "GPL-3.0-or-later" + ], + "documentation": "", + "namespace": "testns", + "version": "0.1.1231", + "readme": "README.md", + "license_file": "COPYING", + "homepage": "", + }, + "file_manifest_file": { + "format": 1, + "ftype": "file", + "chksum_sha256": "4c15a867ceba8ba1eaf2f4a58844bb5dbb82fec00645fc7eb74a3d31964900f6", + "name": "FILES.json", + "chksum_type": "sha256" + }, + "format": 1 +} diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py new file mode 100644 index 00000000..ee56f6ee --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/cache/notjsonfile.py @@ -0,0 +1,49 @@ +# (c) 2020 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +# Make coding more python3-ish +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = ''' + cache: notjsonfile + short_description: JSON formatted files. + description: + - This cache uses JSON formatted, per host, files saved to the filesystem. + author: Ansible Core (@ansible-core) + options: + _uri: + required: True + description: + - Path in which the cache plugin will save the JSON files + env: + - name: ANSIBLE_CACHE_PLUGIN_CONNECTION + ini: + - key: fact_caching_connection + section: defaults + _prefix: + description: User defined prefix to use when creating the JSON files + env: + - name: ANSIBLE_CACHE_PLUGIN_PREFIX + ini: + - key: fact_caching_prefix + section: defaults + _timeout: + default: 86400 + description: Expiration timeout for the cache plugin data + env: + - name: ANSIBLE_CACHE_PLUGIN_TIMEOUT + ini: + - key: fact_caching_timeout + section: defaults + type: integer +''' + +from ansible.plugins.cache import BaseFileCacheModule + + +class CacheModule(BaseFileCacheModule): + """ + A caching module backed by json files. + """ + pass diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py new file mode 100644 index 00000000..cbb8f0fb --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/inventory/statichost.py @@ -0,0 +1,35 @@ +# Copyright (c) 2018 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = ''' + inventory: statichost + short_description: Add a single host + description: Add a single host + extends_documentation_fragment: + - inventory_cache + options: + plugin: + description: plugin name (must be statichost) + required: true + hostname: + description: Toggle display of stderr even when script was successful + required: True +''' + +from ansible.errors import AnsibleParserError +from ansible.plugins.inventory import BaseInventoryPlugin, Cacheable + + +class InventoryModule(BaseInventoryPlugin, Cacheable): + + NAME = 'testns.content_adj.statichost' + + def verify_file(self, path): + pass + + def parse(self, inventory, loader, path, cache=None): + + pass diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py new file mode 100644 index 00000000..daecac5d --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/lookup/noop.py @@ -0,0 +1,37 @@ +# (c) 2020 Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) + +# Make coding more python3-ish +from __future__ import (absolute_import, division, print_function) + +__metaclass__ = type + +DOCUMENTATION = """ + lookup: noop + author: Ansible core team + short_description: returns input + description: + - this is a noop +""" + +EXAMPLES = """ +- name: do nothing + debug: msg="{{ lookup('testns.testcol.noop', [1,2,3,4] }}" +""" + +RETURN = """ + _list: + description: input given +""" + +from ansible.module_utils.common._collections_compat import Sequence +from ansible.plugins.lookup import LookupBase +from ansible.errors import AnsibleError + + +class LookupModule(LookupBase): + + def run(self, terms, **kwargs): + if not isinstance(terms, Sequence): + raise AnsibleError("testns.testcol.noop expects a list") + return terms diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/fakemodule.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/fakemodule.py new file mode 100644 index 00000000..decdbef4 --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/fakemodule.py @@ -0,0 +1,26 @@ +#!/usr/bin/python +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +DOCUMENTATION = """ + module: fakemodule + short_desciptoin: fake module + description: + - this is a fake module + options: + _notreal: + description: really not a real option + author: + - me +""" + +import json + + +def main(): + print(json.dumps(dict(changed=False, source='testns.testcol.fakemodule'))) + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/notrealmodule.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/notrealmodule.py new file mode 100644 index 00000000..4479f23f --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/modules/notrealmodule.py @@ -0,0 +1,13 @@ +#!/usr/bin/python +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +import json + + +def main(): + print(json.dumps(dict(changed=False, source='testns.testcol.notrealmodule'))) + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py new file mode 100644 index 00000000..ccb33b04 --- /dev/null +++ b/test/integration/targets/ansible-doc/collections/ansible_collections/testns/testcol/plugins/vars/noop_vars_plugin.py @@ -0,0 +1,27 @@ +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + +DOCUMENTATION = ''' + vars: noop_vars_plugin + short_description: Do NOT load host and group vars + description: don't test loading host and group vars from a collection + options: + stage: + default: all + choices: ['all', 'inventory', 'task'] + type: str + ini: + - key: stage + section: testns.testcol.noop_vars_plugin + env: + - name: ANSIBLE_VARS_PLUGIN_STAGE +''' + +from ansible.plugins.vars import BaseVarsPlugin + + +class VarsModule(BaseVarsPlugin): + + def get_vars(self, loader, path, entities, cache=True): + super(VarsModule, self).get_vars(loader, path, entities) + return {'collection': 'yes', 'notreal': 'value'} diff --git a/test/integration/targets/ansible-doc/fakemodule.output b/test/integration/targets/ansible-doc/fakemodule.output new file mode 100644 index 00000000..adc27e08 --- /dev/null +++ b/test/integration/targets/ansible-doc/fakemodule.output @@ -0,0 +1,15 @@ +> TESTNS.TESTCOL.FAKEMODULE (./collections/ansible_collections/testns/testcol/plugins/modules/fakemodule.py) + + this is a fake module + +OPTIONS (= is mandatory): + +- _notreal + really not a real option + [Default: (null)] + + +AUTHOR: me + +SHORT_DESCIPTOIN: fake module + diff --git a/test/integration/targets/ansible-doc/inventory b/test/integration/targets/ansible-doc/inventory new file mode 100644 index 00000000..ab9b62c8 --- /dev/null +++ b/test/integration/targets/ansible-doc/inventory @@ -0,0 +1 @@ +not_empty # avoid empty empty hosts list warning without defining explicit localhost diff --git a/test/integration/targets/ansible-doc/library/test_docs.py b/test/integration/targets/ansible-doc/library/test_docs.py new file mode 100644 index 00000000..39ae3728 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs.py @@ -0,0 +1,39 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['stableinterface'], + 'supported_by': 'core'} + +DOCUMENTATION = ''' +--- +module: test_docs +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_missing_description.py b/test/integration/targets/ansible-doc/library/test_docs_missing_description.py new file mode 100644 index 00000000..6ed41836 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_missing_description.py @@ -0,0 +1,40 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_returns +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +options: + test: + type: str +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict( + test=dict(type='str'), + ), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_no_metadata.py b/test/integration/targets/ansible-doc/library/test_docs_no_metadata.py new file mode 100644 index 00000000..4ea86f02 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_no_metadata.py @@ -0,0 +1,35 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_no_metadata +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_no_status.py b/test/integration/targets/ansible-doc/library/test_docs_no_status.py new file mode 100644 index 00000000..1b0db4e9 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_no_status.py @@ -0,0 +1,38 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'supported_by': 'core'} + +DOCUMENTATION = ''' +--- +module: test_docs_no_status +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_non_iterable_status.py b/test/integration/targets/ansible-doc/library/test_docs_non_iterable_status.py new file mode 100644 index 00000000..63d080f6 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_non_iterable_status.py @@ -0,0 +1,39 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': 1, + 'supported_by': 'core'} + +DOCUMENTATION = ''' +--- +module: test_docs_non_iterable_status +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py b/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py new file mode 100644 index 00000000..3de1c690 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_removed_precedence.py @@ -0,0 +1,40 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_removed_precedence +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +deprecated: + alternative: new_module + why: Updated module released with more functionality + removed_at_date: '2022-06-01' + removed_in: '2.14' +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_removed_status.py b/test/integration/targets/ansible-doc/library/test_docs_removed_status.py new file mode 100644 index 00000000..cb48c169 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_removed_status.py @@ -0,0 +1,39 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['removed'], + 'supported_by': 'core'} + +DOCUMENTATION = ''' +--- +module: test_docs_removed_status +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_returns.py b/test/integration/targets/ansible-doc/library/test_docs_returns.py new file mode 100644 index 00000000..77c13764 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_returns.py @@ -0,0 +1,56 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_returns +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +z_last: + description: A last result. + type: str + returned: success + +m_middle: + description: + - This should be in the middle. + - Has some more data + type: dict + returned: success and 1st of month + contains: + suboption: + description: A suboption. + type: str + choices: [ARF, BARN, c_without_capital_first_letter] + +a_first: + description: A first result. + type: str + returned: success +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_returns_broken.py b/test/integration/targets/ansible-doc/library/test_docs_returns_broken.py new file mode 100644 index 00000000..d6d62643 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_returns_broken.py @@ -0,0 +1,40 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_returns_broken +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +test: + description: A test return value. + type: str + +broken_key: [ +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_docs_suboptions.py b/test/integration/targets/ansible-doc/library/test_docs_suboptions.py new file mode 100644 index 00000000..c922d1d6 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_docs_suboptions.py @@ -0,0 +1,70 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +DOCUMENTATION = ''' +--- +module: test_docs_suboptions +short_description: Test module +description: + - Test module +author: + - Ansible Core Team +options: + with_suboptions: + description: + - An option with suboptions. + - Use with care. + type: dict + suboptions: + z_last: + description: The last suboption. + type: str + m_middle: + description: + - The suboption in the middle. + - Has its own suboptions. + suboptions: + a_suboption: + description: A sub-suboption. + type: str + a_first: + description: The first suboption. + type: str +''' + +EXAMPLES = ''' +''' + +RETURN = ''' +''' + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict( + test_docs_suboptions=dict( + type='dict', + options=dict( + a_first=dict(type='str'), + m_middle=dict( + type='dict', + options=dict( + a_suboption=dict(type='str') + ), + ), + z_last=dict(type='str'), + ), + ), + ), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_empty.py b/test/integration/targets/ansible-doc/library/test_empty.py new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_empty.py diff --git a/test/integration/targets/ansible-doc/library/test_no_docs.py b/test/integration/targets/ansible-doc/library/test_no_docs.py new file mode 100644 index 00000000..5503aedb --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_no_docs.py @@ -0,0 +1,23 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['stableinterface'], + 'supported_by': 'core'} + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_no_docs_no_metadata.py b/test/integration/targets/ansible-doc/library/test_no_docs_no_metadata.py new file mode 100644 index 00000000..48872684 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_no_docs_no_metadata.py @@ -0,0 +1,18 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_no_docs_no_status.py b/test/integration/targets/ansible-doc/library/test_no_docs_no_status.py new file mode 100644 index 00000000..f90c5c71 --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_no_docs_no_status.py @@ -0,0 +1,22 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'supported_by': 'core'} + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/library/test_no_docs_non_iterable_status.py b/test/integration/targets/ansible-doc/library/test_no_docs_non_iterable_status.py new file mode 100644 index 00000000..44fbedee --- /dev/null +++ b/test/integration/targets/ansible-doc/library/test_no_docs_non_iterable_status.py @@ -0,0 +1,23 @@ +#!/usr/bin/python +from __future__ import absolute_import, division, print_function +__metaclass__ = type + + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': 1, + 'supported_by': 'core'} + + +from ansible.module_utils.basic import AnsibleModule + + +def main(): + module = AnsibleModule( + argument_spec=dict(), + ) + + module.exit_json() + + +if __name__ == '__main__': + main() diff --git a/test/integration/targets/ansible-doc/runme.sh b/test/integration/targets/ansible-doc/runme.sh new file mode 100755 index 00000000..b5929f60 --- /dev/null +++ b/test/integration/targets/ansible-doc/runme.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash + +set -eux +ansible-playbook test.yml -i inventory "$@" + +( +unset ANSIBLE_PLAYBOOK_DIR +cd "$(dirname "$0")" + +# test module docs from collection +current_out="$(ansible-doc --playbook-dir ./ testns.testcol.fakemodule)" +expected_out="$(cat fakemodule.output)" +test "$current_out" == "$expected_out" + +# ensure we do work with valid collection name for list +ansible-doc --list testns.testcol --playbook-dir ./ 2>&1 | grep -v "Invalid collection pattern" + +# ensure we dont break on invalid collection name for list +ansible-doc --list testns.testcol.fakemodule --playbook-dir ./ 2>&1 | grep "Invalid collection pattern" + + +# test listing diff plugin types from collection +for ptype in cache inventory lookup vars +do + # each plugin type adds 1 from collection + # FIXME pre=$(ansible-doc -l -t ${ptype}|wc -l) + # FIXME post=$(ansible-doc -l -t ${ptype} --playbook-dir ./|wc -l) + # FIXME test "$pre" -eq $((post - 1)) + + # ensure we ONLY list from the collection + justcol=$(ansible-doc -l -t ${ptype} --playbook-dir ./ testns.testcol|wc -l) + test "$justcol" -eq 1 + + # ensure we get 0 plugins when restricting to collection, but not supplying it + justcol=$(ansible-doc -l -t ${ptype} testns.testcol|wc -l) + test "$justcol" -eq 0 + + # ensure we get 1 plugins when restricting namespace + justcol=$(ansible-doc -l -t ${ptype} --playbook-dir ./ testns|wc -l) + test "$justcol" -eq 1 +done +) diff --git a/test/integration/targets/ansible-doc/test.yml b/test/integration/targets/ansible-doc/test.yml new file mode 100644 index 00000000..a077a994 --- /dev/null +++ b/test/integration/targets/ansible-doc/test.yml @@ -0,0 +1,138 @@ +- hosts: localhost + gather_facts: no + environment: + ANSIBLE_LIBRARY: "{{ playbook_dir }}/library" + tasks: + - name: module with missing description return docs + command: ansible-doc test_docs_missing_description + register: result + ignore_errors: true + + - assert: + that: + - result is failed + - | + "ERROR! Unable to retrieve documentation from 'test_docs_missing_description' due to: All (sub-)options and return values must have a 'description' field" + in result.stderr + + - name: module with suboptions + command: ansible-doc test_docs_suboptions + register: result + ignore_errors: true + + - set_fact: + actual_output: >- + {{ result.stdout | regex_replace('^(> [A-Z_]+ +\().+library/([a-z_]+.py)\)$', '\1library/\2)', multiline=true) }} + expected_output: "{{ lookup('file', 'test_docs_suboptions.output') }}" + + - assert: + that: + - result is succeeded + - actual_output == expected_output + + - name: module with return docs + command: ansible-doc test_docs_returns + register: result + ignore_errors: true + + - set_fact: + actual_output: >- + {{ result.stdout | regex_replace('^(> [A-Z_]+ +\().+library/([a-z_]+.py)\)$', '\1library/\2)', multiline=true) }} + expected_output: "{{ lookup('file', 'test_docs_returns.output') }}" + + - assert: + that: + - result is succeeded + - actual_output == expected_output + + - name: module with broken return docs + command: ansible-doc test_docs_returns_broken + register: result + ignore_errors: true + + - assert: + that: + - result is failed + - '"ERROR! module test_docs_returns_broken missing documentation (or could not parse documentation)" in result.stderr' + + - name: non-existent module + command: ansible-doc test_does_not_exist + register: result + - assert: + that: + - '"[WARNING]: module test_does_not_exist not found in:" in result.stderr' + + - name: documented module + command: ansible-doc test_docs + register: result + - assert: + that: + - '"WARNING" not in result.stderr' + - '"TEST_DOCS " in result.stdout' + - '"AUTHOR: Ansible Core Team" in result.stdout' + + - name: documented module without metadata + command: ansible-doc test_docs_no_metadata + register: result + - assert: + that: + - '"WARNING" not in result.stderr' + - '"TEST_DOCS_NO_METADATA " in result.stdout' + - '"AUTHOR: Ansible Core Team" in result.stdout' + + - name: documented module with no status in metadata + command: ansible-doc test_docs_no_status + register: result + - assert: + that: + - '"WARNING" not in result.stderr' + - '"TEST_DOCS_NO_STATUS " in result.stdout' + - '"AUTHOR: Ansible Core Team" in result.stdout' + + - name: documented module with non-iterable status in metadata + command: ansible-doc test_docs_non_iterable_status + register: result + - assert: + that: + - '"WARNING" not in result.stderr' + - '"TEST_DOCS_NON_ITERABLE_STATUS " in result.stdout' + - '"AUTHOR: Ansible Core Team" in result.stdout' + + - name: documented module with removed status + command: ansible-doc test_docs_removed_status + register: result + + - assert: + that: + - '"WARNING" not in result.stderr' + - '"TEST_DOCS_REMOVED_STATUS " in result.stdout' + - '"AUTHOR: Ansible Core Team" in result.stdout' + + - name: empty module + command: ansible-doc test_empty + register: result + ignore_errors: true + + - assert: + that: + - result is failed + + - name: module with no documentation + command: ansible-doc test_no_docs + register: result + ignore_errors: true + + - assert: + that: + - result is failed + + - name: deprecated module with both removed date and version (date should get precedence) + command: ansible-doc test_docs_removed_precedence + register: result + + - assert: + that: + - '"DEPRECATED" in result.stdout' + - '"Reason: Updated module released with more functionality" in result.stdout' + - '"Will be removed in a release after 2022-06-01" in result.stdout' + - '"Alternatives: new_module" in result.stdout' diff --git a/test/integration/targets/ansible-doc/test_docs_returns.output b/test/integration/targets/ansible-doc/test_docs_returns.output new file mode 100644 index 00000000..9fbbc8c7 --- /dev/null +++ b/test/integration/targets/ansible-doc/test_docs_returns.output @@ -0,0 +1,37 @@ +> TEST_DOCS_RETURNS (library/test_docs_returns.py) + + Test module + +AUTHOR: Ansible Core Team + +EXAMPLES: + + + + +RETURN VALUES: +- a_first + A first result. + + returned: success + type: str + +- m_middle + This should be in the middle. + Has some more data + + returned: success and 1st of month + type: dict + + CONTAINS: + + - suboption + A suboption. + (Choices: ARF, BARN, c_without_capital_first_letter) + type: str + +- z_last + A last result. + + returned: success + type: str diff --git a/test/integration/targets/ansible-doc/test_docs_suboptions.output b/test/integration/targets/ansible-doc/test_docs_suboptions.output new file mode 100644 index 00000000..52b51d9d --- /dev/null +++ b/test/integration/targets/ansible-doc/test_docs_suboptions.output @@ -0,0 +1,43 @@ +> TEST_DOCS_SUBOPTIONS (library/test_docs_suboptions.py) + + Test module + +OPTIONS (= is mandatory): + +- with_suboptions + An option with suboptions. + Use with care. + [Default: (null)] + type: dict + + SUBOPTIONS: + + - a_first + The first suboption. + [Default: (null)] + type: str + + - m_middle + The suboption in the middle. + Has its own suboptions. + [Default: (null)] + + SUBOPTIONS: + + - a_suboption + A sub-suboption. + [Default: (null)] + type: str + + - z_last + The last suboption. + [Default: (null)] + type: str + + +AUTHOR: Ansible Core Team + +EXAMPLES: + + + |