test-kitchen 1.2.1 → 1.3.0

data/lib/kitchen/driver/proxy.rb

@@ -1,3 +1,4 @@
+# -*- encoding: utf-8 -*-
 #
 # Author:: Seth Chisamore <schisamo@opscode.com>
 #
@@ -17,13 +18,17 @@
 # limitations under the License.
 #
 
-require 'kitchen/driver/ssh_base'
+require "kitchen"
 
 module Kitchen
 
   module Driver
 
-    # Proxy driver for Test Kitchen.
+    # Simple driver that proxies commands through to a test instance whose
+    # lifecycle is not managed by Test Kitchen. This driver is useful for long-
+    # lived non-ephemeral test instances that are simply "reset" between test
+    # runs. Think executing against devices like network switches--this is why
+    # the driver was created.
     #
     # @author Seth Chisamore <schisamo@opscode.com>
     class Proxy < Kitchen::Driver::SSHBase
@@ -33,11 +38,13 @@ module Kitchen
 
       no_parallel_for :create, :destroy
 
+      # (see Base#create)
       def create(state)
         state[:hostname] = config[:host]
         reset_instance(state)
       end
 
+      # (see Base#destroy)
       def destroy(state)
         return if state[:hostname].nil?
         reset_instance(state)
@@ -46,13 +53,17 @@ module Kitchen
 
       private
 
+      # Resets the non-Kitchen managed instance using by issuing a command
+      # over SSH.
+      #
+      # @param state [Hash] the state hash
+      # @api private
       def reset_instance(state)
         if cmd = config[:reset_command]
           info("Resetting instance state with command: #{cmd}")
           ssh(build_ssh_args(state), cmd)
         end
       end
-
     end
   end
 end

data/lib/kitchen/driver/ssh_base.rb

@@ -31,10 +31,12 @@ module Kitchen
       default_config :sudo, true
       default_config :port, 22
 
-      def create(state)
+      # (see Base#create)
+      def create(state) # rubocop:disable Lint/UnusedMethodArgument
         raise ClientError, "#{self.class}#create must be implemented"
       end
 
+      # (see Base#converge)
       def converge(state)
         provisioner = instance.provisioner
         provisioner.create_sandbox
@@ -51,35 +53,61 @@ module Kitchen
         provisioner && provisioner.cleanup_sandbox
       end
 
+      # (see Base#setup)
       def setup(state)
         Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
-          run_remote(busser_setup_cmd, conn)
+          run_remote(busser.setup_cmd, conn)
         end
       end
 
+      # (see Base#verify)
       def verify(state)
         Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
-          run_remote(busser_sync_cmd, conn)
-          run_remote(busser_run_cmd, conn)
+          run_remote(busser.sync_cmd, conn)
+          run_remote(busser.run_cmd, conn)
         end
       end
 
-      def destroy(state)
+      # (see Base#destroy)
+      def destroy(state) # rubocop:disable Lint/UnusedMethodArgument
         raise ClientError, "#{self.class}#destroy must be implemented"
       end
 
+      # (see Base#login_command)
       def login_command(state)
         SSH.new(*build_ssh_args(state)).login_command
       end
 
+      # Executes an arbitrary command on an instance over an SSH connection.
+      #
+      # @param state [Hash] mutable instance and driver state
+      # @param command [String] the command to be executed
+      # @raise [ActionFailed] if the command could not be successfully completed
+      def remote_command(state, command)
+        Kitchen::SSH.new(*build_ssh_args(state)) do |conn|
+          run_remote(command, conn)
+        end
+      end
+
+      # **(Deprecated)** Executes a remote command over SSH.
+      #
+      # @param ssh_args [Array] ssh arguments
+      # @param command [String] remote command to invoke
+      # @deprecated This method should no longer be called directly and exists
+      #   to support very old drivers. This will be removed in the future.
       def ssh(ssh_args, command)
         Kitchen::SSH.new(*ssh_args) do |conn|
           run_remote(command, conn)
         end
       end
 
-      protected
+      private
 
+      # Builds arguments for constructing a `Kitchen::SSH` instance.
+      #
+      # @param state [Hash] state hash
+      # @return [Array] SSH constructor arguments
+      # @api private
       def build_ssh_args(state)
         combined = config.to_hash.merge(state)
 
