docker_prune: correctly return 'changed' result (#593) (#594)

* Correctly return 'changed' status.

* Extend tests.

* Fix typo.

(cherry picked from commit 08bfcf7e5f)

changelogs/fragments/593-docker_prune-changed.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "docker_prune - return correct value for ``changed``. So far the module always claimed that nothing changed (https://github.com/ansible-collections/community.docker/pull/593)."

plugins/modules/docker_prune.py

@@ -80,6 +80,9 @@ extends_documentation_fragment:
 author:
   - "Felix Fontein (@felixfontein)"
 
+notes:
+  - The module always returned C(changed=false) before community.docker 3.5.1.
+
 requirements:
   - "L(Docker SDK for Python,https://docker-py.readthedocs.io/en/stable/) >= 2.1.0"
   - "Docker API >= 1.25"
@@ -228,34 +231,46 @@ def main():
 
     try:
         result = dict()
+        changed = False
 
         if client.module.params['containers']:
             filters = clean_dict_booleans_for_docker_api(client.module.params.get('containers_filters'))
             res = client.prune_containers(filters=filters)
             result['containers'] = res.get('ContainersDeleted') or []
             result['containers_space_reclaimed'] = res['SpaceReclaimed']
+            if result['containers'] or result['containers_space_reclaimed']:
+                changed = True
 
         if client.module.params['images']:
             filters = clean_dict_booleans_for_docker_api(client.module.params.get('images_filters'))
             res = client.prune_images(filters=filters)
             result['images'] = res.get('ImagesDeleted') or []
             result['images_space_reclaimed'] = res['SpaceReclaimed']
+            if result['images'] or result['images_space_reclaimed']:
+                changed = True
 
         if client.module.params['networks']:
             filters = clean_dict_booleans_for_docker_api(client.module.params.get('networks_filters'))
             res = client.prune_networks(filters=filters)
             result['networks'] = res.get('NetworksDeleted') or []
+            if result['networks']:
+                changed = True
 
         if client.module.params['volumes']:
             filters = clean_dict_booleans_for_docker_api(client.module.params.get('volumes_filters'))
             res = client.prune_volumes(filters=filters)
             result['volumes'] = res.get('VolumesDeleted') or []
             result['volumes_space_reclaimed'] = res['SpaceReclaimed']
+            if result['volumes'] or result['volumes_space_reclaimed']:
+                changed = True
 
         if client.module.params['builder_cache']:
             res = client.prune_builds()
             result['builder_cache_space_reclaimed'] = res['SpaceReclaimed']
+            if result['builder_cache_space_reclaimed']:
+                changed = True
 
+        result['changed'] = changed
         client.module.exit_json(**result)
     except DockerException as e:
         client.fail('An unexpected docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())

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

@@ -36,7 +36,8 @@
     command: docker volume list
 
   # Prune objects
-  - docker_prune:
+  - name: Prune everything
+    docker_prune:
       containers: yes
       images: yes
       networks: yes
@@ -51,6 +52,7 @@
   - name: General checks
     assert:
       that:
+      - result is changed
       # containers
       - container.container.Id in result.containers
       - "'containers_space_reclaimed' in result"
@@ -78,6 +80,37 @@
       - volume.volume.Name not in result.volumes
     when: docker_api_version is version('1.42', '>=')
 
+  # Prune objects again
+  - name: Prune everything again (should have no change)
+    docker_prune:
+      containers: true
+      images: true
+      networks: true
+      volumes: true
+      builder_cache: "{{ docker_py_version is version('3.3.0', '>=') }}"
+    register: result
+
+  # Analyze result
+  - name: Show results
+    debug:
+      var: result
+  - name: General checks
+    assert:
+      that:
+      - result is not changed
+      # containers
+      - result.containers == []
+      - result.containers_space_reclaimed == 0
+      # images
+      - result.images == []
+      - result.images_space_reclaimed == 0
+      # networks
+      - result.networks == []
+      # volumes
+      - result.volumes == []
+      # builder_cache
+      - result.builder_cache_space_reclaimed == 0
+
   # Test with filters
   - name: Prune with filters
     docker_prune:
@@ -107,6 +140,7 @@
     - name: Check results
       assert:
         that:
+          - result is changed
           - volume.volume.Name in result.volumes
           - "'volumes_space_reclaimed' in result"