test-kitchen 1.2.1 → 1.3.0

data/lib/kitchen/ssh.rb

@@ -16,20 +16,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'logger'
-require 'net/ssh'
-require 'net/scp'
-require 'socket'
+require "logger"
+require "net/ssh"
+require "net/scp"
+require "socket"
 
-require 'kitchen/errors'
-require 'kitchen/login_command'
+require "kitchen/errors"
+require "kitchen/login_command"
 
 module Kitchen
 
   # Wrapped exception for any internally raised SSH-related errors.
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>
-  class SSHFailed < TransientFailure ; end
+  class SSHFailed < TransientFailure; end
 
   # Class to help establish SSH connections, issue remote commands, and
   # transfer files between a local system and remote node.
@@ -37,6 +37,29 @@ module Kitchen
   # @author Fletcher Nichol <fnichol@nichol.ca>
   class SSH
 
+    # Constructs a new SSH object.
+    #
+    # @example basic usage
+    #
+    #   ssh = Kitchen::SSH.new("remote.example.com", "root")
+    #   ssh.exec("sudo apt-get update")
+    #   ssh.upload!("/tmp/data.txt", "/var/lib/data.txt")
+    #   ssh.shutdown
+    #
+    # @example block usage
+    #
+    #   Kitchen::SSH.new("remote.example.com", "root") do |ssh|
+    #     ssh.exec("sudo apt-get update")
+    #     ssh.upload!("/tmp/data.txt", "/var/lib/data.txt")
+    #   end
+    #
+    # @param hostname [String] the remote hostname (IP address, FQDN, etc.)
+    # @param username [String] the username for the remote host
+    # @param options [Hash] configuration options
+    # @option options [Logger] :logger the logger to use
+    #   (default: `::Logger.new(STDOUT)`)
+    # @yield [self] if a block is given then the constructed object yields
+    #   itself and calls `#shutdown` at the end, closing the remote connection
     def initialize(hostname, username, options = {})
       @hostname = hostname
       @username = username
@@ -49,6 +72,10 @@ module Kitchen
       end
     end
 
+    # Execute a command on the remote host.
+    #
+    # @param cmd [String] command string to execute
+    # @raise [SSHFailed] if the command does not exit with a 0 code
     def exec(cmd)
       logger.debug("[SSH] #{self} (#{cmd})")
       exit_code = exec_with_exit(cmd)
@@ -58,9 +85,16 @@ module Kitchen
       end
     end
 
+    # Uploads a local file to remote host.
+    #
+    # @param local [String] path to local file
+    # @param remote [String] path to remote file destination
+    # @param options [Hash] configuration options that are passed to
+    #   `Net::SCP.upload`
+    # @see http://net-ssh.github.io/net-scp/classes/Net/SCP.html#method-i-upload
     def upload!(local, remote, options = {}, &progress)
       if progress.nil?