@@ -96,6 +124,12 @@ module Kitchen
         [combined[:hostname], combined[:username], opts]
       end
 
+      # Adds http and https proxy environment variables to a command, if set
+      # in configuration data.
+      #
+      # @param cmd [String] command string
+      # @return [String] command string
+      # @api private
       def env_cmd(cmd)
         env = "env"
         env << " http_proxy=#{config[:http_proxy]}"   if config[:http_proxy]
@@ -104,6 +138,12 @@ module Kitchen
         env == "env" ? cmd : "#{env} #{cmd}"
       end
 
+      # Executes a remote command over SSH.
+      #
+      # @param command [String] remove command to run
+      # @param connection [Kitchen::SSH] an SSH connection
+      # @raise [ActionFailed] if an exception occurs
+      # @api private
       def run_remote(command, connection)
         return if command.nil?
 
@@ -112,16 +152,30 @@ module Kitchen
         raise ActionFailed, ex.message
       end
 
+      # Transfers one or more local paths over SSH.
+      #
+      # @param locals [Array<String>] array of local paths
+      # @param remote [String] remote destination path
+      # @param connection [Kitchen::SSH] an SSH connection
+      # @raise [ActionFailed] if an exception occurs
+      # @api private
       def transfer_path(locals, remote, connection)
         return if locals.nil? || Array(locals).empty?
 
-        info("Transfering files to #{instance.to_str}")
+        info("Transferring files to #{instance.to_str}")
         locals.each { |local| connection.upload_path!(local, remote) }
         debug("Transfer complete")
       rescue SSHFailed, Net::SSH::Exception => ex
         raise ActionFailed, ex.message
       end
 
+      # Blocks until a TCP socket is available where a remote SSH server
+      # should be listening.
+      #
+      # @param hostname [String] remote SSH server host
+      # @param username [String] SSH username (default: `nil`)
+      # @param options [Hash] configuration hash (default: `{}`)
+      # @api private
       def wait_for_sshd(hostname, username = nil, options = {})
         SSH.new(hostname, username, { :logger => logger }.merge(options)).wait
       end

data/lib/kitchen/errors.rb

@@ -16,6 +16,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "English"
+
 module Kitchen
 
   # All Kitchen errors and exceptions.
@@ -23,6 +25,24 @@ module Kitchen
   # @author Fletcher Nichol <fnichol@nichol.ca>
   module Error
 
+    # Creates an array of strings, representing a formatted exception,
+    # containing backtrace and nested exception info as necessary, that can
+    # be viewed by a human.
+    #
+    # For example:
+    #
+    #     ------Exception-------
+    #     Class: Kitchen::StandardError
+    #     Message: Failure starting the party
+    #     ---Nested Exception---
+    #     Class: IOError
+    #     Message: not enough directories for a party
+    #     ------Backtrace-------
+    #     nil
+    #     ----------------------
+    #
+    # @param exception [::StandardError] an exception
+    # @return [Array<String>] a formatted message
     def self.formatted_trace(exception)
       arr = formatted_exception(exception).dup
       last = arr.pop
@@ -34,12 +54,27 @@ module Kitchen
       arr
     end
 
+    # Creates an array of strings, representing a formatted exception that
+    # can be viewed by a human. Thanks to MiniTest for the inspiration
+    # upon which this output has been designed.
+    #
+    # For example:
+    #
+    #     ------Exception-------
+    #     Class: Kitchen::StandardError
+    #     Message: I have failed you
+    #     ----------------------
+    #
+    # @param exception [::StandardError] an exception
+    # @param title [String] a custom title for the message
+    #   (default: `"Exception"`)
+    # @return [Array<String>] a formatted message
     def self.formatted_exception(exception, title = "Exception")
       [
         title.center(22, "-"),
         "Class: #{exception.class}",
         "Message: #{exception.message}",
-        "".center(22, "-"),
+        "".center(22, "-")
       ]
     end
   end
@@ -50,9 +85,16 @@ module Kitchen
 
     include Error
 
+    # @return [::StandardError] the original (wrapped) exception
     attr_reader :original
 
