test-kitchen 1.2.1 → 1.3.0

data/lib/kitchen/base64_stream.rb

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+#
+# Author:: Fletcher Nichol (<fnichol@nichol.ca>)
+#
+# Copyright (C) 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.
+# 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.
+
+module Kitchen
+
+  # Base64 encoder/decoder that operates on IO objects so as to minimize
+  # memory allocations on large payloads.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  module Base64Stream
+
+    # Encodes an input stream into a Base64 output stream. The input and ouput
+    # objects must be opened IO resources. In other words, opening and closing
+    # the resources are not the responsibilty of this method.
+    #
+    # @param io_in [#read] input stream
+    # @param io_out [#write] output stream
+    def self.strict_encode(io_in, io_out)
+      buffer = "" # rubocop:disable Lint/UselessAssignment
+      while io_in.read(3 * 1000, buffer)
+        io_out.write([buffer].pack("m0"))
+      end
+      buffer = nil # rubocop:disable Lint/UselessAssignment
+    end
+
+    # Decodes a Base64 input stream into an output stream. The input and ouput
+    # objects must be opened IO resources. In other words, opening and closing
+    # the resources are not the responsibilty of this method.
+    #
+    # @param io_in [#read] input stream
+    # @param io_out [#write] output stream
+    def self.strict_decode(io_in, io_out)
+      buffer = "" # rubocop:disable Lint/UselessAssignment
+      while io_in.read(3 * 1000, buffer)
+        io_out.write(buffer.unpack("m0").first)
+      end
+      buffer = nil # rubocop:disable Lint/UselessAssignment
+    end
+  end
+end

data/lib/kitchen/busser.rb

@@ -16,8 +16,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'base64'
-require 'digest'
+require "base64"
+require "digest"
 
 module Kitchen
 
@@ -95,21 +95,23 @@ module Kitchen
     # @return [String] a command string to setup the test suite, or nil if no
     #   work needs to be performed
     def setup_cmd
-      @setup_cmd ||= if local_suite_files.empty?
-        nil
-      else
-        setup_cmd  = []
-        setup_cmd << busser_setup_env
-        setup_cmd << "if ! #{sudo}#{config[:ruby_bindir]}/gem list busser -i >/dev/null"
-        setup_cmd << "then #{sudo}#{config[:ruby_bindir]}/gem install #{gem_install_args}"
-        setup_cmd << "fi"
-        setup_cmd << "gem_bindir=`#{config[:ruby_bindir]}/ruby -rrubygems -e \"puts Gem.bindir\"`"
-        setup_cmd << "#{sudo}${gem_bindir}/busser setup"
-        setup_cmd << "#{sudo}#{config[:busser_bin]} plugin install #{plugins.join(' ')}"
-
-        # use Bourne (/bin/sh) as Bash does not exist on all Unix flavors
-        "sh -c '#{setup_cmd.join('; ')}'"
-      end
+      return if local_suite_files.empty?
+
+      ruby    = "#{config[:ruby_bindir]}/ruby"
+      gem     = sudo("#{config[:ruby_bindir]}/gem")
+      busser  = sudo(config[:busser_bin])
+
+      cmd = <<-CMD.gsub(/^ {8}/, "")
+        #{busser_setup_env}
+        gem_bindir=`#{ruby} -rrubygems -e "puts Gem.bindir"`
+
+        if ! #{gem} list busser -i >/dev/null; then
+          #{gem} install #{gem_install_args}
+        fi
+        #{sudo("${gem_bindir}")}/busser setup
+        #{busser} plugin install #{plugins.join(" ")}
+      CMD
+      Util.wrap_command(cmd)
     end
 
     # Returns a command string which transfers all suite test files to the
@@ -121,18 +123,22 @@ module Kitchen
     # @return [String] a command string to transfer all suite test files, or
     #   nil if no work needs to be performed.
     def sync_cmd
