jenkins_api_client 0.0.2 → 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,13 @@
+= CHANGELOG
+
+=== v0.1.0  [26-OCT-2012]
+* Improved performance
+* Added job create feature, delete feature, chaining feature, and build feature
+* Added exception handling mechanism
+
+=== v0.0.2  [16-OCT-2012]
+* Added documentation
+* Added some more smal features to Job class
+
+=== v0.0.1  [15-OCT-2012]
+* Initial Release

data/LICENCE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2012 Kannan Manickam <arangamani.kannan@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -1,14 +1,145 @@
-= jenkins_api_client
+= Jenkins API Client
 
-Client libraries for communicating with a Jenkins CI server
+Client libraries for communicating with a Jenkins CI server and programatically managing jobs.
 
-== Sample Usage:
+== OVERVIEW:
+This project is a simple API client for interacting with Jenkins Continuous Integration server.
+Jenkins provides three kinds of remote access API. 1. XML API, 2. JSON API, and 3. Python API.
+This project aims at consuming the JSON API and provides some useful functions for controlling
+jobs on the Jenkins programatically. Even though Jenkins provides an awesome UI for controlling
+jobs, it would be nice and helpful to have a programmable interface so we can dynamically and
+automatically manage jobs and other artifacts.
+
+== DETAILS:
+This projects currently only provides functionality for the <tt>jobs</tt> interface. This is
+still a work-in-progress project. I mainly use the functionality of this project for my autmation
+work and the functionality mainly focussed on my usage and I believe others might find it useful
+too. I would love to add more features to it and I will continue working on improving existing
+features and add more interfaces such as nodes, views, build queue, etc,.
+
+== USAGE:
+
+=== Installation
 
 Install jenkins_api_client by <tt>sudo gem install jenkins_api_client</tt>
+Include this gem in your code as a require statement.
 
   require 'jenkins_api_client'
 
-  client = JenkinsApi::Client.new(:server_ip => '0.0.0.0', 
+=== Using with IRB
+
+If you want to just play with it and not actually want to write a script, you can just use the
+irb launcher script which is available in <tt>scripts/login_with_irb.rb</tt>. But make sure that
+you have your credentials available in the correct location. By default the script assumes that
+you have your credentials file in <tt>~/.jenkins_api_client/login.yml</tt>. If you don't prefer this
+location and would like to use a different location, just modify that script to point to the
+location where the credentials file exists.
+
+  ruby scripts/login_with_irb.rb
+
+You will see the that it entered IRB session and you can play with the API client with the
+<tt>@client</tt> object that it has returned.
+
+=== Authentication
+
+This project supports two types of password-based authentication. You can just you the plain
+password by using <tt>password</tt> parameter. If you don't prefer leaving plain passwords in the
+credentials file, you can encode your password in base64 format and use <tt>password_base64</tt>
+parameter to specify the password either in the arguments or in the credentials file.
+
+=== Basic Usage
+
+As discussed earlier, you can either specify all the credentials and server information as
+parameters to the Client or have a credentials file and just parse the yaml file and pass it in.
+The following call just passes the information as parameters
+
+  @client = JenkinsApi::Client.new(:server_ip => '0.0.0.0', 
            :username => 'somename', :password => 'secret password')
   # The following call will return all jobs matching 'Testjob'
-  puts client.job.list("^Testjob")
+  puts @client.job.list("^Testjob")
+
+The following example passes the YAML file contents. An example yaml file is located in
+<tt>config/login.yml.example</tt>.
+
+  @client = JenkinsApi::Client.new(YAML.Load_file(File.expand_path('~/.jenkins_api_client/login.yml', __FILE__)))
+  # The following call lists all jobs
+  puts @client.job.list_all
+
+=== Chaining and Building Jobs
+
+Sometimes we want certain jobs to be added as downstream projects and run them sequencially.
+The following example will explain how this could be done.
+
+  require 'jenkins_api_client'
+
+  # We want to filter all jobs that start with 'test_job'
+  # Just write a regex to match all the jobs that start with 'test_job'
+  jobs_to_filter = "^test_job.*"
+
+  # Create an instance to jenkins_api_client
+  @client = JenkinsApi::Client.new(YAML.load_file(File.expand_path('~/.jenkins_api_client/login.yml', __FILE__)))
+
+  # Get a filtered list of jobs from the server
+  jobs = @client.job.list(jobs_to_filter)
+
+  # Chain all the jobs with 'success' as the threshold
+  # The chain method will return the jobs that is in the head of the sequence
+  # This method will also remove any existing chaining
+  initial_jobs = @client.job.chain(jobs, 'success', ["all"])
+
+  # Now that we have the initial job(s) we can build them
+  # The build function returns a code from the API which should be 302 if the build was successful
+  code = @client.job.build(initial_jobs[0])
+  raise "Could not build the job specified" unless code == 302
+
+In the above example, you might have noticed that the chain method returns an array instead of a
+single job. There is a reason behind it. In simple chain, such as the one in the example above, all
+jobs specified are chained one by one. But in some cases they might not be dependent on the previous
+jobs and we might want to run some jobs parallelly. We just have to specify that as a parameter.
+
+For example: <tt>parallel = 3</tt> in the parameter list to the <tt>chain</tt> method will take the first three
+jobs and chain them with the next three jobs and so forth till it reaches the end of the list.
+
+There is another filter option you can specify for the method to take only jobs that are in a
+particular state. In case if we want to build only jobs that are failed or unstable, we can achieve
+that by passing in the states in the third parameter. In the example above, we wanted build all jobs.
+If we just want to build failed and unstable jobs, just pass <tt>["failure", "unstable"]</tt>. Also if you
+pass in an empty array, it will assume that you want to consider all jobs and no filtering will be
+performed.
+
+There is another parameter called <tt>threshold</tt> you can specify for the chaining and this is used
+to decide whether to move forward with the next job in the chain or not. A <tt>success</tt> will move to
+the next job only if the current build succeeds, <tt>failure</tt> will move to the next job even if the build
+fails, and <tt>unstable</tt> will move to the job even if the build is unstable.
+
+The following call to the <tt>chain</tt> method will consider only failed and unstable jobs, chain then
+with 'failure' as the threshold, and also chain three jobs in parallel.
+
+  initial_jobs = @client.job.chain(jobs, 'failure', ["failure", "unstable"], 3)
+  # We will receive three jobs as a result and we can build them all
+  initial_jobs.each { |job|
+    code = @client.job.build(job)
+    raise "Unable to build job: #{job}" unless code == 302
+  }
+
+=== Debug
+
+The call to client initialization accepts a debug parameter. If it is set to <tt>true</tt> it will print
+some debug information to the console. By default it is set to false.
+
+== CONTRIBUTING:
+
+If you would like to contribute to this project, just do the following:
+
+1. Fork the repo on Github.
+2. Add your features and make commits to your forked repo.
+3. Make a pull request to this repo.
+4. Review will be done and changes will be requested.
+5. Once changes are done or no changes are required, pull request will be merged.
+6. The next release will have your changes in it.
+
+== FEATURE REQUEST:
+
+If you use this gem for your project and you think it would be nice to have a particular feature
+that is presently not implemented, I would love to hear that and consider working on it.
+Just open an issue in Github as a feature request.

data/config/login.yml.example

@@ -0,0 +1,19 @@
+# The Jenkins server and login information can be stored in a YAML file like this 
+# so we don't have to pass in the parameters every we login to the server
+# through this API client.
+
+# This file contains the following four parameters
+
+# The IP address of the Jenkins CI Server
+
+:server_ip: 0.0.0.0
+
+# The port number on which the Jenkins listens on. The default is 8080
+
+:server_port: 8080
+
+# The username and password to authenticate to the server
+
+:username: my_username
+
+:password: my_password

data/lib/jenkins_api_client/client.rb

@@ -1,9 +1,32 @@
+#
+# Copyright (c) 2012 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
 require 'rubygems'
 require 'json'
 require 'net/http'
 require 'nokogiri'
 require 'active_support/core_ext'
 require 'active_support/builder'
+require 'base64'
 
 require File.expand_path('../version', __FILE__)
 require File.expand_path('../exceptions', __FILE__)
@@ -11,9 +34,10 @@ require File.expand_path('../job', __FILE__)
 
 module JenkinsApi
   class Client
-
+    attr_accessor :debug
+    @debug = false
     DEFAULT_SERVER_PORT = 8080
-    VALID_PARAMS = %w(server_ip server_port username password)
+    VALID_PARAMS = %w(server_ip server_port username password debug)
 
     # Initialize a Client object with Jenkins CI server information and credentials
     #
@@ -28,8 +52,13 @@ module JenkinsApi
         instance_variable_set("@#{key}", value) if value
       } if args.is_a? Hash
      raise "Server IP is required to connect to Jenkins Server" unless @server_ip
-     raise "Credentials are required to connect to te Jenkins Server" unless @username && @password
+     raise "Credentials are required to connect to te Jenkins Server" unless @username && (@password || @password_base64)
      @server_port = DEFAULT_SERVER_PORT unless @server_port
+
+     # Base64 decode inserts a newline character at the end. As a workaround added chomp
+     # to remove newline characters. I hope nobody uses newline characters at the end of
+     # their passwords :)
+     @password = Base64.decode64(@password_base64).chomp if @password_base64
     end
 
     # Creates an instance to the Job object by passing a reference to self
@@ -48,12 +77,24 @@ module JenkinsApi
     #
     # @param [String] url_prefix
     #
-    def api_get_request(url_prefix)
+    def api_get_request(url_prefix, tree = nil)
       http = Net::HTTP.start(@server_ip, @server_port)
       request = Net::HTTP::Get.new("#{url_prefix}/api/json")
+      request = Net::HTTP::Get.new("#{url_prefix}/api/json?#{tree}") if tree
       request.basic_auth @username, @password
       response = http.request(request)
-      JSON.parse(response.body)
+      case response.code.to_i
+      when 200
+        return JSON.parse(response.body)
+      when 401
+        raise Exceptions::UnautherizedException.new("HTTP Code: #{response.code.to_s}, Response Body: #{response.body}")
+      when 404
+        raise Exceptions::NotFoundException.new("HTTP Code: #{response.code.to_s}, Response Body: #{response.body}")
+      when 500
+        raise Exceptions::InternelServerErrorException.new("HTTP Code: #{response.code.to_s}, Response Body: #{response.body}")
+      else
+        raise Exceptions::ApiException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+      end
     end
 
     # Sends a POST message to the Jenkins CI server with the specified URL
@@ -65,6 +106,16 @@ module JenkinsApi
       request = Net::HTTP::Post.new("#{url_prefix}")
       request.basic_auth @username, @password
       response = http.request(request)
+      case response.code.to_i
+      when 200, 302
+        return response.code
+      when 404
+        raise Exceptions::NotFoundException.new("HTTP Code: #{response.code.to_s}, Response Body: #{response.body}")
+      when 500
+        raise Exceptions::InternelServerErrorException.new("HTTP Code: #{response.code.to_s}, Response Body: #{response.body}")
+      else
+        raise Exceptions::ApiException.new("HTTP Code: #{response.code.to_s}, Response body: #{response.body}")
+      end
     end
 
     # Obtains the configuration of a component from the Jenkins CI server
@@ -86,9 +137,10 @@ module JenkinsApi
     #
     def post_config(url_prefix, xml)
       http = Net::HTTP.start(@server_ip, @server_port)
