Add tests to make sure that the documented 'elements' matches that defined in argument_spec (#66385)

* Add tests to make sure that the documented 'elements' matches that defined in argument_spec

* Mass-add test/sanity/ignore.txt

changelogs/fragments/66385-ansible-test-module-validation-elements.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- "ansible-test - the module validation code now checks whether ``elements`` documentation for options matches the argument_spec."

docs/docsite/rst/dev_guide/testing_validate-modules.rst

@@ -67,6 +67,8 @@ Codes
   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 ``list``.
+  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 ``argument_spec`` use default type (``str``)
   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

test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/main.py

@@ -1463,6 +1463,37 @@ class ModuleValidator(Validator):
                     msg=msg
                 )
 
+            doc_elements = doc_options_arg.get('elements', None)
+            doc_type = doc_options_arg.get('type', 'str')
+            data_elements = data.get('elements', None)
+            if (doc_elements and not doc_type == 'list'):
+                msg = "Argument '%s " % arg
+                if context:
+                    msg += " found in %s" % " -> ".join(context)
+                msg += " defines parameter elements as %s but it is valid only when value of parameter type is list" % doc_elements
+                self.reporter.error(
+                    path=self.object_path,
+                    code='doc-elements-invalid',
+                    msg=msg
+                )
+            if (doc_elements or data_elements) and not (doc_elements == data_elements):
+                msg = "Argument '%s' in argument_spec" % arg
+                if context:
+                    msg += " found in %s" % " -> ".join(context)
+                if data_elements:
+                    msg += " specifies elements as %s," % data_elements
+                else:
+                    msg += " does not specify elements,"
+                if doc_elements:
+                    msg += "but elements is documented as being %s" % doc_elements
+                else:
+                    msg += "but elements is not documented"
+                self.reporter.error(
+                    path=self.object_path,
+                    code='doc-elements-mismatch',
+                    msg=msg
+                )
+
             spec_suboptions = data.get('options')
             doc_suboptions = doc_options_arg.get('suboptions', {})
             if spec_suboptions: