Add test and update documentation for mailer plugin

Add a test for notify-every-unstable-build option because it was
missing.

Improve the documentation and add recipients as a requirement to the
plugin.

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

jenkins_jobs/modules/publishers.py

@@ -1724,9 +1724,12 @@ def pipeline(parser, xml_parent, data):
 def email(parser, xml_parent, data):
     """yaml: email
     Email notifications on build failure.
+    Requires the Jenkins :jenkins-wiki:`Mailer Plugin
+    <Mailer>`.
+
 
     :arg str recipients: Space separated list of recipient email addresses
-      (optional)
+      (required)
     :arg bool notify-every-unstable-build: Send an email for every
       unstable build (default true)
     :arg bool send-to-individuals: Send an email to the individual
@@ -1734,14 +1737,21 @@ def email(parser, xml_parent, data):
 
     Example:
 
-    .. literalinclude::  /../../tests/publishers/fixtures/email001.yaml
+    .. literalinclude::
+       /../../tests/publishers/fixtures/email-minimal.yaml
+       :language: yaml
+
+    .. literalinclude::  /../../tests/publishers/fixtures/email-complete.yaml
        :language: yaml
     """
 
     # TODO: raise exception if this is applied to a maven job
     mailer = XML.SubElement(xml_parent,
                             'hudson.tasks.Mailer')
-    XML.SubElement(mailer, 'recipients').text = data.get('recipients', '')
+    try:
+        XML.SubElement(mailer, 'recipients').text = data['recipients']
+    except KeyError as e:
+        raise MissingAttributeError(e)
 
     # Note the logic reversal (included here to match the GUI
     if data.get('notify-every-unstable-build', True):

tests/publishers/fixtures/email-complete.xml

@@ -2,8 +2,8 @@
 <project>
   <publishers>
     <hudson.tasks.Mailer>
-      <recipients/>
-      <dontNotifyEveryUnstableBuild>false</dontNotifyEveryUnstableBuild>
+      <recipients>foo@example.com bar@example.com</recipients>
+      <dontNotifyEveryUnstableBuild>true</dontNotifyEveryUnstableBuild>
       <sendToIndividuals>true</sendToIndividuals>
     </hudson.tasks.Mailer>
   </publishers>

tests/publishers/fixtures/email-complete.yaml

@@ -1,3 +1,5 @@
 publishers:
   - email:
       recipients: foo@example.com bar@example.com
+      notify-every-unstable-build: false
+      send-to-individuals: true

tests/publishers/fixtures/email-minimal.xml

@@ -2,7 +2,7 @@
 <project>
   <publishers>
     <hudson.tasks.Mailer>
-      <recipients>foo@example.com bar@example.com</recipients>
+      <recipients>foo@example.com</recipients>
       <dontNotifyEveryUnstableBuild>false</dontNotifyEveryUnstableBuild>
       <sendToIndividuals>false</sendToIndividuals>
     </hudson.tasks.Mailer>

tests/publishers/fixtures/email-minimal.yaml

@@ -0,0 +1,3 @@
+publishers:
+  - email:
+      recipients: foo@example.com

tests/publishers/fixtures/email002.yaml

@@ -1,4 +0,0 @@
-publishers:
-  - email:
-      send-to-individuals: true
-