jenkins_api_client 0.13.0 → 0.14.0

data/lib/jenkins_api_client/node.rb

@@ -86,7 +86,9 @@ module JenkinsApi
 
       # Initializes a new node object
       #
-      # @param [Object] client reference to Client
+      # @param client [Client] the client object
+      #
+      # @return [Node] the node object
       #
       def initialize(client)
         @client = client

data/lib/jenkins_api_client/system.rb

@@ -31,7 +31,9 @@ module JenkinsApi
 
       # Initializes a new System object.
       #
-      # @param [Object] client a reference to Client
+      # @param client [Client] the client object
+      #
+      # @return [System] the system object
       #
       def initialize(client)
         @client = client
@@ -61,7 +63,7 @@ module JenkinsApi
 
       # Restarts the Jenkins server
       #
-      # @param [Bool] force whether to force restart or wait till all
+      # @param [Boolean] force whether to force restart or wait till all
       #               jobs are completed.
       #
       def restart(force = false)
@@ -74,6 +76,12 @@ module JenkinsApi
         end
       end
 
+      # Performs a force restart of Jenkins server
+      #
+      def restart!
+        restart(true)
+      end
+
       # Reload the Jenkins server
       #
       def reload
@@ -84,6 +92,7 @@ module JenkinsApi
       # List all users known to Jenkins by their Full Name
       #
       def list_users
+        warn "DEPRECATION: System#list_users is deprecated. Please use User#list instead"
         @logger.info "Obtaining the list of users from jenkins"
         users = @client.api_get_request("/asynchPeople")
         names = []

data/lib/jenkins_api_client/user.rb

@@ -0,0 +1,119 @@
+#
+# Copyright (c) 2012-2013 Douglas Henderson <dougforpres@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 'timeout'
+
+module JenkinsApi
+  class Client
+    # This class is used to communicate with Jenkins and performing some user
+    # level operations - currently limited to fetching user info, but can
+    # be extended to support updating user fields
+    #
+    # @since 0.14.0
+    #
+    class User
+
+      # Initializes a new User object.
+      #
+      # @param client [Client] the client object
+      #
+      # @return [User] the user object
+      #
+      def initialize(client)
+        @client = client
+        @logger = @client.logger
+        @timeout = @client.timeout
+      end
+
+      # Returns a string representation of System class.
+      #
+      def to_s
+        "#<JenkinsApi::Client::User>"
+      end
+
+      # Get a list of users
+      # Response will include same as is available from
+      # http://jenkins/user/#{username}
+      # userid, display name, and email-address
+      #
+      # @return [Hash] of [Hash], keyed by Jenkins user id
+      #   * +fullName+ The jenkins user idoutput+ Console output of the job
+      #   * +properties+ Size of the text. This ca
+      #
+      def list
+        @logger.info "Obtaining the list of users from jenkins"
+        # First we need to get the list of users.
+        # This is the same as "System.list_users", but since I didn't want to
+        # depend on that class I reproduced the request here.
+        userlist = @client.api_get_request("/asynchPeople")
+        users = {}
+
+        userlist['users'].each { |user|
+          # Jenkins seems ok to fetch by full-name, as long as perfect match
+          # since the name *came* from Jenkins this seems reasonably safe
+          user = get(user['user']['fullName'])
+          users[user['id']] = user if user
+        } unless userlist.nil?
+
+        return users
+      end
+
+      # Get a single user
+      #
+      # @param user_id [String] User ID or Full Name
+      #
+      # @return [Hash]
+      #   * +id+ Jenkins user id
+      #   * +fullName+ Full name of user (or user id if not set)
+      #   * other fields populated by Jenkins - this may vary based on version/plugins
+      #
+      # @example Example JSON for user info
+      #   {
+      #     "absoluteUrl" : "https://myjenkins.example.com/jenkins/user/fred",
+      #     "description" : "",
+      #     "fullName" : "Fred Flintstone",
+      #     "id" : "fred",
+      #     "property" : [
+      #       {
+      #       },
+      #       {
+      #       },
+      #       {
+      #         "address" : "fred@slaterockandgravel.com"
+      #       },
+      #       {
+      #       },
+      #       {
+      #       },
+      #       {
+      #         "insensitiveSearch" : false
+      #       }
+      #     ]
+      #   }
+      #
+      def get(user_id)
+        response = @client.api_get_request("/user/#{user_id}")
+      end
+
+    end
+  end
+end

data/lib/jenkins_api_client/version.rb