-      @sync_cmd ||= if local_suite_files.empty?
-        nil
-      else
-        sync_cmd  = []
-        sync_cmd << busser_setup_env
-        sync_cmd << "#{sudo}#{config[:busser_bin]} suite cleanup"
-        sync_cmd << "#{local_suite_files.map { |f| stream_file(f, remote_file(f, config[:suite_name])) }.join("; ")}"
-        sync_cmd << "#{helper_files.map { |f| stream_file(f, remote_file(f, "helpers")) }.join("; ")}"
-
-        # use Bourne (/bin/sh) as Bash does not exist on all Unix flavors
-        "sh -c '#{sync_cmd.join('; ')}'"
+      return if local_suite_files.empty?
+
+      cmd = <<-CMD.gsub(/^ {8}/, "")
+        #{busser_setup_env}
+
+        #{sudo(config[:busser_bin])} suite cleanup
+
+      CMD
+      local_suite_files.each do |f|
+        cmd << stream_file(f, remote_file(f, config[:suite_name])).concat("\n")
+      end
+      helper_files.each do |f|
+        cmd << stream_file(f, remote_file(f, "helpers")).concat("\n")
       end
+
+      Util.wrap_command(cmd)
     end
 
     # Returns a command string which runs all Busser suite tests for the suite.
@@ -143,16 +149,15 @@ module Kitchen
     # @return [String] a command string to run the test suites, or nil if no
     #   work needs to be performed
     def run_cmd
-      @run_cmd ||= if local_suite_files.empty?
-        nil
-      else
-        run_cmd  = []
-        run_cmd << busser_setup_env
-        run_cmd << "#{sudo}#{config[:busser_bin]} test"
-
-        # use Bourne (/bin/sh) as Bash does not exist on all Unix flavors
-        "sh -c '#{run_cmd.join('; ')}'"
-      end
+      return if local_suite_files.empty?
+
+      cmd = <<-CMD.gsub(/^ {8}/, "")
+        #{busser_setup_env}
+
+        #{sudo(config[:busser_bin])} test
+      CMD
+
+      Util.wrap_command(cmd)
     end
 
     private
@@ -160,83 +165,144 @@ module Kitchen
     DEFAULT_RUBY_BINDIR = "/opt/chef/embedded/bin".freeze
     DEFAULT_ROOT_PATH = "/tmp/busser".freeze
 
+    # @return [Hash] a configuration hash
+    # @api private
     attr_reader :config
 
+    # Ensures that the object is internally consistent and otherwise raising
+    # an exception.
+    #
+    # @param suite_name [String] the suite name
+    # @raise [ClientError] if a suite name is missing
+    # @raise [UserError] if the suite name is invalid
+    # @api private
     def validate_options(suite_name)
       if suite_name.nil?
         raise ClientError, "Busser#new requires a suite_name"
       end
 
-      if suite_name == 'helper'
+      if suite_name == "helper"
         raise UserError,
           "Suite name invalid: 'helper' is a reserved directory name."
       end
     end
 
+    # Returns a uniquely sorted Array of Busser plugin gems that need to
+    # be installed for the related suite.
+    #
+    # @return [Array<String>] a lexically sorted, unique item array of Busser
+    #   plugin gem names
+    # @api private
     def plugins
+      non_suite_dirs = %w[data data_bags environments nodes roles]
       glob = File.join(config[:test_base_path], config[:suite_name], "*")
       Dir.glob(glob).reject { |d|
-        ! File.directory?(d) || non_suite_dirs.include?(File.basename(d))
+        !File.directory?(d) || non_suite_dirs.include?(File.basename(d))
       }.map { |d| "busser-#{File.basename(d)}" }.sort.uniq
     end
 
+    # Returns an Array of test suite filenames for the related suite currently
+    # residing on the local workstation. Any special provisioner-specific
+    # directories (such as a Chef roles/ directory) are excluded.
+    #
+    # @return [Array<String>] array of suite files
+    # @api private
     def local_suite_files
       base = File.join(config[:test_base_path], config[:suite_name])
       glob = File.join(base, "*/**/*")
       Dir.glob(glob).reject do |f|
-         is_chef_data_dir?(base, f) || File.directory?(f)
+        chef_data_dir?(base, f) || File.directory?(f)
       end
     end
 
-    def is_chef_data_dir?(base, file)
-      file =~ %r[^#{base}/(data|data_bags|environments|nodes|roles)/]
+    # Determines whether or not a local workstation file exists under a
+    # Chef-related directory.
+    #
+    # @return [truthy,falsey] whether or not a given file is some kind of
+    #   Chef-related file
+    # @api private
+    def chef_data_dir?(base, file)
+      file =~ %r{^#{base}/(data|data_bags|environments|nodes|roles)/}
     end
 
+    # Returns an Array of common helper filenames currently residing on the
+    # local workstation.
+    #
+    # @return [Array<String>] array of helper files
+    # @api private
     def helper_files
-      Dir.glob(File.join(config[:test_base_path], "helpers", "*/**/*")).reject { |f| File.directory?(f) }
+      glob = File.join(config[:test_base_path], "helpers", "*/**/*")
+      Dir.glob(glob).reject { |f| File.directory?(f) }
     end
 
+    # Returns a command string that will, once evaluated, result in the
+    # fully qualified destination path of a file on an instance.
+    #
+    # @param file [String] absolute path to the local file
+    # @param dir [String] suite directory or helper directory name
+    # @return [String] command string
+    # @api private
     def remote_file(file, dir)
       local_prefix = File.join(config[:test_base_path], dir)
-      "$(#{sudo}#{config[:busser_bin]} suite path)/".concat(file.sub(%r{^#{local_prefix}/}, ''))
+      "`#{sudo(config[:busser_bin])} suite path`/".
+        concat(file.sub(%r{^#{local_prefix}/}, ""))
     end
 
+    # Returns a command string that will, once evaluated, result in the copying
+    # of a local file to a remote instance.
+    #
+    # @param local_path [String] the path to a local source file for copying
+    # @param remote_path [String] the destrination path on the remote instance
+    # @return [String] command string
+    # @api private
     def stream_file(local_path, remote_path)
       local_file = IO.read(local_path)
+      encoded_file = Base64.encode64(local_file).gsub("\n", "")
       md5 = Digest::MD5.hexdigest(local_file)
-      perms = sprintf("%o", File.stat(local_path).mode)[2, 4]
+      perms = format("%o", File.stat(local_path).mode)[2, 4]
       stream_cmd = [
-        "#{sudo}#{config[:busser_bin]}",
+        sudo(config[:busser_bin]),
         "deserialize",
         "--destination=#{remote_path}",
         "--md5sum=#{md5}",
         "--perms=#{perms}"
       ].join(" ")
 
-      stream_file_cmd  = []
-      stream_file_cmd << %{echo "Uploading #{remote_path} (mode=#{perms})"}
-      stream_file_cmd << %{echo "#{Base64.encode64(local_file).gsub("\n", '')}" | #{sudo}#{stream_cmd}}
-      stream_file_cmd.join('; ')
-    end
-
-    def sudo
-      config[:sudo] ? "sudo -E " : ""
+      [
+        %{echo "Uploading #{remote_path} (mode=#{perms})"},
+        %{echo "#{encoded_file}" | #{stream_cmd}}
+      ].join("\n").concat("\n")
     end
 
-    def non_suite_dirs
-      %w{data data_bags environments nodes roles}
+    # Conditionally prefixes a command with a sudo command.
+    #
+    # @param command [String] command to be prefixed
+    # @return [String] the command, conditionaly prefixed with sudo
+    # @api private
+    def sudo(command)
+      config[:sudo] ? "sudo -E #{command}" : command
     end
 
+    # Returns a command string that sets appropriate environment variables for
+    # busser commands.
+    #
+    # @return [String] command string
+    # @api private
     def busser_setup_env
       [
         %{BUSSER_ROOT="#{config[:root_path]}"},
         %{GEM_HOME="#{config[:root_path]}/gems"},
         %{GEM_PATH="#{config[:root_path]}/gems"},
         %{GEM_CACHE="#{config[:root_path]}/gems/cache"},
-        %{; export BUSSER_ROOT GEM_HOME GEM_PATH GEM_CACHE}
+        %{\nexport BUSSER_ROOT GEM_HOME GEM_PATH GEM_CACHE}
       ].join(" ")
     end
 
+    # Returns arguments to a `gem install` command, suitable to install the
+    # Busser gem.
+    #
+    # @return [String] arguments string
+    # @api private
     def gem_install_args
       gem, version = config[:version].split("@")
       gem, version = "busser", gem if gem =~ /^\d+\.\d+\.\d+/

data/lib/kitchen/cli.rb

@@ -16,11 +16,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'thor'
+require "thor"
 
-require 'kitchen'
-require 'kitchen/generator/driver_create'
-require 'kitchen/generator/init'
+require "kitchen"
+require "kitchen/generator/driver_create"
+require "kitchen/generator/init"
 
 module Kitchen
 
@@ -32,12 +32,21 @@ module Kitchen
     # Common module to load and invoke a CLI-implementation agnostic command.
     module PerformCommand
 
+      # Perform a CLI subcommand.
+      #
+      # @param task [String] action to take, usually corresponding to the
+      #   subcommand name
+      # @param command [String] command class to create and invoke]
+      # @param args [Array] remainder arguments from processed ARGV
+      #   (default: `nil`)
+      # @param additional_options [Hash] additional configuration needed to
+      #   set up the command class (default: `{}`)
       def perform(task, command, args = nil, additional_options = {})
         require "kitchen/command/#{command}"
 
         command_options = {
           :action => task,
-          :help => lambda { help(task) },
+          :help => -> { help(task) },
           :config => @config,
           :shell => shell
         }.merge(additional_options)
@@ -51,6 +60,8 @@ module Kitchen
     include Logging
     include PerformCommand
 
+    # The maximum number of concurrent instances that can run--which is a bit
+    # high
     MAX_CONCURRENCY = 9999
 
     # Constructs a new instance.
@@ -59,22 +70,27 @@ module Kitchen
       $stdout.sync = true
       Kitchen.logger = Kitchen.default_file_logger
       @loader = Kitchen::Loader::YAML.new(
-        :project_config => ENV['KITCHEN_YAML'],
-        :local_config => ENV['KITCHEN_LOCAL_YAML'],
-        :global_config => ENV['KITCHEN_GLOBAL_YAML']
+        :project_config => ENV["KITCHEN_YAML"],
+        :local_config => ENV["KITCHEN_LOCAL_YAML"],
+        :global_config => ENV["KITCHEN_GLOBAL_YAML"]
       )
       @config = Kitchen::Config.new(
         :loader     => @loader,
-        :log_level  => ENV.fetch('KITCHEN_LOG', "info").downcase.to_sym
+        :log_level  => ENV.fetch("KITCHEN_LOG", "info").downcase.to_sym
       )
     end
 
     desc "list [INSTANCE|REGEXP|all]", "Lists one or more instances"
-    method_option :bare, :aliases => "-b", :type => :boolean,
+    method_option :bare,
+      :aliases => "-b",
+      :type => :boolean,
       :desc => "List the name of each instance only, one per line"
-    method_option :debug, :aliases => "-d", :type => :boolean,
+    method_option :debug,
+      :aliases => "-d",
+      :type => :boolean,
       :desc => "[Deprecated] Please use `kitchen diagnose'"
-    method_option :log_level, :aliases => "-l",
+    method_option :log_level,
+      :aliases => "-l",
       :desc => "Set the log level (debug, info, warn, error, fatal)"
     def list(*args)
       update_config!
@@ -82,36 +98,63 @@ module Kitchen
     end
 
     desc "diagnose [INSTANCE|REGEXP|all]", "Show computed diagnostic configuration"
-    method_option :log_level, :aliases => "-l",
+    method_option :log_level,
+      :aliases => "-l",
       :desc => "Set the log level (debug, info, warn, error, fatal)"
-    method_option :loader, :type => :boolean,
+    method_option :loader,
+      :type => :boolean,
       :desc => "Include data loader diagnostics"
-    method_option :instances, :type => :boolean, :default => true,
+    method_option :instances,
+      :type => :boolean,
+      :default => true,
       :desc => "Include instances diagnostics"
-    method_option :all, :type => :boolean,
+    method_option :all,
+      :type => :boolean,
       :desc => "Include all diagnostics"
     def diagnose(*args)
       update_config!
       perform("diagnose", "diagnose", args, :loader => @loader)
     end
 
-    [:create, :converge, :setup, :verify, :destroy].each do |action|
+    {
+      :create   => "Change instance state to create. " \
+                   "Start one or more instances",
+      :converge => "Change instance state to converge. " \
+                   "Use a provisioner to configure one or more instances",
+      :setup    => "Change instance state to setup. " \
+                   "Prepare to run automated tests. " \
+                   "Install busser and related gems on one or more instances",
+      :verify   => "Change instance state to verify. " \
+                   "Run automated tests on one or more instances",
+      :destroy  => "Change instance state to destroy. " \
+                   "Delete all information for one or more instances"
+    }.each do |action, short_desc|
       desc(
         "#{action} [INSTANCE|REGEXP|all]",
-        "#{action.capitalize} one or more instances"
+        short_desc
       )
-      method_option :concurrency, :aliases => "-c",
-        :type => :numeric, :lazy_default => MAX_CONCURRENCY,
-        :desc => <<-DESC.gsub(/^\s+/, '').gsub(/\n/, ' ')
+      long_desc <<-DESC
+        The instance states are in order: destroy, create, converge, setup, verify, destroy.
+        Change one or more instances from the current state to the #{action} state. Actions for all
+        intermediate states will be executed. See http://kitchen.ci for further explanation.
+      DESC
+      method_option :concurrency,
+        :aliases => "-c",
+        :type => :numeric,
+        :lazy_default => MAX_CONCURRENCY,
+        :desc => <<-DESC.gsub(/^\s+/, "").gsub(/\n/, " ")
           Run a #{action} against all matching instances concurrently. Only N
           instances will run at the same time if a number is given.
         DESC
-      method_option :parallel, :aliases => "-p", :type => :boolean,
-        :desc => <<-DESC.gsub(/^\s+/, '').gsub(/\n/, ' ')
+      method_option :parallel,
+        :aliases => "-p",
+        :type => :boolean,
+        :desc => <<-DESC.gsub(/^\s+/, "").gsub(/\n/, " ")
           [Future DEPRECATION, use --concurrency]
           Run a #{action} against all matching instances concurrently.
         DESC
-      method_option :log_level, :aliases => "-l",
+      method_option :log_level,
+        :aliases => "-l",
         :desc => "Set the log level (debug, info, warn, error, fatal)"
       define_method(action) do |*args|
         update_config!
@@ -119,9 +162,13 @@ module Kitchen
       end
     end
 
-    desc "test [INSTANCE|REGEXP|all]", "Test one or more instances"
+    desc "test [INSTANCE|REGEXP|all]",
+      "Test (destroy, create, converge, setup, verify and destroy) one or more instances"
     long_desc <<-DESC
-      Test one or more instances
+      The instance states are in order: destroy, create, converge, setup, verify, destroy.
+      Test changes the state of one or more instances to destroyed, then executes
+      the actions for each state up to destroy. At any sign of failure, executing the
+      actions stops and the instance is left in the last successful execution state.
 
       There are 3 post-verify modes for instance cleanup, triggered with
       the `--destroy' flag:
@@ -130,22 +177,31 @@ module Kitchen
       * always: instances will always be destroyed afterwards.\n
       * never: instances will never be destroyed afterwards.
     DESC
-    method_option :concurrency, :aliases => "-c",
-      :type => :numeric, :lazy_default => MAX_CONCURRENCY,
-      :desc => <<-DESC.gsub(/^\s+/, '').gsub(/\n/, ' ')
+    method_option :concurrency,
+      :aliases => "-c",
+      :type => :numeric,
+      :lazy_default => MAX_CONCURRENCY,
+      :desc => <<-DESC.gsub(/^\s+/, "").gsub(/\n/, " ")
         Run a test against all matching instances concurrently. Only N
         instances will run at the same time if a number is given.
       DESC
-    method_option :parallel, :aliases => "-p", :type => :boolean,
-      :desc => <<-DESC.gsub(/^\s+/, '').gsub(/\n/, ' ')
+    method_option :parallel,
+      :aliases => "-p",
+      :type => :boolean,
+      :desc => <<-DESC.gsub(/^\s+/, "").gsub(/\n/, " ")
         [Future DEPRECATION, use --concurrency]
         Run a test against all matching instances concurrently.
       DESC
-    method_option :log_level, :aliases => "-l",
+    method_option :log_level,
+      :aliases => "-l",
       :desc => "Set the log level (debug, info, warn, error, fatal)"
-    method_option :destroy, :aliases => "-d", :default => "passing",
+    method_option :destroy,
+      :aliases => "-d",
+      :default => "passing",
       :desc => "Destroy strategy to use after testing (passing, always, never)."
-    method_option :auto_init, :type => :boolean, :default => false,
+    method_option :auto_init,
+      :type => :boolean,
+      :default => false,
       :desc => "Invoke init command if .kitchen.yml is missing"
     def test(*args)
       update_config!
@@ -154,18 +210,32 @@ module Kitchen
     end
 
     desc "login INSTANCE|REGEXP", "Log in to one instance"
-    method_option :log_level, :aliases => "-l",
+    method_option :log_level,
+      :aliases => "-l",
       :desc => "Set the log level (debug, info, warn, error, fatal)"
     def login(*args)
       update_config!
       perform("login", "login", args)
     end
 
+    desc "exec INSTANCE|REGEXP -c REMOTE_COMMAND",
+      "Execute command on one or more instance"
+    method_option :log_level,
+      :aliases => "-l",
+      :desc => "Set the log level (debug, info, warn, error, fatal)"
+    method_option :command,
+      :aliases => "-c",
+      :desc => "execute via ssh"
+    def exec(*args)
+      update_config!
+      perform("exec", "exec", args)
+    end
+
     desc "version", "Print Kitchen's version information"
     def version
       puts "Test Kitchen version #{Kitchen::VERSION}"
     end
-    map %w(-v --version) => :version
+    map %w[-v --version] => :version
 
     desc "sink", "Show the Kitchen sink!", :hide => true
     def sink
@@ -217,6 +287,7 @@ module Kitchen
         perform("discover", "driver_discover", args)
       end
 
+      # @return [String] basename
       def self.basename
         super + " driver"
       end
@@ -238,14 +309,23 @@ module Kitchen
 
     private
 
+    # Ensure the any failing commands exit non-zero.
+    #
+    # @return [true] you die always on failure
+    # @api private
     def self.exit_on_failure?
       true
     end
 
+    # @return [Logger] the common logger
+    # @api private
     def logger
       Kitchen.logger
     end
 
+    # Update and finalize options for logging, concurrency, and other concerns.
+    #
+    # @api private
     def update_config!
       if options[:log_level]
         level = options[:log_level].downcase.to_sym
@@ -264,10 +344,13 @@ module Kitchen
       end
     end
 
+    # If auto_init option is active, invoke the init generator.
+    #
+    # @api private
     def ensure_initialized
-      yaml = ENV['KITCHEN_YAML'] || '.kitchen.yml'
+      yaml = ENV["KITCHEN_YAML"] || ".kitchen.yml"
 
-      if options[:auto_init] && ! File.exists?(yaml)
+      if options[:auto_init] && !File.exist?(yaml)
         banner "Invoking init as '#{yaml}' file is missing"
         invoke "init"
       end