-    def initialize(msg, original = $!)
+    # Creates a new StandardError exception which optionally wraps an original
+    # exception if given or detected by checking the `$!` global variable.
+    #
+    # @param msg [String] exception message
+    # @param original [::StandardError] an original exception which will be
+    #   wrapped (default: `$ERROR_INFO`)
+    def initialize(msg, original = $ERROR_INFO)
       super(msg)
       @original = original
     end
@@ -60,23 +102,54 @@ module Kitchen
 
   # Base exception class for all exceptions that are caused by user input
   # errors.
-  class UserError < StandardError ; end
+  class UserError < StandardError; end
 
   # Base exception class for all exceptions that are caused by incorrect use
   # of an API.
-  class ClientError < StandardError ; end
+  class ClientError < StandardError; end
 
   # Base exception class for exceptions that are caused by external library
   # failures which may be temporary.
-  class TransientFailure < StandardError ; end
+  class TransientFailure < StandardError; end
 
   # Exception class for any exceptions raised when performing an instance
   # action.
-  class ActionFailed < TransientFailure ; end
+  class ActionFailed < TransientFailure; end
 
   # Exception class capturing what caused an instance to die.
-  class InstanceFailure < TransientFailure ; end
+  class InstanceFailure < TransientFailure; end
 
+  # Yields to a code block in order to consistently emit a useful crash/error
+  # message and exit appropriately. There are two primary failure conditions:
+  # an expected instance failure, and any other unexpected failures.
+  #
+  # **Note** This method may call `Kernel.exit` so may not return if the
+  # yielded code block raises an exception.
+  #
+  # ## Instance Failure
+  #
+  # This is an expected failure scenario which could happen if an instance
+  # couldn't be created, a Chef run didn't successfully converge, a
+  # post-convergence test suite failed, etc. In other words, you can count on
+  # encountering these failures all the time--this is Kitchen's worldview:
+  # crash early and often. In this case a cleanly formatted exception is
+  # written to `STDERR` and the exception message is written to
+  # the common Kitchen file logger.
+  #
+  # ## Unexpected Failure
+  #
+  # All other forms of `Kitchen::Error` exceptions are considered unexpected
+  # or unplanned exceptions, typically from user configuration errors, driver
+  # or provisioner coding issues or bugs, or internal code issues. Given
+  # a stable release of Kitchen and a solid set of drivers and provisioners,
+  # the most likely cause of this is user configuration error originating in
+  # the `.kitchen.yml` setup. For this reason, the exception is written to
+  # `STDERR`, a full formatted exception trace is written to the common
+  # Kitchen file logger, and a message is displayed on `STDERR` to the user
+  # informing them to check the log files and check their configuration with
+  # the `kitchen diagnose` subcommand.
+  #
+  # @raise [SystemExit] if an exception is raised in the yielded block
   def self.with_friendly_errors
     yield
   rescue Kitchen::InstanceFailure => e
@@ -93,6 +166,13 @@ module Kitchen
 
   private
 
+  # Writes an array of lines to the common Kitchen logger's file device at the
+  # given severity level. If the Kitchen logger is set to debug severity, then
+  # the array of lines will also be written to the console output.
+  #
+  # @param level [Symbol,String] the desired log level
+  # @param lines [Array<String>] an array of strings to log
+  # @api private
   def self.file_log(level, lines)
     Array(lines).each do |line|
       if Kitchen.logger.debug?
@@ -103,16 +183,31 @@ module Kitchen
     end
   end
 
+  # Writes an array of lines to the `STDERR` device.
+  #
+  # @param lines [Array<String>] an array of strings to log
+  # @api private
   def self.stderr_log(lines)
-    Array(lines).each do |line|
-      $stderr.puts(Color.colorize(">>>>>> #{line}", :red))
+    Array(lines).map { |line| ">>>>>> #{line}" }.each do |line|
+      line = Color.colorize(line, :red) if Kitchen.tty?
+      $stderr.puts(line)
     end
   end
 
+  # Writes an array of lines to the common Kitchen debugger with debug
+  # severity.
+  #
+  # @param lines [Array<String>] an array of strings to log
+  # @api private
   def self.debug_log(lines)
     Array(lines).each { |line| Kitchen.logger.debug(line) }
   end
 