@@ -25,7 +25,7 @@ module JenkinsApi
     # Major version of the gem
     MAJOR   = 0
     # Minor version of the gem
-    MINOR   = 13
+    MINOR   = 14
     # Tiny version of the gem used for patches
     TINY    = 0
     # Used for pre-releases

data/lib/jenkins_api_client/view.rb

@@ -30,7 +30,9 @@ module JenkinsApi
 
       # Initializes a new view object
       #
-      # @param [Object] client reference to Client
+      # @param client [Client] the client object
+      #
+      # @return [View] the client object
       #
       def initialize(client)
         @client = client
@@ -78,8 +80,8 @@ module JenkinsApi
       # @option params [String] :status_filter Filter jobs based on the status.
       #         Valid options: all_selected_jobs, enabled_jobs_only,
       #         disabled_jobs_only. Default: all_selected_jobs
-      # @option params [TrueClass|FalseClass] :filter_queue true or false
-      # @option params [TrueClass|FalseClass] :filter_executors true or false
+      # @option params [Boolean] :filter_queue true or false
+      # @option params [Boolean] :filter_executors true or false
       # @option params [String] :regex Regular expression to filter jobs that
       #         are to be added to the view
       #

data/spec/func_tests/job_spec.rb

@@ -500,6 +500,13 @@ describe JenkinsApi::Client::Job do
         end
       end
 
+      describe "#poll" do
+        it "Should poll the specified job for scm changes" do
+          response = @client.job.poll(@job_name)
+          @valid_post_responses.should include(response.to_i)
+        end
+      end
+
       describe "#disable" do
         it "Should disable the specified job and then enable it again" do
           @client.job.list_details(@job_name)['buildable'].should == true

data/spec/func_tests/system_spec.rb

@@ -74,7 +74,7 @@ describe JenkinsApi::Client::System do
 
       describe "#list_users" do
         it "Should be able to get a list of users" do
-          @client.system.list_users.size == 1
+          @client.system.list_users.should be_an_instance_of(Array)
         end
       end
 

data/spec/func_tests/user_spec.rb

@@ -0,0 +1,49 @@
+#
+# Specifying JenkinsApi::Client::User class capabilities
+# Author: Doug Henderson <dougforpres@gmail.com>
+#
+
+require File.expand_path('../spec_helper', __FILE__)
+require 'yaml'
+
+describe JenkinsApi::Client::User do
+  context "With properly initialized client" do
+    before(:all) do
+      @creds_file = '~/.jenkins_api_client/spec.yml'
+      @valid_post_responses = [200, 201, 302]
+      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
+
+    describe "InstanceMethods" do
+
+      describe "#list" do
+        it "Should be able to get a list of users" do
+          @client.user.list.should be_an_instance_of(Hash)
+        end
+      end
+
+      describe "#get" do
+        it "Should be able to get a specific user" do
+          # Actually, we're gonna get every user in the main user list
+          users = @client.user.list
+
+          users.each do |id, user|
+            id.should eq(user['id'])
+            fetched = @client.user.get(id)
+            fetched.should eq(user)
+          end
+
+        end
+      end
+
+    end
+
+  end
+end

data/spec/unit_tests/build_queue_spec.rb

@@ -3,7 +3,7 @@ require File.expand_path('../spec_helper', __FILE__)
 describe JenkinsApi::Client::BuildQueue do
   context "With properly initialized Client" do
     before do
-      @client = mock
+      @client = double
       mock_logger = Logger.new "/dev/null"
       @client.should_receive(:logger).and_return(mock_logger)
       @queue = JenkinsApi::Client::BuildQueue.new(@client)

data/spec/unit_tests/job_spec.rb

@@ -6,7 +6,7 @@ describe JenkinsApi::Client::Job do
 
     before do
       mock_logger = Logger.new "/dev/null"
