xml children module parameter does not exist (#5808)

* Add changelog

* Add integration tests

* Rename children to set_children

* Add PR information

* Update changelogs/fragments/5808-xml-children-parameter-does-not-exist.yml

Co-authored-by: Felix Fontein <felix@fontein.de>

Co-authored-by: Felix Fontein <felix@fontein.de>

changelogs/fragments/5808-xml-children-parameter-does-not-exist.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- xml - fixed a bug where empty ``children`` list would not be set (https://github.com/ansible-collections/community.general/pull/5808).

plugins/modules/xml.py

@@ -266,7 +266,7 @@ EXAMPLES = r'''
   community.general.xml:
     path: /foo/bar.xml
     xpath: /business/website
-    children: []
+    set_children: []
 
 # In case of namespaces, like in below XML, they have to be explicitly stated.
 #
@@ -961,7 +961,7 @@ def main():
     # add_children && set_children both set?: should have already aborted by now
 
     # set_children set?
-    if set_children:
+    if set_children is not None:
         set_target_children(module, doc, xpath, namespaces, set_children, input_type)
 
     # add_children set?

tests/integration/targets/xml/results/test-set-children-elements-empty-list.xml

@@ -0,0 +1,11 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<business type="bar">
+  <name>Tasty Beverage Co.</name>
+  <beers>
+    </beers>
+  <rating subjective="true">10</rating>
+  <website>
+    <mobilefriendly/>
+    <address>http://tastybeverageco.com</address>
+  </website>
+</business>

tests/integration/targets/xml/results/test-set-children-elements-empty-list.xml.license

@@ -0,0 +1,3 @@
+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
+SPDX-FileCopyrightText: Ansible Project

tests/integration/targets/xml/tasks/test-set-children-elements.yml

@@ -8,6 +8,32 @@
       src: fixtures/ansible-xml-beers.xml
       dest: /tmp/ansible-xml-beers.xml
 
+  - name: Set child elements - empty list
+    xml:
+      path: /tmp/ansible-xml-beers.xml
+      xpath: /business/beers
+      set_children: []
+    register: set_children_elements
+
+  - name: Compare to expected result
+    copy:
+      src: results/test-set-children-elements-empty-list.xml
+      dest: /tmp/ansible-xml-beers.xml
+    check_mode: yes
+    diff: yes
+    register: comparison
+
+  - name: Test expected result
+    assert:
+      that:
+      - set_children_elements is changed
+      - comparison is not changed  # identical
+    #command: diff -u {{ role_path }}/results/test-set-children-elements.xml /tmp/ansible-xml-beers.xml
+
+  - name: Setup test fixture
+    copy:
+      src: fixtures/ansible-xml-beers.xml
+      dest: /tmp/ansible-xml-beers.xml
 
   - name: Set child elements
     xml: