Support additional events for HipChat plugin

In newer versions, Jenkins HipChat plugin supports notifications for the
following events:

  notify-success
  notify-aborted
  notify-not-built
  notify-unstable
  notify-failure
  notify-back-to-normal

This commit adds support for these events in JJB. Also, introduces a
unit test for hipchat module and converts doc example generation to
literalinclude.

Change-Id: I3e09b4f2b41db58eb22ada89a633516e319a95bc

jenkins_jobs/modules/hipchat_notif.py

@@ -13,21 +13,36 @@
 # under the License.
 
 """
-Enable hipchat notification of build execution.
+Enable HipChat notifications of build execution.
 
-Example::
+:Parameters:
+  * **enabled** *(bool)*: general cut off switch. If not explicitly set to
+    ``true``, no hipchat parameters are written to XML. For Jenkins HipChat
+    plugin of version prior to 0.1.5, also enables all build results to be
+    reported in HipChat room. For later plugin versions, explicit notify-*
+    setting is required (see below).
+  * **room** *(str)*: name of HipChat room to post messages to
+  * **start-notify** *(bool)*: post messages about build start event
+  * **notify-success** *(bool)*: post messages about successful build event
+    (Jenkins HipChat plugin >= 0.1.5)
+  * **notify-aborted** *(bool)*: post messages about aborted build event
+    (Jenkins HipChat plugin >= 0.1.5)
+  * **notify-not-built** *(bool)*: post messages about build set to NOT_BUILT
+    status (Jenkins HipChat plugin >= 0.1.5). This status code is used in a
+    multi-stage build (like maven2) where a problem in earlier stage prevented
+    later stages from building.
+  * **notify-unstable** *(bool)*: post messages about unstable build event
+    (Jenkins HipChat plugin >= 0.1.5)
+  * **notify-failure** *(bool)*:  post messages about build failure event
+    (Jenkins HipChat plugin >= 0.1.5)
+  * **notify-back-to-normal** *(bool)*: post messages about build being back to
+    normal after being unstable or failed (Jenkins HipChat plugin >= 0.1.5)
 
-  - job:
-      name: test_job
-      hipchat:
-        enabled: true
-        room:  Testjob Build Notifications
-        start-notify: true
+Example:
+
+.. literalinclude:: /../../tests/hipchat/fixtures/hipchat001.yaml
+   :language: yaml
 
-In the jenkins UI specification, the hipchat plugin must be explicitly
-selected as a publisher.  This is not required (or supported) here - use the
-``enabled`` parameter to enable/disable the publisher action.
-If you set ``enabled: false``, no hipchat parameters are written to XML.
 """
 
 # Enabling hipchat notifications on a job requires specifying the hipchat
@@ -98,6 +113,24 @@ class HipChat(jenkins_jobs.modules.base.Base):
         XML.SubElement(pdefhip, 'room').text = hipchat['room']
         XML.SubElement(pdefhip, 'startNotification').text = str(
             hipchat.get('start-notify', False)).lower()
+        if hipchat.get('notify-success'):
+            XML.SubElement(pdefhip, 'notifySuccess').text = str(
+                hipchat.get('notify-success')).lower()
+        if hipchat.get('notify-aborted'):
+            XML.SubElement(pdefhip, 'notifyAborted').text = str(
+                hipchat.get('notify-aborted')).lower()
+        if hipchat.get('notify-not-built'):
+            XML.SubElement(pdefhip, 'notifyNotBuilt').text = str(
+                hipchat.get('notify-not-built')).lower()
+        if hipchat.get('notify-unstable'):
+            XML.SubElement(pdefhip, 'notifyUnstable').text = str(
+                hipchat.get('notify-unstable')).lower()
+        if hipchat.get('notify-failure'):
+            XML.SubElement(pdefhip, 'notifyFailure').text = str(
+                hipchat.get('notify-failure')).lower()
+        if hipchat.get('notify-back-to-normal'):
+            XML.SubElement(pdefhip, 'notifyBackToNormal').text = str(
+                hipchat.get('notify-back-to-normal')).lower()
 
         publishers = xml_parent.find('publishers')
         if publishers is None:

tests/hipchat/fixtures/hipchat001.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <jenkins.plugins.hipchat.HipChatNotifier_-HipChatJobProperty>
+      <room>My Room</room>
+      <startNotification>true</startNotification>
+      <notifySuccess>true</notifySuccess>
+      <notifyAborted>true</notifyAborted>
+      <notifyNotBuilt>true</notifyNotBuilt>
+      <notifyUnstable>true</notifyUnstable>
+      <notifyFailure>true</notifyFailure>
+      <notifyBackToNormal>true</notifyBackToNormal>
+    </jenkins.plugins.hipchat.HipChatNotifier_-HipChatJobProperty>
+  </properties>
+  <publishers>
+    <jenkins.plugins.hipchat.HipChatNotifier>
+      <jenkinsUrl>url</jenkinsUrl>
+      <authToken>authtoken</authToken>
+      <room/>
+    </jenkins.plugins.hipchat.HipChatNotifier>
+  </publishers>
+</project>

tests/hipchat/fixtures/hipchat001.yaml

@@ -0,0 +1,10 @@
+hipchat:
+  enabled: true
+  room: My Room
+  start-notify: true
+  notify-success: true
+  notify-aborted: true
+  notify-not-built: true
+  notify-unstable: true
+  notify-failure: true
+  notify-back-to-normal: true

tests/hipchat/fixtures/hipchat002.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <jenkins.plugins.hipchat.HipChatNotifier_-HipChatJobProperty>
+      <room>My Room</room>
+      <startNotification>true</startNotification>
+    </jenkins.plugins.hipchat.HipChatNotifier_-HipChatJobProperty>
+  </properties>
+  <publishers>
+    <jenkins.plugins.hipchat.HipChatNotifier>
+      <jenkinsUrl>url</jenkinsUrl>
+      <authToken>authtoken</authToken>
+      <room/>
+    </jenkins.plugins.hipchat.HipChatNotifier>
+  </publishers>
+</project>

tests/hipchat/fixtures/hipchat002.yaml

@@ -0,0 +1,4 @@
+hipchat:
+  enabled: true
+  room: My Room
+  start-notify: true

tests/hipchat/test_hipchat.py

@@ -0,0 +1,25 @@
+# Copyright 2014 Hewlett-Packard Development Company, L.P.
+#
+# 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 os
+from testscenarios.testcase import TestWithScenarios
+from testtools import TestCase
+from jenkins_jobs.modules import hipchat_notif
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModulePublishers(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = hipchat_notif.HipChat