-      @client = mock
+      @client = double
       @client.should_receive(:logger).and_return(mock_logger)
       @job = JenkinsApi::Client::Job.new(@client)
       @sample_json_response = {
@@ -369,6 +369,15 @@ describe JenkinsApi::Client::Job do
         end
       end
 
+      describe "#poll" do
+        it "accepts the job name and polls the job for scm changes" do
+          @client.should_receive(:api_post_request).with(
+            "/job/test_job/polling"
+          ).and_return(302)
+          @job.poll("test_job").should == 302
+        end
+      end
+
       describe "#enable" do
         it "accepts the job name and enables the job" do
           @client.should_receive(:api_post_request).with(

data/spec/unit_tests/node_spec.rb

@@ -3,7 +3,7 @@ require File.expand_path('../spec_helper', __FILE__)
 describe JenkinsApi::Client::Node do
   context "With properly initialized Client" do
     before do
-      @client = mock
+      @client = double
       mock_logger = Logger.new "/dev/null"
       @client.should_receive(:logger).and_return(mock_logger)
       @node = JenkinsApi::Client::Node.new(@client)

data/spec/unit_tests/system_spec.rb

@@ -5,7 +5,7 @@ describe JenkinsApi::Client::System do
     before do
       mock_logger = Logger.new "/dev/null"
       mock_timeout = 300
-      @client = mock
+      @client = double
       @client.should_receive(:logger).and_return(mock_logger)
       @client.should_receive(:timeout).and_return(mock_timeout)
       @system = JenkinsApi::Client::System.new(@client)

data/spec/unit_tests/user_spec.rb

@@ -0,0 +1,126 @@
+require File.expand_path('../spec_helper', __FILE__)
+
+describe JenkinsApi::Client::User do
+  context "With properly initialized Client" do
+    FRED_TXT = <<__FRED
+{
+  "absoluteUrl" : "https://myjenkins.example.com/jenkins/user/fred",
+  "description" : "",
+  "fullName" : "Fred Flintstone",
+  "id" : "fred",
+  "property" : [
+    {
+    },
+    {
+    },
+    {
+      "address" : "fred@slaterockandgravel.com"
+    },
+    {
+    },
+    {
+    },
+    {
+      "insensitiveSearch" : false
+    }
+  ]
+}
+__FRED
+
+    WILMA_TXT = <<__WILMA
+{
+  "absoluteUrl" : "https://myjenkins.example.com/jenkins/user/wilma",
+  "description" : "",
+  "fullName" : "wilma",
+  "id" : "wilma",
+  "property" : [
+    {
+    },
+    {
+    },
+    {
+    },
+    {
+    },
+    {
+    },
+    {
+    }
+  ]
+}
+__WILMA
+
+    FRED_JSON = JSON.parse(FRED_TXT)
+    WILMA_JSON = JSON.parse(WILMA_TXT)
+    PEOPLE_JSON = JSON.parse(<<__PEEPS
+{
+  "users" : [
+    {
+      "lastChange" : 1375293464494,
+      "project" : {
+        "name" : "a project",
+        "url" : "a url to a project"
+      },
+      "user" : {
+        "absoluteUrl" : "a url to a user",
+        "fullName" : "Fred Flintstone"
+      }
+    }
+  ]
+}
+__PEEPS
+)
+
+    USERLIST_JSON = JSON.parse(<<__USERLIST
+{
+  "fred": #{FRED_TXT}
+}
+__USERLIST
+)
+
+    before do
+      mock_logger = Logger.new "/dev/null"
+      mock_timeout = 300
+      @client = double
+      @client.should_receive(:logger).and_return(mock_logger)
+      @client.should_receive(:timeout).and_return(mock_timeout)
+      @client.stub(:api_get_request).with('/asynchPeople').and_return(PEOPLE_JSON)
+      @client.stub(:api_get_request).with('/user/Fred Flintstone').and_return(FRED_JSON)
+      @client.stub(:api_get_request).with('/user/fred').and_return(FRED_JSON)
+      @client.stub(:api_get_request).with('/user/wilma').and_return(WILMA_JSON)
+      @user = JenkinsApi::Client::User.new(@client)
+    end
+
+    describe "InstanceMethods" do
+      describe "#initialize" do
+        it "initializes by receiving an instance of client object" do
+          mock_logger = Logger.new "/dev/null"
+          mock_timeout = 300
+          @client.should_receive(:logger).and_return(mock_logger)
+          @client.should_receive(:timeout).and_return(mock_timeout)
+          expect(
+            lambda{ JenkinsApi::Client::User.new(@client) }
+          ).not_to raise_error
+        end
+      end
+
+      describe "#list" do
+        it "sends a request to list the users" do
+          @user.list.should eq(USERLIST_JSON)
+        end
+      end
+
+      describe "#get" do
+        it "returns dummy user if user cannot be found" do
+          # This is artifact of Jenkins - It'll create a user to match the name you give it - even on a fetch
+          @user.get("wilma").should eq(WILMA_JSON)
+        end
+
+        it "returns valid user if user can be found" do
+          @user.get("fred").should eq(FRED_JSON)
+        end
+      end
+
+    end
+  end
+end