add xml_info module with shared module_utils and doc fragment

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

tests/integration/targets/xml_info/aliases

@@ -0,0 +1,6 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+azp/posix/3
+destructive

tests/integration/targets/xml_info/meta/main.yml

@@ -0,0 +1,7 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+dependencies:
+  - setup_pkg_mgr

tests/integration/targets/xml_info/tasks/main.yml

@@ -0,0 +1,70 @@
+---
+####################################################################
+# WARNING: These are designed specifically for Ansible tests       #
+# and should not be used as examples of how to write Ansible roles #
+####################################################################
+
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Install lxml (FreeBSD)
+  package:
+    name: 'py{{ ansible_facts.python.version.major }}{{ ansible_facts.python.version.minor }}-lxml'
+    state: present
+  when: ansible_facts.os_family == "FreeBSD"
+
+- name: Install requirements (RHEL 8)
+  package:
+    name:
+      - libxml2-devel
+      - libxslt-devel
+      - python3-lxml
+    state: present
+  when: ansible_facts.distribution == "RedHat" and ansible_facts.distribution_major_version == "8"
+
+# Needed for MacOSX !
+- name: Install lxml
+  pip:
+    name: lxml
+    state: present
+
+- name: Get lxml version
+  command: "{{ ansible_python_interpreter }} -c 'from lxml import etree; print(\".\".join(str(v) for v in etree.LXML_VERSION))'"
+  register: lxml_version
+
+- name: Set lxml capabilities as variables
+  set_fact:
+    lxml_xpath_attribute_result_attrname: '{{ lxml_version.stdout is version("2.3.0", ">=") }}'
+
+- name: Define test XML content
+  set_fact:
+    xml_info_test_xml: |
+      <?xml version='1.0' encoding='UTF-8'?>
+      <business type="bar">
+        <name>Tasty Beverage Co.</name>
+        <beers>
+          <beer>Rochefort 10</beer>
+          <beer>St. Bernardus Abbot 12</beer>
+          <beer>Schlitz</beer>
+        </beers>
+        <rating subjective="true">10</rating>
+        <website>
+          <mobilefriendly/>
+          <address>https://tastybeverageco.com</address>
+        </website>
+      </business>
+
+- name: Write test XML to file
+  copy:
+    content: "{{ xml_info_test_xml }}"
+    dest: /tmp/ansible-xml-info-beers.xml
+
+- name: Only run the tests when lxml v2.3.0+
+  when: lxml_xpath_attribute_result_attrname
+  block:
+
+    - include_tasks: test-count.yml
+    - include_tasks: test-print-match.yml
+    - include_tasks: test-get-element-content.yml
+    - include_tasks: test-xmlstring.yml

tests/integration/targets/xml_info/tasks/test-count.yml

@@ -0,0 +1,17 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Count beer elements
+  xml_info:
+    path: /tmp/ansible-xml-info-beers.xml
+    xpath: /business/beers/beer
+    count: true
+  register: beers
+
+- name: Test expected result
+  assert:
+    that:
+      - beers is not changed
+      - beers.count == 3

tests/integration/targets/xml_info/tasks/test-get-element-content.yml

@@ -0,0 +1,31 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Get element attributes
+  xml_info:
+    path: /tmp/ansible-xml-info-beers.xml
+    xpath: /business/rating
+    content: attribute
+  register: get_element_attribute
+
+- name: Test expected result
+  assert:
+    that:
+      - get_element_attribute is not changed
+      - get_element_attribute.matches[0]['rating'] is defined
+      - get_element_attribute.matches[0]['rating']['subjective'] == 'true'
+
+- name: Get element text
+  xml_info:
+    path: /tmp/ansible-xml-info-beers.xml
+    xpath: /business/rating
+    content: text
+  register: get_element_text
+
+- name: Test expected result
+  assert:
+    that:
+      - get_element_text is not changed
+      - get_element_text.matches[0]['rating'] == '10'

tests/integration/targets/xml_info/tasks/test-print-match.yml

@@ -0,0 +1,33 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: print_match returns matching xpath paths in matches
+  xml_info:
+    path: /tmp/ansible-xml-info-beers.xml
+    xpath: /business/beers/beer
+    print_match: true
+  register: print_match_result
+
+- name: Test expected result
+  assert:
+    that:
+      - print_match_result is not changed
+      - print_match_result.matches | length == 3
+      - "'/business/beers/beer[1]' in print_match_result.matches"
+      - "'/business/beers/beer[2]' in print_match_result.matches"
+      - "'/business/beers/beer[3]' in print_match_result.matches"
+
+- name: print_match with no matches returns empty matches list
+  xml_info:
+    path: /tmp/ansible-xml-info-beers.xml
+    xpath: /business/nonexistent
+    print_match: true
+  register: print_match_empty
+
+- name: Test expected result for no matches
+  assert:
+    that:
+      - print_match_empty is not changed
+      - print_match_empty.matches | length == 0

tests/integration/targets/xml_info/tasks/test-xmlstring.yml

@@ -0,0 +1,43 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Count nodes in an XML string
+  xml_info:
+    xmlstring: "{{ xml_info_test_xml }}"
+    xpath: /business/beers/beer
+    count: true
+  register: count_result
+
+- name: Test expected result
+  assert:
+    that:
+      - count_result is not changed
+      - count_result.count == 3
+
+- name: Get element text from an XML string
+  xml_info:
+    xmlstring: "{{ xml_info_test_xml }}"
+    xpath: /business/rating
+    content: text
+  register: text_result
+
+- name: Test expected result
+  assert:
+    that:
+      - text_result is not changed
+      - text_result.matches[0]['rating'] == '10'
+
+- name: Print match from an XML string
+  xml_info:
+    xmlstring: "{{ xml_info_test_xml }}"
+    xpath: /business/beers/beer
+    print_match: true
+  register: match_result
+
+- name: Test expected result
+  assert:
+    that:
+      - match_result is not changed
+      - match_result.matches | length == 3