-      request = Net::HTTP::Post.new("#{url_prefix}/config.xml")
+      request = Net::HTTP::Post.new("#{url_prefix}")
       request.basic_auth @username, @password
       request.body = xml
+      request.content_type = 'application/xml'
       response = http.request(request)
       response.code
     end

data/lib/jenkins_api_client/exceptions.rb

@@ -1,11 +1,49 @@
+#
+# Copyright (c) 2012 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
 module JenkinsApi
   module Exceptions
     class ApiException < RuntimeError
-
-      def initialize(message="")
+      def initialize(message = "")
         super("Error: #{message}")
       end
+    end
+
+    class UnautherizedException < ApiException
+      def initialize(message = "")
+        super("Invalid credentials are provided. #{message}")
+      end
+    end
 
+    class NotFoundException < ApiException
+      def initialize(message = "")
+        super("Requested page not found on the Jenkins CI server. #{message}")
+      end
+    end
+
+    class InternelServerErrorException < ApiException
+      def initialize(message = "")
+        super("Internel Server Error. #{message}")
+      end
     end
   end
 end

data/lib/jenkins_api_client/job.rb

@@ -1,3 +1,25 @@
+#
+# Copyright (c) 2012 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
 module JenkinsApi
   class Client
     class Job
@@ -8,6 +30,29 @@ module JenkinsApi
         @client = client
       end
 
+      # Return a string representation of the object
+      #
+      def to_s
+        "#<JenkinsApi::Client::Job>"
+      end
+
+      # Create a job with the name specified and the xml given
+      #
+      # @param [String] job_name
+      # @param [XML] xml
+      #
+      def create(job_name, xml)
+        @client.post_config("/createItem?name=#{job_name}", xml)
+      end
+
+      # Delete a job given the name
+      #
+      # @param [String] job_name
+      #
+      def delete(job_name)
+        @client.api_post_request("/job/#{job_name}/doDelete")
+      end
+
       # List all jobs on the Jenkins CI server
       #
       def list_all
@@ -22,12 +67,17 @@ module JenkinsApi
       # List all jobs that match the given regex
       #
       # @param [String] filter - a regex
+      # @param [Boolean] ignorecase
       #
-      def list(filter)
+      def list(filter, ignorecase = true)
         response_json = @client.api_get_request("")
         jobs = []
         response_json["jobs"].each { |job|
-          jobs << job["name"] if job["name"] =~ /#{filter}/i
+          if ignorecase
+            jobs << job["name"] if job["name"] =~ /#{filter}/i
+          else
+            jobs << job["name"] if job["name"] =~ /#{filter}/
+          end
         }
         jobs
       end
@@ -101,10 +151,10 @@ module JenkinsApi
       # This functions lists all jobs that are currently running on the Jenkins CI server
       #
       def list_running
-        jobs = list_all
+        xml_response = @client.api_get_request("", "tree=jobs[name,color]")
         running_jobs = []
