xml: fix print_match not populating matches return value (#12013)

* fix(xml): populate matches when print_match is set, fix returned doc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(xml): add integration tests for print_match

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* changelog: add fragment for PR 12013

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

changelogs/fragments/12013-xml-print-match.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - xml - fix ``print_match`` not populating the ``matches`` return value (https://github.com/ansible-collections/community.general/issues/9125, https://github.com/ansible-collections/community.general/pull/12013).

plugins/modules/xml.py

@@ -355,7 +355,7 @@ count:
 matches:
   description: The xpath matches found.
   type: list
-  returned: when parameter O(print_match) is set
+  returned: when parameter O(print_match) is set, or when parameter O(content) is set
 xmlstring:
   description: An XML string of the resulting output.
   type: str
@@ -412,7 +412,7 @@ def do_print_match(module, tree, xpath, namespaces):
         match_xpaths.append(tree.getpath(m))
     match_str = json.dumps(match_xpaths)
     msg = f"selector '{xpath}' match: {match_str}"
-    finish(module, tree, xpath, namespaces, changed=False, msg=msg)
+    finish(module, tree, xpath, namespaces, changed=False, msg=msg, matches=match_xpaths)
 
 
 def count_nodes(module, tree, xpath, namespaces):

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

@@ -75,6 +75,7 @@
     - include_tasks: test-set-namespaced-element-value.yml
     - include_tasks: test-set-namespaced-children-elements.yml
     - include_tasks: test-get-element-content.yml
+    - include_tasks: test-print-match.yml
     - include_tasks: test-xmlstring.yml
     - include_tasks: test-children-elements-xml.yml
 

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

@@ -0,0 +1,38 @@
+---
+# 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: Setup test fixture
+  copy:
+    src: fixtures/ansible-xml-beers.xml
+    dest: /tmp/ansible-xml-beers.xml
+
+- name: print_match returns matching xpath paths in matches
+  xml:
+    path: /tmp/ansible-xml-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:
+    path: /tmp/ansible-xml-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