jenkins_build: Support stop a running Jenkins build (#2850)

* Support stop a running Jenkins build. Meanwhile enrich document content and test cases.

* Fix the inconsistencies regarding the function name.

* Submit the changelog and fix a PEP8 issue.

* Remedy whitespace related PEP8 issues.

* Implement the idempotent test case for the stop build function.

* Make sure it returns proper changed status when we stop a build repeatedly.

* Fix incorrect usages on comparison with True or False and incorrect usages on validating the changed status.

* In this mocking situation, adjust the mock return value and test case to perform unit testing.

* Implement JenkinsMockIdempotent() to mock return value in idempotent test cases.

* Fix issues reported by CI.

* Refactor the code to avoid CI exception and remove get_build_status() from mock function as they should not be there.

* Update plugins/modules/web_infrastructure/jenkins_build.py

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

changelogs/fragments/2850-jenkins_build-support-stop-jenkins-build.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - jenkins_build - support stopping a running jenkins build (https://github.com/ansible-collections/community.general/pull/2850).
+bugfixes:
+  - jenkins_build - examine presence of ``build_number`` before deleting a jenkins build (https://github.com/ansible-collections/community.general/pull/2850).

plugins/modules/web_infrastructure/jenkins_build.py

@@ -15,7 +15,9 @@ description:
     - Manage Jenkins builds with Jenkins REST API.
 requirements:
   - "python-jenkins >= 0.4.12"
-author: Brett Milford (@brettmilford)
+author:
+  - Brett Milford (@brettmilford)
+  - Tong He (@unnecessary-username)
 options:
   args:
     description:
@@ -36,9 +38,10 @@ options:
     type: str
   state:
     description:
-      - Attribute that specifies if the build is to be created or deleted.
+      - Attribute that specifies if the build is to be created, deleted or stopped.
+      - The C(stopped) state has been added in community.general 3.3.0.
     default: present
-    choices: ['present', 'absent']
+    choices: ['present', 'absent', 'stopped']
     type: str
   token:
     description:
@@ -62,9 +65,26 @@ EXAMPLES = '''
     args:
       cloud: "test"
       availability_zone: "test_az"
+    state: present
     user: admin
     password: asdfg
     url: http://localhost:8080
+
+- name: Stop a running jenkins build anonymously
+  community.general.jenkins_build:
+    name: "stop-check"
+    build_number: 3
+    state: stopped
+    url: http://localhost:8080
+
+- name: Delete a jenkins build using token authentication
+  community.general.jenkins_build:
+    name: "delete-experiment"
+    build_number: 30
+    state: absent
+    user: Jenkins
+    token: abcdefghijklmnopqrstuvwxyz123456
+    url: http://localhost:8080
 '''
 
 RETURN = '''
@@ -152,7 +172,8 @@ class JenkinsBuild:
         try:
             build_number = self.server.get_job_info(self.name)['nextBuildNumber']
         except Exception as e:
-            self.module.fail_json(msg='Unable to get job info from Jenkins server, %s' % to_native(e), exception=traceback.format_exc())
+            self.module.fail_json(msg='Unable to get job info from Jenkins server, %s' % to_native(e),
+                                  exception=traceback.format_exc())
 
         return build_number
 
@@ -162,7 +183,8 @@ class JenkinsBuild:
             return response
 
         except Exception as e:
-            self.module.fail_json(msg='Unable to fetch build information, %s' % to_native(e), exception=traceback.format_exc())
+            self.module.fail_json(msg='Unable to fetch build information, %s' % to_native(e),
+                                  exception=traceback.format_exc())
 
     def present_build(self):
         self.build_number = self.get_next_build()
@@ -176,6 +198,19 @@ class JenkinsBuild:
             self.module.fail_json(msg='Unable to create build for %s: %s' % (self.jenkins_url, to_native(e)),
                                   exception=traceback.format_exc())
 
+    def stopped_build(self):
+        build_info = None
+        try:
+            build_info = self.server.get_build_info(self.name, self.build_number)
+            if build_info['building'] is True:
+                self.server.stop_build(self.name, self.build_number)
+        except Exception as e:
+            self.module.fail_json(msg='Unable to stop build for %s: %s' % (self.jenkins_url, to_native(e)),
+                                  exception=traceback.format_exc())
+        else:
+            if build_info['building'] is False:
+                self.module.exit_json(**self.result)
+
     def absent_build(self):
         try:
             self.server.delete_build(self.name, self.build_number)
@@ -191,7 +226,10 @@ class JenkinsBuild:
             sleep(10)
             self.get_result()
         else:
-            if build_status['result'] == "SUCCESS":
+            if self.state == "stopped" and build_status['result'] == "ABORTED":
+                result['changed'] = True
+                result['build_info'] = build_status
+            elif build_status['result'] == "SUCCESS":
                 result['changed'] = True
                 result['build_info'] = build_status
             else:
@@ -216,14 +254,13 @@ def main():
             build_number=dict(type='int'),
             name=dict(required=True),
             password=dict(no_log=True),
-            state=dict(choices=['present', 'absent'], default="present"),
+            state=dict(choices=['present', 'absent', 'stopped'], default="present"),
             token=dict(no_log=True),
             url=dict(default="http://localhost:8080"),
             user=dict(),
         ),
-        mutually_exclusive=[
-            ['password', 'token'],
-        ],
+        mutually_exclusive=[['password', 'token']],
+        required_if=[['state', 'absent', ['build_number'], True], ['state', 'stopped', ['build_number'], True]],
     )
 
     test_dependencies(module)
@@ -231,6 +268,8 @@ def main():
 
     if module.params.get('state') == "present":
         jenkins_build.present_build()
+    elif module.params.get('state') == "stopped":
+        jenkins_build.stopped_build()
     else:
         jenkins_build.absent_build()
 

tests/unit/plugins/modules/web_infrastructure/test_jenkins_build.py

@@ -50,18 +50,42 @@ class JenkinsMock():
 
     def get_build_info(self, name, build_number):
         return {
+            "building": True,
             "result": "SUCCESS"
         }
 
-    def get_build_status(self):
-        pass
-
     def build_job(self, *args):
         return None
 
     def delete_build(self, name, build_number):
         return None
 
+    def stop_build(self, name, build_number):
+        return None
+
+
+class JenkinsMockIdempotent():
+
+    def get_job_info(self, name):
+        return {
+            "nextBuildNumber": 1235
+        }
+
+    def get_build_info(self, name, build_number):
+        return {
+            "building": False,
+            "result": "ABORTED"
+        }
+
+    def build_job(self, *args):
+        return None
+
+    def delete_build(self, name, build_number):
+        return None
+
+    def stop_build(self, name, build_number):
+        return None
+
 
 class TestJenkinsBuild(unittest.TestCase):
 
@@ -79,6 +103,16 @@ class TestJenkinsBuild(unittest.TestCase):
             set_module_args({})
             jenkins_build.main()
 
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
+    def test_module_fail_when_missing_build_number(self, test_deps):
+        test_deps.return_value = None
+        with self.assertRaises(AnsibleFailJson):
+            set_module_args({
+                "name": "required-if",
+                "state": "stopped"
+            })
+            jenkins_build.main()
+
     @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
     @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.JenkinsBuild.get_jenkins_connection')
     def test_module_create_build(self, jenkins_connection, test_deps):
@@ -93,6 +127,42 @@ class TestJenkinsBuild(unittest.TestCase):
             })
             jenkins_build.main()
 
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.JenkinsBuild.get_jenkins_connection')
+    def test_module_stop_build(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "host-check",
+                "build_number": "1234",
+                "state": "stopped",
+                "user": "abc",
+                "token": "xyz"
+            })
+            jenkins_build.main()
+
+        self.assertTrue(return_json.exception.args[0]['changed'])
+
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.JenkinsBuild.get_jenkins_connection')
+    def test_module_stop_build_again(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMockIdempotent()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "host-check",
+                "build_number": "1234",
+                "state": "stopped",
+                "user": "abc",
+                "password": "xyz"
+            })
+            jenkins_build.main()
+
+        self.assertFalse(return_json.exception.args[0]['changed'])
+
     @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
     @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.JenkinsBuild.get_jenkins_connection')
     def test_module_delete_build(self, jenkins_connection, test_deps):