-        jobs.each { |job|
-          running_jobs << job if get_current_build_status(job) == "running"
+        xml_response["jobs"].each { |job|
+          running_jobs << job["name"] if job["color"] =~ /anime/
         }
         running_jobs
       end
@@ -131,7 +181,7 @@ module JenkinsApi
       # @param [String] xml
       #
       def post_config(job_name, xml)
-        @client.post_config("/job/#{job_name}", xml)
+        @client.post_config("/job/#{job_name}/config.xml", xml)
       end
 
       # Change the description of a specific job
@@ -154,8 +204,9 @@ module JenkinsApi
       # @param [String] job_name
       # @param [String] downstream_projects
       # @param [String] threshold - failure, success, or unstable
+      # @param [Bool] overwrite - true or false
       #
-      def add_downstream_projects(job_name, downstream_projects, threshold = 'success')
+      def add_downstream_projects(job_name, downstream_projects, threshold, overwrite = false)
         case threshold
         when 'success'
           name = 'SUCCESS'
@@ -174,7 +225,11 @@ module JenkinsApi
         n_xml = Nokogiri::XML(xml)
         child_projects_node = n_xml.xpath("//childProjects").first
         if child_projects_node
-          child_projects_node.content = child_projects_node.content + ", #{downstream_projects}"
+          if overwrite
+            child_projects_node.content = "#{downstream_projects}"
+          else
+            child_projects_node.content = child_projects_node.content + ", #{downstream_projects}"
+          end
         else
           publisher_node = n_xml.xpath("//publishers").first
           build_trigger_node = publisher_node.add_child("<hudson.tasks.BuildTrigger/>")
@@ -237,6 +292,39 @@ module JenkinsApi
         post_config(job_name, xml_modified)
       end
 
+      # Chain the jobs given based on specified criteria
+      #
+      # @param [Array] job_names Array of job names to be chained
+      # @param [String] threshold what should be the threshold for running the next job
+      # @param [Array] criteria criteria which should be applied for picking the jobs for the chain
+      # @param [Integer] parallel Number of jobs that should be considered for parallel run
+      #
+      def chain(job_names, threshold, criteria, parallel = 1)
+        raise "Parallel jobs should be at least 1" if parallel < 1
+
+        job_names.each { |job|
+          puts "INFO: Removing downstream projects for <#{job}>" if @client.debug
+          @client.job.remove_downstream_projects(job)
+        }
+
+        filtered_job_names = []
+        if criteria.include?("all") || criteria.empty?
+          filtered_job_names = job_names
+        else
+          puts "INFO: Criteria is specified. Filtering jobs..." if @client.debug
+          job_names.each { |job|
+            filtered_job_names << job if criteria.include?(@client.job.get_current_build_status(job))
+          }
+        end
+        filtered_job_names.each_with_index { |job_name, index|
+          break if index >= (filtered_job_names.length - parallel)
+          puts "INFO: Adding <#{filtered_job_names[index+1]}> as a downstream project to <#{job_name}> with <#{threshold}> as the threshold" if @client.debug
+          @client.job.add_downstream_projects(job_name, filtered_job_names[index + parallel], threshold, true)
+        }
+        parallel = filtered_job_names.length if parallel > filtered_job_names.length
+        filtered_job_names[0..parallel-1]
+      end
+
     end
   end
 end

data/lib/jenkins_api_client/version.rb

@@ -1,6 +1,27 @@
+#
+# Copyright (c) 2012 Kannan Manickam <arangamani.kannan@gmail.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
 
 module JenkinsApi
   class Client
-    VERSION = "0.0.2"
+    VERSION = "0.1.0"
   end
 end

data/scripts/login_with_irb.rb

@@ -0,0 +1,14 @@
+# This script provides an easier way to login to Jenkins server API.
+# It logs you in with the credentials and server details you proided and then starts an IRB
+# session so you can interactively play with the API.
+
+require File.expand_path('../../lib/jenkins_api_client', __FILE__)
+require 'yaml'
+require 'irb'
+
+begin
+  @client = JenkinsApi::Client.new(YAML.load_file(File.expand_path('~/.jenkins_api_client/login.yml', __FILE__)))
+  puts "logged-in to the Jenkins API, use the '@client' variable to use the client"
+end
+
+IRB.start

data/spec/client_spec.rb

@@ -0,0 +1,47 @@
+#
+# Specifying JenkinsApi::Client class capabilities
+# Author: Kannan Manickam <arangamani.kannan@gmail.com>
+#
+
+require File.expand_path('../spec_helper', __FILE__)
+require 'yaml'
+
+describe JenkinsApi::Client do
+  context "Given valid credentials and server information in the ~/.jenkins_api_client/login.yml" do
+    before(:all) do
+      @creds_file = '~/.jenkins_api_client/login.yml'
+      # Grabbing just the server IP in a variable so we can check for wrong credentials
+      @server_ip = YAML.load_file(File.expand_path(@creds_file, __FILE__))[:server_ip]
+      begin
+        @client = JenkinsApi::Client.new(YAML.load_file(File.expand_path(@creds_file, __FILE__)))
+      rescue Exception => e
+        puts "WARNING: Credentials are not set properly."
+        puts e.message
+      end
+    end
+
+    it "Should be able to initialize with valid credentials" do
+      client1 = JenkinsApi::Client.new(YAML.load_file(File.expand_path(@creds_file, __FILE__)))
+      client1.class.should == JenkinsApi::Client
+    end
+
+    it "Should fail if wrong credentials are given" do
+      begin
+        client2 = JenkinsApi::Client.new(:server_ip => @server_ip, :username => 'stranger', :password => 'hacked')
+        client2.job.list_all
+      rescue Exception => e
+        e.class.should == JenkinsApi::Exceptions::UnautherizedException
+      end
+    end
+
+    it "Should return a job object on call to job function" do
+      @client.job.class.should == JenkinsApi::Client::Job
+    end
+
+    it "Should accept a YAML argument when creating a new client" do
+      client3 = JenkinsApi::Client.new(YAML.load_file(File.expand_path(@creds_file, __FILE__)))
+      client3.class.should == JenkinsApi::Client
+    end
+    
+  end
+end

data/spec/job_spec.rb

@@ -0,0 +1,129 @@
+#
+# Specifying JenkinsApi::Client::Job class capabilities
+# Author: Kannan Manickam <arangamani.kannan@gmail.com>
+#
+
+require File.expand_path('../spec_helper', __FILE__)
+require 'yaml'
+
+describe JenkinsApi::Client::Job do
+  context "With properly initialized client" do
+    before(:all) do
+      @helper = JenkinsApiSpecHelper::Helper.new
+      @creds_file = '~/.jenkins_api_client/login.yml'
+      @job_name_prefix = 'awesome_rspec_test_job'
+      @filter = "^#{@job_name_prefix}.*"
+      @job_name = ''
+      begin
+        @client = JenkinsApi::Client.new(YAML.load_file(File.expand_path(@creds_file, __FILE__)))
+      rescue Exception => e
+        puts "WARNING: Credentials are not set properly."
+        puts e.message
+      end
+      # Creating 10 jobs to run the spec tests on
+      begin
+        10.times do |num|
+          xml = @helper.create_job_xml
+          job = "#{@job_name_prefix}_#{num}"
+          @job_name = job if num == 0
+          @client.job.create(job, xml).to_i.should == 200
+        end
+      rescue Exception => e
+        puts "WARNING: Can't create jobs for preparing to spec tests"
+      end
+    end
+
+    it "Should be able to create a job" do
+      xml = @helper.create_job_xml
+      @client.job.create("some_random_nonexistent_job", xml).to_i.should == 200
+    end
+
+    it "Should be able to change the description of a job" do
+      @client.job.change_description("some_random_nonexistent_job", "The description has been changed by the spec test").to_i.should == 200
+    end
+
+    it "Should be able to delete a job" do
+      @client.job.delete("some_random_nonexistent_job").to_i.should == 302
+    end
+
+    it "Should list all jobs" do
+      @client.job.list_all.class.should == Array
+    end
+
+    it "Should return job names based on the filter" do
+      names = @client.job.list(@filter)
+      names.class.should == Array
+      names.each { |name|
+        name.should match /#{@filter}/i
+      }
+    end
+
+    it "Should return all job names with details" do
+      @client.job.list_all_with_details.class.should == Array
+    end
+
+    it "Should list details of a particular job" do
+      job_name = @client.job.list(@filter)[0]
+      job_name.class.should == String
+      @client.job.list_details(job_name).class.should == Hash
+    end
+
+    it "Should list upstream projects of the specified job" do
+      @client.job.get_upstream_projects(@job_name).class.should == Array
+    end
+
+    it "Should list downstream projects of the specified job" do
+      @client.job.get_downstream_projects(@job_name).class.should == Array
+    end
+
+    it "Should get builds of a specified job" do
+      @client.job.get_builds(@job_name).class.should == Array
+    end
+
+    it "Should obtain the current build status for the specified job" do
+      build_status = @client.job.get_current_build_status(@job_name)
+      build_status.class.should == String
+      valid_build_status = ["not run", "aborted", "success", "failure", "unstable", "running"]
+      valid_build_status.include?(build_status).should be_true
+    end
+
+    it "Should list all running jobs" do
+      @client.job.list_running.class.should == Array
+    end
+
+    it "Should build the specified job" do
+      @client.job.get_current_build_status(@job_name).should_not == "running"
+      response = @client.job.build(@job_name)
+      response.to_i.should == 302
+    end
+
+    it "Should be able to restrict a job to a node" do
+      @client.job.restrict_to_node(@job_name, 'master').to_i.should == 200
+      # Run it again to make sure that the replace existing node works
+      @client.job.restrict_to_node(@job_name, 'master').to_i.should == 200
+    end
+
+    it "Should be able to chain jobs" do
+      #
+      jobs = @client.job.list(@filter)
+      jobs.class.should == Array
+      start_jobs = @client.job.chain(jobs, 'success', ["all"])
+      start_jobs.class.should == Array
+      start_jobs.length.should == 1
+
+      #
+      #
+      start_jobs = @client.job.chain(jobs, 'failure', ["not run", "aborted", 'failure'], 3)
+      start_jobs.class.should == Array
+      start_jobs.length.should == 3
+    end
+
+    after(:all) do
+      job_names = @client.job.list(@filter)
+      job_names.each { |job_name|
+        @client.job.delete(job_name)
+      }
+    end
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,47 @@
+#
+# Helper functions for Ruby specifications
+# Author: Kannan Manickam <arangamani.kannan@gmail.com>
+#
+
+require 'simplecov'
+SimpleCov.start if ENV["COVERAGE"]
+require File.expand_path('../../lib/jenkins_api_client', __FILE__)
+require 'pp'
+require 'yaml'
+require 'nokogiri'
+
+RSpec.configure do |config|
+  config.mock_with :flexmock
+end
+
+module JenkinsApiSpecHelper
+  class Helper
+
+    def create_job_xml
+      builder = Nokogiri::XML::Builder.new(:encoding => 'UTF-8') { |xml|
+        xml.project {
+          xml.actions
+          xml.description
+          xml.keepDependencies "false"
+          xml.properties
+          xml.scm(:class => "hudson.scm.NullSCM")
+          xml.canRoam "true"
+          xml.disabled "false"
+          xml.blockBuildWhenDownstreamBuilding "false"
+          xml.blockBuildWhenUpstreamBuilding "false"
+          xml.triggers.vector
+          xml.concurrentBuild "false"
+          xml.builders {
+            xml.send("hudson.tasks.Shell") {
+              xml.command "\necho 'done'\necho 'done again'"
+            }
+          }
+          xml.publishers
+          xml.buildWrappers
+        }
+      }
+      builder.to_xml
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jenkins_api_client
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-16 00:00:00.000000000 Z
+date: 2012-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -167,14 +167,21 @@ extensions: []
 extra_rdoc_files:
 - README.rdoc
 files:
+- CHANGELOG.rdoc
 - Gemfile
+- LICENCE
 - README.rdoc
 - Rakefile
+- config/login.yml.example
 - lib/jenkins_api_client.rb
 - lib/jenkins_api_client/client.rb
 - lib/jenkins_api_client/exceptions.rb
 - lib/jenkins_api_client/job.rb
 - lib/jenkins_api_client/version.rb
+- scripts/login_with_irb.rb
+- spec/client_spec.rb
+- spec/job_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/arangamani/jenkins_api_client
 licenses: []
 post_install_message: 
@@ -189,7 +196,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -746284255980224518
+      hash: 2928616763588687630
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: