update doc and add new JJB unit tests

Add documentation on how to generate documentation and run JJB unit tests. Also added a unit tests for each category of plugins as examples for others to follow when adding new JJB plugins. I'm hoping this will help contributors add tests for new plugins going forward. Change-Id: I2ab90cdb37d0f3b1e947345d4291d2927b04a0c6
2013-11-15 23:13:16 +00:00 · 2013-11-15 23:13:16 +00:00 · b790bbc681
commit b790bbc681
parent 28ec20bb7f
31 changed files with 439 additions and 13 deletions
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@ -11,6 +11,25 @@ systems, including Jenkins.  If you use Puppet, you can use the

 __ https://github.com/openstack-infra/config/tree/master/modules/jenkins

+Documentation
+-------------
+
+Documentation have been included and are in the 'doc' folder. To generate docs
+locally execute the command::
+
+    tox -e venv -- python setup.py build_sphinx
+
+Unit Tests
+----------
+
+Unit tests have been included and are in the 'tests' folder.  We recently
+started including unit tests as examples in our documentation so to keep the
+examples up to date it is very important that we include a unit tests for
+every module.  You can run the unit tests by execute the command::
+
+    tox -epy27
+
+*Note - view tox.ini to run test on other versions of python

 Configuration File
 ------------------
@ -54,15 +73,18 @@ Usage
 ^^^^^
 .. program-output:: jenkins-jobs --help

-Testing
-^^^^^^^
-Once you have a configuration defined, you can test it with::
+Testing JJB
+^^^^^^^^^^^
+Once you have a configuration defined, you can test the job builder by running::

  jenkins-jobs test /path/to/config -o /path/to/output

 That will write XML files to the output directory for all of the jobs
-defined in the configuration directory.  When you're satisfied, you
-can run::
+defined in the configuration directory.  
+
+Updating Jenkins
+^^^^^^^^^^^^^^^^
+When you're satisfied with the generated xml from the test, you can run::

  jenkins-jobs update /path/to/config

--- a/jenkins_jobs/modules/notifications.py
+++ b/jenkins_jobs/modules/notifications.py
@ -49,7 +49,7 @@ def http_endpoint(parser, xml_parent, data):

      notifications:
        - http:
-          url: http://example.com/jenkins_endpoint
+            url: http://example.com/jenkins_endpoint
    """
    endpoint_element = XML.SubElement(xml_parent,
                                      'com.tikal.hudson.plugins.notification.'
--- a/tests/builders/init.py
+++ b/tests/builders/init.py
--- a/tests/builders/fixtures/trigger-builds001.xml
+++ b/tests/builders/fixtures/trigger-builds001.xml
@ -0,0 +1,37 @@
+<?xml version="1.0" ?>
+<project>
+  <builders>
+    <hudson.plugins.parameterizedtrigger.TriggerBuilder>
+      <configs>
+        <hudson.plugins.parameterizedtrigger.BlockableBuildTriggerConfig>
+          <configs>
+            <hudson.plugins.parameterizedtrigger.PredefinedBuildParameters>
+              <properties>FOO=&quot;bar&quot;</properties>
+            </hudson.plugins.parameterizedtrigger.PredefinedBuildParameters>
+          </configs>
+          <projects>build_started</projects>
+          <condition>ALWAYS</condition>
+          <triggerWithNoParameters>false</triggerWithNoParameters>
+          <buildAllNodesWithLabel>false</buildAllNodesWithLabel>
+          <block>
+            <buildStepFailureThreshold>
+              <name>FAILURE</name>
+              <ordinal>2</ordinal>
+              <color>RED</color>
+            </buildStepFailureThreshold>
+            <unstableThreshold>
+              <name>UNSTABLE</name>
+              <ordinal>1</ordinal>
+              <color>Yellow</color>
+            </unstableThreshold>
+            <failureThreshold>
+              <name>FAILURE</name>
+              <ordinal>2</ordinal>
+              <color>RED</color>
+            </failureThreshold>
+          </block>
+        </hudson.plugins.parameterizedtrigger.BlockableBuildTriggerConfig>
+      </configs>
+    </hudson.plugins.parameterizedtrigger.TriggerBuilder>
+  </builders>
+</project>
--- a/tests/builders/fixtures/trigger-builds001.yaml
+++ b/tests/builders/fixtures/trigger-builds001.yaml
@ -0,0 +1,6 @@
+builders:
+  - trigger-builds:
+    - project: "build_started"
+      predefined-parameters:
+        FOO="bar"
+      block: true
--- a/tests/builders/test_builders.py
+++ b/tests/builders/test_builders.py
@ -0,0 +1,28 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 testtools import TestCase
+from testscenarios.testcase import TestWithScenarios
+from jenkins_jobs.modules import builders
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModuleBuilders(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = builders.Builders
--- a/tests/general/test_general.py
+++ b/tests/general/test_general.py
@ -1,3 +1,20 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 testtools import TestCase
 from testscenarios.testcase import TestWithScenarios
--- a/tests/notifications/init.py
+++ b/tests/notifications/init.py
--- a/tests/notifications/fixtures/http-endpoint001.xml
+++ b/tests/notifications/fixtures/http-endpoint001.xml
@ -0,0 +1,13 @@
+<?xml version="1.0" ?>
+<project>
+  <properties>
+    <com.tikal.hudson.plugins.notification.HudsonNotificationProperty>
+      <endpoints>
+        <com.tikal.hudson.plugins.notification.Endpoint>
+          <protocol>HTTP</protocol>
+          <url>http://example.com/jenkins_endpoint</url>
+        </com.tikal.hudson.plugins.notification.Endpoint>
+      </endpoints>
+    </com.tikal.hudson.plugins.notification.HudsonNotificationProperty>
+  </properties>
+</project>
--- a/tests/notifications/fixtures/http-endpoint001.yaml
+++ b/tests/notifications/fixtures/http-endpoint001.yaml
@ -0,0 +1,3 @@
+notifications:
+  - http:
+      url: http://example.com/jenkins_endpoint
--- a/tests/notifications/test_notifications.py
+++ b/tests/notifications/test_notifications.py
@ -0,0 +1,28 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 testtools import TestCase
+from testscenarios.testcase import TestWithScenarios
+from jenkins_jobs.modules import notifications
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModuleNotifications(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = notifications.Notifications
--- a/tests/parameters/init.py
+++ b/tests/parameters/init.py
--- a/tests/parameters/fixtures/dynamic-choice-param001.xml
+++ b/tests/parameters/fixtures/dynamic-choice-param001.xml
@ -0,0 +1,26 @@
+<?xml version="1.0" ?>
+<project>
+  <properties>
+    <hudson.model.ParametersDefinitionProperty>
+      <parameterDefinitions>
+        <com.seitenbau.jenkins.plugins.dynamicparameter.ChoiceParameterDefinition>
+          <name>OPTIONS</name>
+          <description>Available options</description>
+          <__remote>false</__remote>
+          <__script>['optionA', 'optionB']</__script>
+          <__localBaseDirectory serialization="custom">
+            <hudson.FilePath>
+              <default>
+                <remote>/var/lib/jenkins/dynamic_parameter/classpath</remote>
+              </default>
+              <boolean>true</boolean>
+            </hudson.FilePath>
+          </__localBaseDirectory>
+          <__remoteBaseDirectory>dynamic_parameter_classpath</__remoteBaseDirectory>
+          <__classPath/>
+          <readonlyInputField>false</readonlyInputField>
+        </com.seitenbau.jenkins.plugins.dynamicparameter.ChoiceParameterDefinition>
+      </parameterDefinitions>
+    </hudson.model.ParametersDefinitionProperty>
+  </properties>
+</project>
--- a/tests/parameters/fixtures/dynamic-choice-param001.yaml
+++ b/tests/parameters/fixtures/dynamic-choice-param001.yaml
@ -0,0 +1,7 @@
+parameters:
+  - dynamic-choice:
+      name: OPTIONS
+      description: "Available options"
+      script: "['optionA', 'optionB']"
+      remote: false
+      read-only: false
--- a/tests/parameters/test_parameters.py
+++ b/tests/parameters/test_parameters.py
@ -0,0 +1,28 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 parameters
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModuleParameters(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = parameters.Parameters
--- a/tests/properties/init.py
+++ b/tests/properties/init.py
--- a/tests/properties/fixtures/throttle001.xml
+++ b/tests/properties/fixtures/throttle001.xml
@ -0,0 +1,16 @@
+<?xml version="1.0" ?>
+<project>
+  <properties>
+    <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
+      <maxConcurrentPerNode>0</maxConcurrentPerNode>
+      <maxConcurrentTotal>4</maxConcurrentTotal>
+      <throttleEnabled>true</throttleEnabled>
+      <categories>
+        <string>cat1</string>
+        <string>cat2</string>
+      </categories>
+      <throttleOption/>
+      <configVersion>1</configVersion>
+    </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
+  </properties>
+</project>
--- a/tests/properties/fixtures/throttle001.yaml
+++ b/tests/properties/fixtures/throttle001.yaml
@ -0,0 +1,6 @@
+properties:
+  - throttle:
+      max-total: 4
+      categories:
+        - cat1
+        - cat2
--- a/tests/properties/test_properties.py
+++ b/tests/properties/test_properties.py
@ -0,0 +1,28 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 testtools import TestCase
+from testscenarios.testcase import TestWithScenarios
+from jenkins_jobs.modules import properties
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModuleProperties(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = properties.Properties
--- a/tests/publishers/test_publishers.py
+++ b/tests/publishers/test_publishers.py
@ -1,5 +1,3 @@
-#!/usr/bin/env python
-#
 # Joint copyright:
 #  - Copyright 2012,2013 Wikimedia Foundation
 #  - Copyright 2012,2013 Antoine "hashar" Musso
@ -24,7 +22,7 @@ from jenkins_jobs.modules import publishers
 from tests.base import get_scenarios, BaseTestCase


-class TestCaseModulePublisher(TestWithScenarios, TestCase, BaseTestCase):
+class TestCaseModulePublishers(TestWithScenarios, TestCase, BaseTestCase):
    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
    scenarios = get_scenarios(fixtures_path)
    klass = publishers.Publishers
--- a/tests/scm/fixtures/repo001.xml
+++ b/tests/scm/fixtures/repo001.xml
@ -0,0 +1,15 @@
+<?xml version="1.0" ?>
+<project>
+  <scm class="hudson.plugins.repo.RepoScm">
+    <manifestRepositoryUrl>https://example.com/project/</manifestRepositoryUrl>
+    <manifestBranch>stable</manifestBranch>
+    <manifestFile>repo.xml</manifestFile>
+    <manifestGroup>drivers</manifestGroup>
+    <destinationDir>build</destinationDir>
+    <repoUrl>https://internal.net/projects/repo</repoUrl>
+    <mirrorDir>~/git/project/</mirrorDir>
+    <jobs>3</jobs>
+    <currentBranch>false</currentBranch>
+    <quiet>false</quiet>
+  </scm>
+</project>
--- a/tests/scm/fixtures/repo001.yaml
+++ b/tests/scm/fixtures/repo001.yaml
@ -0,0 +1,12 @@
+scm:
+  - repo:
+      manifest-url: https://example.com/project/
+      manifest-branch: stable
+      manifest-file: repo.xml
+      manifest-group: drivers
+      destination-dir: build
+      repo-url: https://internal.net/projects/repo
+      mirror-dir: ~/git/project/
+      jobs: 3
+      current-branch: false
+      quiet: false
--- a/tests/scm/test_scm.py
+++ b/tests/scm/test_scm.py
@ -1,5 +1,3 @@
-#!/usr/bin/env python
-#
 # Joint copyright:
 #  - Copyright 2012,2013 Wikimedia Foundation
 #  - Copyright 2012,2013 Antoine "hashar" Musso
@ -18,13 +16,13 @@
 # under the License.

 import os
-from testscenarios.testcase import TestWithScenarios
 from testtools import TestCase
+from testscenarios.testcase import TestWithScenarios
 from jenkins_jobs.modules import scm
 from tests.base import get_scenarios, BaseTestCase


-class TestCaseModuleScm(TestWithScenarios, TestCase, BaseTestCase):
+class TestCaseModuleSCM(TestWithScenarios, TestCase, BaseTestCase):
    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
    scenarios = get_scenarios(fixtures_path)
    klass = scm.SCM
--- a/tests/triggers/init.py
+++ b/tests/triggers/init.py
--- a/tests/triggers/fixtures/gerrit001.xml
+++ b/tests/triggers/fixtures/gerrit001.xml
@ -0,0 +1,48 @@
+<?xml version="1.0" ?>
+<project>
+  <triggers class="vector">
+    <com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>
+      <spec/>
+      <gerritProjects>
+        <com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.data.GerritProject>
+          <compareType>PLAIN</compareType>
+          <pattern>test-project</pattern>
+          <branches>
+            <com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.data.Branch>
+              <compareType>ANT</compareType>
+              <pattern>**</pattern>
+            </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.data.Branch>
+          </branches>
+          <filePaths>
+            <com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.data.FilePath>
+              <compareType>ANT</compareType>
+              <pattern>subdirectory/**</pattern>
+            </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.data.FilePath>
+          </filePaths>
+        </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.data.GerritProject>
+      </gerritProjects>
+      <skipVote>
+        <onSuccessful>true</onSuccessful>
+        <onFailed>true</onFailed>
+        <onUnstable>true</onUnstable>
+        <onNotBuilt>true</onNotBuilt>
+      </skipVote>
+      <silentMode>false</silentMode>
+      <escapeQuotes>false</escapeQuotes>
+      <noNameAndEmailParameters>false</noNameAndEmailParameters>
+      <dynamicTriggerConfiguration>True</dynamicTriggerConfiguration>
+      <triggerConfigURL>http://myhost/mytrigger</triggerConfigURL>
+      <triggerOnEvents>
+        <com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.events.PluginCommentAddedEvent>
+          <verdictCategory>APRV</verdictCategory>
+          <commentAddedTriggerApprovalValue>1</commentAddedTriggerApprovalValue>
+        </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.events.PluginCommentAddedEvent>
+      </triggerOnEvents>
+      <buildStartMessage/>
+      <buildFailureMessage/>
+      <buildSuccessfulMessage/>
+      <buildUnstableMessage/>
+      <customUrl/>
+    </com.sonyericsson.hudson.plugins.gerrit.trigger.hudsontrigger.GerritTrigger>
+  </triggers>
+</project>
--- a/tests/triggers/fixtures/gerrit001.yaml
+++ b/tests/triggers/fixtures/gerrit001.yaml
@ -0,0 +1,23 @@
+triggers:
+  - gerrit:
+      trigger-on-comment-added-event: true
+      trigger-approval-category: 'APRV'
+      trigger-approval-value: 1
+      projects:
+        - project-compare-type: 'PLAIN'
+          project-pattern: 'test-project'
+          branch-compare-type: 'ANT'
+          branch-pattern: '**'
+          file-paths:
+              - compare-type: ANT
+                pattern: subdirectory/**
+      skip-vote:
+          successful: true
+          failed: true
+          unstable: true
+          notbuilt: true
+      silent: false
+      escape-quotes: false
+      no-name-and-email: false
+      dynamic-trigger-enabled: true
+      dynamic-trigger-url: http://myhost/mytrigger
--- a/tests/triggers/test_triggers.py
+++ b/tests/triggers/test_triggers.py
@ -0,0 +1,28 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 testtools import TestCase
+from testscenarios.testcase import TestWithScenarios
+from jenkins_jobs.modules import triggers
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModuleTriggers(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = triggers.Triggers
--- a/tests/wrappers/init.py
+++ b/tests/wrappers/init.py
--- a/tests/wrappers/fixtures/env-file001.xml
+++ b/tests/wrappers/fixtures/env-file001.xml
@ -0,0 +1,8 @@
+<?xml version="1.0" ?>
+<project>
+  <buildWrappers>
+    <hudson.plugins.envfile.EnvFileBuildWrapper>
+      <filePath>/tmp/foo.txt</filePath>
+    </hudson.plugins.envfile.EnvFileBuildWrapper>
+  </buildWrappers>
+</project>
--- a/tests/wrappers/fixtures/env-file001.yaml
+++ b/tests/wrappers/fixtures/env-file001.yaml
@ -0,0 +1,3 @@
+wrappers:
+  - env-file:
+      properties-file: /tmp/foo.txt
--- a/tests/wrappers/test_wrappers.py
+++ b/tests/wrappers/test_wrappers.py
@ -0,0 +1,28 @@
+# Joint copyright:
+#  - Copyright 2012,2013 Wikimedia Foundation
+#  - Copyright 2012,2013 Antoine "hashar" Musso
+#  - Copyright 2013 Arnaud Fabre
+#
+# 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 testtools import TestCase
+from testscenarios.testcase import TestWithScenarios
+from jenkins_jobs.modules import wrappers
+from tests.base import get_scenarios, BaseTestCase
+
+
+class TestCaseModuleWrappers(TestWithScenarios, TestCase, BaseTestCase):
+    fixtures_path = os.path.join(os.path.dirname(__file__), 'fixtures')
+    scenarios = get_scenarios(fixtures_path)
+    klass = wrappers.Wrappers