-        progress = lambda { |ch, name, sent, total|
+        progress = lambda { |_ch, name, sent, total|
           if sent == total
             logger.debug("Uploaded #{name} (#{total} bytes)")
           end
@@ -70,12 +104,21 @@ module Kitchen
       session.scp.upload!(local, remote, options, &progress)
     end
 
+    # Uploads a recursive directory to remote host.
+    #
+    # @param local [String] path to local file or directory
+    # @param remote [String] path to remote file destination
+    # @param options [Hash] configuration options that are passed to
+    #   `Net::SCP.upload`
+    # @option options [true,false] :recursive recursive copy (default: `true`)
+    # @see http://net-ssh.github.io/net-scp/classes/Net/SCP.html#method-i-upload
     def upload_path!(local, remote, options = {}, &progress)
       options = { :recursive => true }.merge(options)
 
       upload!(local, remote, options, &progress)
     end
 
+    # Shuts down the session connection, if it is still active.
     def shutdown
       return if @session.nil?
 
@@ -85,45 +128,82 @@ module Kitchen
       @session = nil
     end
 
+    # Blocks until the remote host's SSH TCP port is listening.
     def wait
       logger.info("Waiting for #{hostname}:#{port}...") until test_ssh
     end
 
+    # Builds a LoginCommand which can be used to open an interactive session
+    # on the remote host.
+    #
+    # @return [LoginCommand] the login command
     def login_command
-      args  = %W{ -o UserKnownHostsFile=/dev/null }
-      args += %W{ -o StrictHostKeyChecking=no }
-      args += %W{ -o IdentitiesOnly=yes } if options[:keys]
-      args += %W{ -o LogLevel=#{logger.debug? ? "VERBOSE" : "ERROR"} }
-      args += %W{ -o ForwardAgent=#{options[:forward_agent] ? "yes" : "no"} } if options.key? :forward_agent
-      Array(options[:keys]).each { |ssh_key| args += %W{ -i #{ssh_key}} }
-      args += %W{ -p #{port}}
-      args += %W{ #{username}@#{hostname}}
+      args  = %W[ -o UserKnownHostsFile=/dev/null ]
+      args += %W[ -o StrictHostKeyChecking=no ]
+      args += %W[ -o IdentitiesOnly=yes ] if options[:keys]
+      args += %W[ -o LogLevel=#{logger.debug? ? "VERBOSE" : "ERROR"} ]
+      if options.key?(:forward_agent)
+        args += %W[ -o ForwardAgent=#{options[:forward_agent] ? "yes" : "no"} ]
+      end
+      Array(options[:keys]).each { |ssh_key| args += %W[ -i #{ssh_key} ] }
+      args += %W[ -p #{port} ]
+      args += %W[ #{username}@#{hostname} ]
 
       LoginCommand.new(["ssh", *args])
     end
 
     private
 
-    attr_reader :hostname, :username, :options, :logger
+    # TCP socket exceptions
+    SOCKET_EXCEPTIONS = [
+      SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH, IOError
+    ]
+
+    # @return [String] the remote hostname
+    # @api private
+    attr_reader :hostname
+
+    # @return [String] the username for the remote host
+    # @api private
+    attr_reader :username
+
+    # @return [Hash] SSH options, passed to `Net::SSH.start`
+    attr_reader :options
+
+    # @return [Logger] the logger to use
+    # @api private
+    attr_reader :logger
 
+    # Builds the Net::SSH session connection or returns the existing one if
+    # built.
+    #
+    # @return [Net::SSH::Connection::Session] the SSH connection session
+    # @api private
     def session
       @session ||= establish_connection
     end
 
+    # Establish a connection session to the remote host.
+    #
+    # @return [Net::SSH::Connection::Session] the SSH connection session
+    # @api private
     def establish_connection
       rescue_exceptions = [
         Errno::EACCES, Errno::EADDRINUSE, Errno::ECONNREFUSED,
         Errno::ECONNRESET, Errno::ENETUNREACH, Errno::EHOSTUNREACH,
-        Net::SSH::Disconnect
+        Net::SSH::Disconnect, Net::SSH::AuthenticationFailed
       ]
-      retries = 3
+      retries = options[:ssh_retries] || 3
 
       begin
         logger.debug("[SSH] opening connection to #{self}")
         Net::SSH.start(hostname, username, options)
       rescue *rescue_exceptions => e
-        if (retries -= 1) > 0
+        retries -= 1
+        if retries > 0
           logger.info("[SSH] connection failed, retrying (#{e.inspect})")
+          sleep options[:ssh_timeout] || 1
           retry
         else
           logger.warn("[SSH] connection failed, terminating (#{e.inspect})")
@@ -132,31 +212,42 @@ module Kitchen
       end
     end
 
+    # String representation of object, reporting its connection details and
+    # configuration.
+    #
+    # @api private
     def to_s
       "#{username}@#{hostname}:#{port}<#{options.inspect}>"
     end
 
+    # @return [Integer] SSH port (default: 22)
+    # @api private
     def port
       options.fetch(:port, 22)
     end
 
+    # Execute a remote command and return the command's exit code.
+    #
+    # @param cmd [String] command string to execute
+    # @return [Integer] the exit code of the command
+    # @api private
     def exec_with_exit(cmd)
       exit_code = nil
       session.open_channel do |channel|
 
         channel.request_pty
 
-        channel.exec(cmd) do |ch, success|
+        channel.exec(cmd) do |_ch, _success|
 
-          channel.on_data do |ch, data|
+          channel.on_data do |_ch, data|
             logger << data
           end
 
-          channel.on_extended_data do |ch, type, data|
+          channel.on_extended_data do |_ch, _type, data|
             logger << data
           end
 
-          channel.on_request("exit-status") do |ch, data|
+          channel.on_request("exit-status") do |_ch, data|
             exit_code = data.read_long
           end
         end
@@ -165,12 +256,16 @@ module Kitchen
       exit_code
     end
 
+    # Test a remote TCP socket (presumably SSH) for connectivity.
+    #
+    # @return [true,false] a truthy value if the socket is ready and false
+    #   otherwise
+    # @api private
     def test_ssh
       socket = TCPSocket.new(hostname, port)
       IO.select([socket], nil, nil, 5)
-    rescue SocketError, Errno::ECONNREFUSED,
-      Errno::EHOSTUNREACH, Errno::ENETUNREACH, IOError
-      sleep 2
+    rescue *SOCKET_EXCEPTIONS
+      sleep options[:ssh_timeout] || 2
       false
     rescue Errno::EPERM, Errno::ETIMEDOUT
       false

data/lib/kitchen/state_file.rb

@@ -18,18 +18,20 @@
 
 if RUBY_VERSION <= "1.9.3"
   # ensure that Psych and not Syck is used for Ruby 1.9.2
-  require 'yaml'
-  YAML::ENGINE.yamler = 'psych'
+  require "yaml"
+  YAML::ENGINE.yamler = "psych"
 end
-require 'safe_yaml/load'
+require "safe_yaml/load"
 
 module Kitchen
 
   # Exception class for any exceptions raised when reading and parsing a state
   # file from disk
-  class StateFileLoadError < StandardError ; end
+  class StateFileLoadError < StandardError; end
 
   # State persistence manager for instances between actions and invocations.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
   class StateFile
 
     # Constructs an new instance taking the kitchen root and instance name.
@@ -49,7 +51,7 @@ module Kitchen
     # @raise [StateFileLoadError] if there is a problem loading the state file
     #   from disk and loading it into a Hash
     def read
-      if File.exists?(file_name)
+      if File.exist?(file_name) && !File.zero?(file_name)
         Util.symbolized_hash(deserialize_string(read_file))
       else
         Hash.new
@@ -63,13 +65,13 @@ module Kitchen
       dir = File.dirname(file_name)
       serialized_string = serialize_hash(Util.stringified_hash(state))
 
-      FileUtils.mkdir_p(dir) if ! File.directory?(dir)
+      FileUtils.mkdir_p(dir) if !File.directory?(dir)
       File.open(file_name, "wb") { |f| f.write(serialized_string) }
     end
 
     # Destroys a state file on disk if it exists.
     def destroy
-      FileUtils.rm_f(file_name) if File.exists?(file_name)
+      FileUtils.rm_f(file_name) if File.exist?(file_name)
     end
 
     # Returns a Hash of configuration and other useful diagnostic information.
@@ -84,18 +86,33 @@ module Kitchen
 
     private
 
+    # @return [String] absolute path to the yaml state file on disk
+    # @api private
     attr_reader :file_name
 
+    # @return [String] a string representation of the yaml state file
+    # @api private
     def read_file
       IO.read(file_name)
     end
 
+    # Parses a YAML string and returns a Hash.
+    #
+    # @param string [String] a yaml document as a string
+    # @return [Hash] a hash
+    # @raise [StateFileLoadError] if the string document cannot be parsed
+    # @api private
     def deserialize_string(string)
       SafeYAML.load(string)
     rescue SyntaxError, Psych::SyntaxError => ex
       raise StateFileLoadError, "Error parsing #{file_name} (#{ex.message})"
     end
 
+    # Serializes a Hash into a YAML string.
+    #
+    # @param hash [Hash] a hash
+    # @return [String] a yaml document as a string
+    # @api private
     def serialize_hash(hash)
       ::YAML.dump(hash)
     end

data/lib/kitchen/thor_tasks.rb

@@ -16,9 +16,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'thor'
+require "thor"
 
-require 'kitchen'
+require "kitchen"
 
 module Kitchen
 
@@ -42,19 +42,24 @@ module Kitchen
 
     private
 
+    # @return [Config] a Kitchen::Config
     attr_reader :config
 
+    # Generates a test Thor task for each instance and one to test all
+    # instances in serial.
+    #
+    # @api private
     def define
       config.instances.each do |instance|
         self.class.desc instance.name, "Run #{instance.name} test instance"
-        self.class.send(:define_method, instance.name.gsub(/-/, '_')) do
+        self.class.send(:define_method, instance.name.gsub(/-/, "_")) do
           instance.test(:always)
         end
       end
 
       self.class.desc "all", "Run all test instances"
       self.class.send(:define_method, :all) do
-        config.instances.each { |i| invoke i.name.gsub(/-/, '_') }
+        config.instances.each { |i| invoke i.name.gsub(/-/, "_") }
       end
     end
   end

data/lib/kitchen/util.rb

@@ -2,7 +2,7 @@
 #
 # Author:: Fletcher Nichol (<fnichol@nichol.ca>)
 #
-# Copyright (C) 2012, Fletcher Nichol
+# Copyright (C) 2012, 2013, 2014, Fletcher Nichol
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -63,9 +63,9 @@ module Kitchen
     # @return [Object] a converted hash with all keys as symbols
     def self.symbolized_hash(obj)
       if obj.is_a?(Hash)
-        obj.inject({}) { |h, (k, v)| h[k.to_sym] = symbolized_hash(v) ; h }
+        obj.inject({}) { |h, (k, v)| h[k.to_sym] = symbolized_hash(v); h }
       elsif obj.is_a?(Array)
-        obj.inject([]) { |a, v| a << symbolized_hash(v) ; a }
+        obj.inject([]) { |a, e| a << symbolized_hash(e); a }
       else
         obj
       end
@@ -80,9 +80,9 @@ module Kitchen
     # @return [Object] a converted hash with all keys as strings
     def self.stringified_hash(obj)
       if obj.is_a?(Hash)
-        obj.inject({}) { |h, (k, v)| h[k.to_s] = stringified_hash(v) ; h }
+        obj.inject({}) { |h, (k, v)| h[k.to_s] = stringified_hash(v); h }
       elsif obj.is_a?(Array)
-        obj.inject([]) { |a, v| a << stringified_hash(v) ; a }
+        obj.inject([]) { |a, e| a << stringified_hash(e); a }
       else
         obj
       end
@@ -96,7 +96,41 @@ module Kitchen
       total = 0 if total.nil?
       minutes = (total / 60).to_i
       seconds = (total - (minutes * 60))
-      "(%dm%.2fs)" % [minutes, seconds]
+      format("(%dm%.2fs)", minutes, seconds)
+    end
+
+    # Generates a command (or series of commands) wrapped so that it can be
+    # invoked on a remote instance or locally.
+    #
+    # This method uses the Bourne shell (/bin/sh) to maximize the chance of
+    # cross platform portability on Unixlike systems.
+    #
+    # @param [String] the command
+    # @return [String] a wrapped command string
+    def self.wrap_command(cmd)
+      cmd = "false" if cmd.nil?
+      cmd = "true" if cmd.to_s.empty?
+      cmd = cmd.sub(/\n\Z/, "") if cmd =~ /\n\Z/
+
+      "sh -c '\n#{cmd}\n'"
+    end
+
+    # Modifes the given string to strip leading whitespace on each line, the
+    # amount which is calculated by using the first line of text.
+    #
+    # @example
+    #
+    #   string = <<-STRING
+    #     a
+    #       b
+    #   c
+    #   STRING
+    #   Util.outdent!(string) # => "a\n  b\nc\n"
+    #
+    # @param string [String] the string that will be modified
+    # @return [String] the modified string
+    def self.outdent!(string)
+      string.gsub!(/^ {#{string.index(/[^ ]/)}}/, "")
     end
 
     # Returns a set of Bourne Shell (AKA /bin/sh) compatible helper
@@ -105,118 +139,9 @@ module Kitchen
     #
     # @return [String] a string representation of useful helper functions
     def self.shell_helpers
-      # use Bourne (/bin/sh) as Bash does not exist on all Unix flavors
-      <<-HELPERS
-        # Check whether a command exists - returns 0 if it does, 1 if it does not
-        exists() {
-          if command -v $1 >/dev/null 2>&1
-          then
-            return 0
-          else
-            return 1
-          fi
-        }
-
-        # do_wget URL FILENAME
-        do_wget() {
-          echo "trying wget..."
-          wget -O "$2" "$1" 2>/tmp/stderr
-          # check for bad return status
-          test $? -ne 0 && return 1
-          # check for 404 or empty file
-          grep "ERROR 404" /tmp/stderr 2>&1 >/dev/null
-          if test $? -eq 0 || test ! -s "$2"; then
-            return 1
-          fi
-          return 0
-        }
-
-        # do_curl URL FILENAME
-        do_curl() {
-          echo "trying curl..."
-          curl -L "$1" > "$2"
-          # check for bad return status
-          [ $? -ne 0 ] && return 1
-          # check for bad output or empty file
-          grep "The specified key does not exist." "$2" 2>&1 >/dev/null
-          if test $? -eq 0 || test ! -s "$2"; then
-            return 1
-          fi
-          return 0
-        }
-
-        # do_fetch URL FILENAME
-        do_fetch() {
-          echo "trying fetch..."
-          fetch -o "$2" "$1" 2>/tmp/stderr
-          # check for bad return status
-          test $? -ne 0 && return 1
-          return 0
-        }
-
-        # do_perl URL FILENAME
-        do_perl() {
-          echo "trying perl..."
-          perl -e "use LWP::Simple; getprint($ARGV[0]);" "$1" > "$2"
-          # check for bad return status
-          test $? -ne 0 && return 1
-          # check for bad output or empty file
-          # grep "The specified key does not exist." "$2" 2>&1 >/dev/null
-          # if test $? -eq 0 || test ! -s "$2"; then
-          #   unable_to_retrieve_package
-          # fi
-          return 0
-        }
-
-        # do_python URL FILENAME
-        do_python() {
-          echo "trying python..."
-          python -c "import sys,urllib2 ; sys.stdout.write(urllib2.urlopen(sys.argv[1]).read())" "$1" > "$2"
-          # check for bad return status
-          test $? -ne 0 && return 1
-          # check for bad output or empty file
-          #grep "The specified key does not exist." "$2" 2>&1 >/dev/null
-          #if test $? -eq 0 || test ! -s "$2"; then
-          #  unable_to_retrieve_package
-          #fi
-          return 0
-        }
-
-        # do_download URL FILENAME
-        do_download() {
-          PATH=/opt/local/bin:/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
-          export PATH
-
-          echo "downloading $1"
-          echo "  to file $2"
-
-          # we try all of these until we get success.
-          # perl, in particular may be present but LWP::Simple may not be installed
-
-          if exists wget; then
-            do_wget $1 $2 && return 0
-          fi
-
-          if exists curl; then
-            do_curl $1 $2 && return 0
-          fi
-
-          if exists fetch; then
-            do_fetch $1 $2 && return 0
-          fi
-
-          if exists perl; then
-            do_perl $1 $2 && return 0
-          fi
-
-          if exists python; then
-            do_python $1 $2 && return 0
-          fi
-
-          echo ">>>>>> wget, curl, fetch, perl or python not found on this instance."
-          return 16
-        }
-      HELPERS
+      IO.read(File.join(
+        File.dirname(__FILE__), %w[.. .. support download_helpers.sh]
+      ))
     end
   end
 end