+  # Handles an instance failure exception.
+  #
+  # @param e [StandardError] an exception to handle
+  # @see Kitchen.with_friendly_errors
+  # @api private
   def self.handle_instance_failure(e)
     stderr_log(e.message.split(/\s{2,}/))
     stderr_log(Error.formatted_exception(e.original))
@@ -120,6 +215,11 @@ module Kitchen
     debug_log(Error.formatted_trace(e))
   end
 
+  # Handles an unexpected failure exception.
+  #
+  # @param e [StandardError] an exception to handle
+  # @see Kitchen.with_friendly_errors
+  # @api private
   def self.handle_error(e)
     stderr_log(Error.formatted_exception(e))
     stderr_log("Please see .kitchen/logs/kitchen.log for more details")

data/lib/kitchen/generator/driver_create.rb

@@ -16,8 +16,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'thor/group'
-require 'thor/util'
+require "thor/group"
+require "thor/util"
 
 module Kitchen
 
@@ -32,9 +32,12 @@ module Kitchen
 
       argument :name, :type => :string
 
-      class_option :license, :aliases => "-l", :default => "apachev2",
+      class_option :license,
+        :aliases => "-l",
+        :default => "apachev2",
         :desc => "License type for gem (apachev2, mit, lgplv3, reserved)"
 
+      # Invoke the command.
       def create
         self.class.source_root(Kitchen.source_root.join("templates", "driver"))
 
@@ -45,6 +48,9 @@ module Kitchen
 
       private
 
+      # Creates top-level project files.
+      #
+      # @api private
       def create_core_files
         empty_directory(target_dir)
 
@@ -60,6 +66,9 @@ module Kitchen
         create_file(File.join(target_dir, ".cane"))
       end
 
+      # Creates source code files.
+      #
+      # @api private
       def create_source_files
         empty_directory(File.join(target_dir, "lib/kitchen/driver"))
 
@@ -73,6 +82,9 @@ module Kitchen
         )
       end
 
+      # Initialize a git repository.
+      #
+      # @api private
       def initialize_git
         inside(target_dir) do
           run("git init")
@@ -80,14 +92,24 @@ module Kitchen
         end
       end
 
+      # Render an ERb template to a destination file.
+      #
+      # @param erb [String] path to an ERb file
+      # @param dest [String] destination path for the rendered template
+      # @api private
       def create_template(erb, dest)
         template(erb, File.join(target_dir, dest), config)
       end
 
+      # @return [String] the path to the gem skeleton project
+      # @api private
       def target_dir
         File.join(Dir.pwd, "kitchen-#{name}")
       end
 
+      # @return [Hash] a configuration hash which can be used by templates as
+      #   context
+      # @api private
       def config
         @config ||= {
           :name => name,
@@ -99,20 +121,28 @@ module Kitchen
           :email => email,
           :license => options[:license],
           :license_string => license_string,
-          :year => Time.now.year,
+          :year => Time.now.year
         }
       end
 
+      # @return [String] a default author name taken from git configuration if
+      #   found
+      # @api private
       def author
         git_user_name = %x{git config user.name}.chomp
         git_user_name.empty? ? "TODO: Write your name" : git_user_name
       end
 
+      # @return [String] a default email address taken from git configuration
+      #   if found
+      # @api private
       def email
         git_user_email = %x{git config user.email}.chomp
         git_user_email.empty? ? "TODO: Write your email" : git_user_email
       end
 
+      # @return [String] a rendered license string for a given license
+      # @api private
       def license_string
         case options[:license]
         when "mit" then "MIT"
@@ -124,6 +154,8 @@ module Kitchen
         end
       end
 
+      # @return [String] the filename to use for the license file
+      # @api private
       def license_filename
         case options[:license]
         when "mit" then "LICENSE.txt"
@@ -134,9 +166,11 @@ module Kitchen
         end
       end
 
+      # @return [String] the license comment/preamble
+      # @api private
       def license_comment
         @license_comment ||= IO.read(File.join(target_dir, license_filename)).
-          gsub(/^/, '# ').gsub(/\s+$/, '')
+          gsub(/^/, "# ").gsub(/\s+$/, "")
       end
     end
   end