Add helper function to convert xml

Change-Id: I435008aab406c9086d634781c03bb7cf5bc2acba
Signed-off-by: Kien Ha <kienha9922@gmail.com>

jenkins_jobs/modules/helpers.py

@@ -404,16 +404,35 @@ def artifactory_repository(xml_parent, data, target):
             data.get('deploy-dynamic-mode', False)).lower()
 
 
-def convert_mapping_to_xml(parent, data, mapping):
+def convert_mapping_to_xml(parent, data, mapping, fail_required=False):
+    """Convert mapping to XML
 
+    fail_required affects the last parameter of the mapping field when it's
+    parameter is set to 'None'. When fail_required is True then a 'None' value
+    represents a required configuration so will raise a MissingAttributeError
+    if the user does not provide the configuration.
+
+    If fail_required is False parameter is treated as optional. Logic will skip
+    configuring the XML tag for the parameter. We recommend for new plugins to
+    set fail_required=True and instead of optional parameters provide a default
+    value for all paramters that are not required instead.
+    """
     for elem in mapping:
         (optname, xmlname, val) = elem
         val = data.get(optname, val)
+
+        # Use fail_required setting to allow support for optional parameters
+        # we will phase this out in the future as we rework plugins so that
+        # optional parameters use a default setting instead.
+        if val is None and fail_required is True:
+            raise MissingAttributeError(optname)
+
+        # (Deprecated) in the future we will default to fail_required True
         # if no value is provided then continue else leave it
         # up to the user if they want to use an empty XML tag
-        if val is None:
+        if val is None and fail_required is False:
             continue
-        if str(val).lower() == 'true' or str(val).lower() == 'false':
+
+        if type(val) == bool:
             val = str(val).lower()
-        xe = XML.SubElement(parent, xmlname)
-        xe.text = str(val)
+        XML.SubElement(parent, xmlname).text = str(val)

tests/modules/test_helpers.py

@@ -0,0 +1,70 @@
+#
+# Copyright (c) 2016 Kien Ha <kienha9922@gmail.com>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import testtools
+from testtools.matchers import Equals
+import xml.etree.ElementTree as XML
+import yaml
+
+from jenkins_jobs.errors import MissingAttributeError
+from jenkins_jobs.modules.helpers import convert_mapping_to_xml
+from tests.base import LoggingFixture
+
+
+class TestCaseTestHelpers(LoggingFixture, testtools.TestCase):
+
+    def test_convert_mapping_to_xml(self):
+        """
+        Tests the test_convert_mapping_to_xml_fail_required function
+        """
+
+        # Test default values
+        default_root = XML.Element('testdefault')
+        default_data = yaml.load("string: hello")
+        default_mappings = [('default-string', 'defaultString', 'default')]
+
+        convert_mapping_to_xml(
+            default_root,
+            default_data,
+            default_mappings,
+            fail_required=True)
+        result = default_root.find('defaultString').text
+        self.assertThat(result, Equals('default'))
+
+        # Test user input
+        user_input_root = XML.Element('testUserInput')
+        user_input_data = yaml.load("user-input-string: hello")
+        user_input_mappings = [('user-input-string', 'userInputString',
+                                'user-input')]
+
+        convert_mapping_to_xml(
+            user_input_root,
+            user_input_data,
+            user_input_mappings,
+            fail_required=True)
+        result = user_input_root.find('userInputString').text
+        self.assertThat(result, Equals('hello'))
+
+        # Test missing required input
+        required_root = XML.Element('testrequired')
+        required_data = yaml.load("string: hello")
+        required_mappings = [('required-string', 'requiredString', None)]
+
+        self.assertRaises(MissingAttributeError,
+                          convert_mapping_to_xml,
+                          required_root,
+                          required_data,
+                          required_mappings,
+                          fail_required=True)