test-kitchen 1.2.1 → 1.3.0

data/lib/kitchen/command/login.rb

@@ -16,7 +16,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen/command'
+require "kitchen/command"
 
 module Kitchen
 
@@ -27,6 +27,7 @@ module Kitchen
     # @author Fletcher Nichol <fnichol@nichol.ca>
     class Login < Kitchen::Command::Base
 
+      # Invoke the command.
       def call
         results = parse_subcommand(args.first)
         if results.size > 1

data/lib/kitchen/command/sink.rb

@@ -16,7 +16,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen/command'
+require "kitchen/command"
 
 module Kitchen
 
@@ -27,6 +27,7 @@ module Kitchen
     # @author Seth Vargo <sethvargo@gmail.com>
     class Sink < Kitchen::Command::Base
 
+      # Invoke the command.
       def call
         puts [
           "",

data/lib/kitchen/command/test.rb

@@ -16,9 +16,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require 'kitchen/command'
+require "kitchen/command"
 
-require 'benchmark'
+require "benchmark"
 
 module Kitchen
 
@@ -31,15 +31,16 @@ module Kitchen
 
       include RunAction
 
+      # Invoke the command.
       def call
-        if ! %w{passing always never}.include?(options[:destroy])
+        if !%w[passing always never].include?(options[:destroy])
           raise ArgumentError, "Destroy mode must be passing, always, or never."
         end
 
         banner "Starting Kitchen (v#{Kitchen::VERSION})"
         elapsed = Benchmark.measure do
           destroy_mode = options[:destroy].to_sym
-          results = parse_subcommand(args.join('|'))
+          results = parse_subcommand(args.join("|"))
 
           run_action(:test, results, destroy_mode)
         end

data/lib/kitchen/config.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.
@@ -20,24 +20,76 @@ module Kitchen
 
   # Base configuration class for Kitchen. This class exposes configuration such
   # as the location of the Kitchen config file, instances, log_levels, etc.
+  # This object is a factory object, meaning that it is responsible for
+  # consuming the desired testing configuration in and returning Ruby objects
+  # which are used to perfom the work.
+  #
+  # Most internal objects are created with the expectation of being
+  # *immutable*, meaning that internal state cannot be modified after creation.
+  # Any data manipulation or thread-unsafe activity is performed in this object
+  # so that the subsequently created objects (such as Instances, Platforms,
+  # Drivers, etc.) can safely run in concurrent threads of execution. To
+  # prevent the re-creation of duplicate objects, most created objects are
+  # memoized. The consequence of this is that once the Instance Array has
+  # been requested (with the `#instances` message), you will always be returned
+  # the same Instance objects.
+  #
+  # @example fetching all instances
+  #
+  #   Kitchen::Config.new.instances
+  #
+  # @example fetching an instance by name
+  #
+  #   Kitchen::Config.new.instances.get("default-ubuntu-12.04")
+  #
+  # @example fetching all instances matching a regular expression
+  #
+  #   Kitchen::Config.new.instances.get_all(/ubuntu/)
   #
   # @author Fletcher Nichol <fnichol@nichol.ca>
   class Config
 
+    # @return [String] the absolute path to the root of a Test Kitchen project
+    # @api private
     attr_reader :kitchen_root
+
+    # @return [String] the absolute path to the directory into which all Test
+    #   Kitchen log files will be written
+    # @api private
     attr_reader :log_root
+
+    # @return [String] the absolute path to the directory containing test
+    #   suites and other testing-related file and directories
+    # @api private
     attr_reader :test_base_path
+
+    # @return [#read] the data loader that responds to a `#read` message,
+    #   returning a Hash data structure
+    # @api private
     attr_reader :loader
+
+    # @return [Symbol] the logging verbosity level
+    # @api private
     attr_accessor :log_level
 
-    # Creates a new configuration.
+    # Creates a new configuration, representing a particular testing
+    # configuration for a project.
     #
     # @param [Hash] options configuration
-    # @option options [#read] :loader
-    # @option options [String] :kitchen_root
-    # @option options [String] :log_root
-    # @option options [String] :test_base_path
-    # @option options [Symbol] :log_level
+    # @option options [#read] :loader an object that responds to `#read` with
+    #   a Hash structure suitable for manipulating
+    #   (default: `Kitchen::Loader::YAML.new`)
+    # @option options [String] :kitchen_root an absolute path to the root of a
+    #   Test Kitchen project, usually containing a `.kitchen.yml` file
+    #   (default `Dir.pwd`)
+    # @option options [String] :log_root an absolute path to the directory
+    #   into which all Test Kitchen log files will be written
+    #   (default: `"#{kitchen_root}/.kitchen/logs"`)
+    # @option options [String] :test_base_path an absolute path to the
+    #   directory containing test suites and other testing-related files and
+    #   directories (default: `"#{kitchen_root}/test/integration"`)
+    # @option options [Symbol] :log_level the log level verbosity that the
+    #   loggers will use when outputing information (default: `:info`)
     def initialize(options = {})
       @loader         = options.fetch(:loader) { Kitchen::Loader::YAML.new }
       @kitchen_root   = options.fetch(:kitchen_root) { Dir.pwd }
@@ -46,20 +98,20 @@ module Kitchen
       @test_base_path = options.fetch(:test_base_path) { default_test_base_path }
     end
 
-    # @return [Array<Instance>] all instances, resulting from all platform and
-    #   suite combinations
+    # @return [Collection<Instance>] all instances, resulting from all
+    #   platform and suite combinations
     def instances
       @instances ||= Collection.new(build_instances)
     end
 
-    # @return [Array<Platform>] all defined platforms which will be used in
-    #   convergence integration
+    # @return [Collection<Platform>] all defined platforms which will be used
+    #   in convergence integration
     def platforms
       @platforms ||= Collection.new(
         data.platform_data.map { |pdata| Platform.new(pdata) })
     end
 
-    # @return [Array<Suite>] all defined suites which will be used in
+    # @return [Collection<Suite>] all defined suites which will be used in
     #   convergence integration
     def suites
       @suites ||= Collection.new(
@@ -68,24 +120,51 @@ module Kitchen
 
     private
 
+    # Builds the filtered list of Instance objects.
+    #
+    # @return [Array<Instance] an array of Instances
+    # @api private
     def build_instances
       filter_instances.map.with_index do |(suite, platform), index|
         new_instance(suite, platform, index)
       end
     end
 
+    # Returns an object which can generate configuration hashes for all the
+    # primary Test Kitchen objects such as Drivers, Provisioners, etc.
+    #
+    # @return [DataMunger] a data manipulator
+    # @api private
     def data
       @data ||= DataMunger.new(loader.read, kitchen_config)
     end
 
+    # Determines the default absolute path to a log directory, based on the
+    # value of `#kitchen_root`.
+    #
+    # @return [String] an absolute path to the log directory
+    # @api private
     def default_log_root
       File.join(kitchen_root, Kitchen::DEFAULT_LOG_DIR)
     end
 
+    # Determines the default absolute path to the testing files directory,
+    # based on the the value of `#kitchen_root`.
+    #
+    # @return [String] an absolute path to the testing files directory
+    # @api private
     def default_test_base_path
       File.join(kitchen_root, Kitchen::DEFAULT_TEST_DIR)
     end
 
+    # Generates a filtered Array of tuples (Suite/Platform pairs) which is the
+    # cartesian product of suites and platforms. A Suite has two optional
+    # arrays (`#includes` and `#excludes`) which can be used to drop or
+    # select certain Platforms with which to join.
+    #
+    # @return [Array<Array<Suite, Platform>>] an Array of Suite/Platform
+    #   tuples
+    # @api private
     def filter_instances
       suites.product(platforms).select do |suite, platform|
         if !suite.includes.empty?
@@ -98,10 +177,21 @@ module Kitchen
       end
     end
 
+    # Determines the String name for an Instance, given a Suite and a Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @return [String] an Instance name
+    # @api private
     def instance_name(suite, platform)
       Instance.name_for(suite, platform)
     end
 
+    # Generates the immutable Test Kitchen configuration and reasonable
+    # defaults for Drivers and Provisioners.
+    #
+    # @return [Hash] a configuration Hash
+    # @api private
     def kitchen_config
       @kitchen_config ||= {
         :defaults => {
@@ -110,20 +200,40 @@ module Kitchen
         },
         :kitchen_root   => kitchen_root,
         :test_base_path => test_base_path,
-        :log_level      => log_level,
+        :log_level      => log_level
       }
     end
 
+    # Builds a newly configured Busser object, for a given a Suite and Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @return [Busser] a new Busser object
+    # @api private
     def new_busser(suite, platform)
       bdata = data.busser_data_for(suite.name, platform.name)
       Busser.new(suite.name, bdata)
     end
 
+    # Builds a newly configured Driver object, for a given Suite and Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @return [Driver] a new Driver object
+    # @api private
     def new_driver(suite, platform)
       ddata = data.driver_data_for(suite.name, platform.name)
       Driver.for_plugin(ddata[:name], ddata)
     end
 
+    # Builds a newly configured Instance object, for a given Suite and
+    # Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @param index [Integer] an index used for colorizing output
+    # @return [Instance] a new Instance object
+    # @api private
     def new_instance(suite, platform, index)
       Instance.new(
         :busser       => new_busser(suite, platform),
@@ -136,22 +246,44 @@ module Kitchen
       )
     end
 
+    # Builds a newly configured Logger object, for a given Suite and
+    # Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @param index [Integer] an index used for colorizing output
+    # @return [Logger] a new Logger object
+    # @api private
     def new_logger(suite, platform, index)
       name = instance_name(suite, platform)
       Logger.new(
         :stdout   => STDOUT,
         :color    => Color::COLORS[index % Color::COLORS.size].to_sym,
         :logdev   => File.join(log_root, "#{name}.log"),
-        :level    => Util.to_logger_level(self.log_level),
+        :level    => Util.to_logger_level(log_level),
         :progname => name
       )
     end
 
+    # Builds a newly configured Provisioner object, for a given Suite and
+    # Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @return [Provisioner] a new Provisioner object
+    # @api private
     def new_provisioner(suite, platform)
       pdata = data.provisioner_data_for(suite.name, platform.name)
       Provisioner.for_plugin(pdata[:name], pdata)
     end
 
+    # Builds a newly configured StateFile object, for a given Suite and
+    # Platform.
+    #
+    # @param suite [Suite,#name] a Suite
+    # @param platform [Platform,#name] a Platform
+    # @return [StateFile] a new StateFile object
+    # @api private
     def new_state_file(suite, platform)
       StateFile.new(kitchen_root, instance_name(suite, platform))
     end

data/lib/kitchen/configurable.rb

@@ -0,0 +1,314 @@
+# -*- 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.
+
+require "thor/util"
+
+require "kitchen/lazy_hash"
+
+module Kitchen
+
+  # A mixin for providing configuration-related behavior such as default
+  # config (static, computed, inherited), required config, local path
+  # expansion, etc.
+  #
+  # @author Fletcher Nichol <fnichol@nichol.ca>
+  module Configurable
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # @return [Kitchen::Instance] the associated instance
+    attr_reader :instance
+
+    # A lifecycle method that should be invoked when the object is about ready
+    # to be used. A reference to an Instance is required as configuration
+    # dependant data may be access through an Instance. This also acts as a
+    # hook point where the object may wish to perform other last minute
+    # checks, validations, or configuration expansions.
+    #
+    # @param instance [Instance] an associated instance
+    # @return [self] itself, for use in chaining
+    # @raise [ClientError] if instance parameter is nil
+    def finalize_config!(instance)
+      if instance.nil?
+        raise ClientError, "Instance must be provided to #{self}"
+      end
+
+      @instance = instance
+      expand_paths!
+      validate_config!
+
+      self
+    end
+
+    # Provides hash-like access to configuration keys.
+    #
+    # @param attr [Object] configuration key
+    # @return [Object] value at configuration key
+    def [](attr)
+      config[attr]
+    end
+
+    # Find an appropriate path to a file or directory, based on graceful
+    # fallback rules or returns nil if path cannot be determined.
+    #
+    # Given an instance with suite named `"server"`, a `test_base_path` of
+    # `"/a/b"`, and a path segement of `"roles"` then following will be tried
+    # in order (first match that exists wins):
+    #
+    # 1. /a/b/server/roles
+    # 2. /a/b/roles
+    # 3. $PWD/roles
+    #
+    # @param path [String] the base path segment to search for
+    # @param opts [Hash] options
+    # @option opts [Symbol] :type either `:file` or `:directory` (default)
+    # @option opts [Symbol] :base_path a custom base path to search under,
+    #   default uses value from `config[:test_base_path]`
+    # @return [String] path to the existing file or directory, or nil if file
+    #   or directory was not found
+    # @raise [UserError] if `config[:test_base_path]` is used and is not set
+    def calculate_path(path, opts = {})
+      type = opts.fetch(:type, :directory)
+      base = opts.fetch(:base_path) do
+        config.fetch(:test_base_path) do |key|
+          raise UserError, "#{key} is not found in #{self}"
+        end
+      end
+
+      [
+        File.join(base, instance.suite.name, path),
+        File.join(base, path),
+        File.join(Dir.pwd, path)
+      ].find do |candidate|
+        type == :directory ? File.directory?(candidate) : File.file?(candidate)
+      end
+    end
+
+    # Returns an array of configuration keys.
+    #
+    # @return [Array] array of configuration keys
+    def config_keys
+      config.keys
+    end
+
+    # Returns a Hash of configuration and other useful diagnostic information.
+    #
+    # @return [Hash] a diagnostic hash
+    def diagnose
+      result = Hash.new
+      config_keys.sort.each { |k| result[k] = config[k] }
+      result
+    end
+
+    private
+
+    # @return [LzayHash] a configuration hash
+    # @api private
+    attr_reader :config
+
+    # Initializes an internal configuration hash. The hash may contain
+    # callable blocks as values that are meant to be called lazily. This
+    # method is intended to be included in an object's .initialize method.
+    #
+    # @param config [Hash] initial provided configuration
+    # @api private
+    def init_config(config)
+      @config = LazyHash.new(config, self)
+      self.class.defaults.each do |attr, value|
+        @config[attr] = value unless @config.key?(attr)
+      end
+    end
+
+    # Expands file paths for certain configuration values. A configuration
+    # value is marked for file expansion with a expand_path_for declaration
+    # in the included class.
+    #
+    # @api private
+    def expand_paths!
+      root_path = config[:kitchen_root] || Dir.pwd
+      expanded_paths = LazyHash.new(self.class.expanded_paths, self).to_hash
+
+      expanded_paths.each do |key, should_expand|
+        next if !should_expand || config[key].nil?
+
+        config[key] = File.expand_path(config[key], root_path)
+      end
+    end
+
+    # Runs all validations set up for the included class. Each validation is
+    # for a specific configuration attribute and has an associated callable
+    # block. Each validation block is called with the attribute, its value,
+    # and the included object for context.
+    #
+    # @api private
+    def validate_config!
+      self.class.validations.each do |attr, block|
+        block.call(attr, config[attr], self)
+      end
+    end
+
+    # Class methods which will be mixed in on inclusion of Configurable module.
+    module ClassMethods
+
+      # Sets a sane default value for a configuration attribute. These values
+      # can be overridden by provided configuration or in a subclass with
+      # another default_config declaration.
+      #
+      # @example a nil default value
+      #
+      #   default_config :i_am_nil
+      #
+      # @example a primitive default value
+      #
+      #   default_config :use_sudo, true
+      #
+      # @example a block to compute a default value
+      #
+      #   default_config :box_name do |subject|
+      #     subject.instance.platform.name
+      #   end
+      #
+      # @param attr [String] configuration attribute name
+      # @param value [Object, nil] static default value for attribute
+      # @yieldparam object [Object] a reference to the instantiated object
+      # @yieldreturn [Object, nil] dynamically computed value for the attribute
+      def default_config(attr, value = nil, &block)
+        defaults[attr] = block_given? ? block : value
+      end
+
+      # Ensures that an attribute which is a path will be fully expanded at
+      # the right time. This helps make the configuration unambiguous and much
+      # easier to debug and diagnose.
+      #
+      # Note that the file path expansion is only intended for paths on the
+      # local workstation invking the Test Kitchen code.
+      #
+      # @example the default usage
+      #
+      #   expand_path_for :data_path
+      #
+      # @example disabling path expansion with a falsey value
+      #
+      #   expand_path_for :relative_path, false
+      #
+      # @example using a block to determine whether or not to expand
+      #
+      #   expand_path_for :relative_or_not_path do |subject|
+      #     subject.instance.name =~ /default/
+      #   end
+      #
+      # @param attr [String] configuration attribute name
+      # @param value [Object, nil] whether or not to exand the file path
+      # @yieldparam object [Object] a reference to the instantiated object
+      # @yieldreturn [Object, nil] dynamically compute whether or not to
+      #   perform the file expansion
+      def expand_path_for(attr, value = true, &block)
+        expanded_paths[attr] = block_given? ? block : value
+      end
+
+      # Ensures that an attribute must have a non-nil, non-empty String value.
+      # The default behavior will be to raise a user error and thereby halting
+      # further configuration processing. Good use cases for require_config
+      # might be cloud provider credential keys and other similar data.
+      #
+      # @example a value that must not be nil or an empty String
+      #
+      #   required_config :cloud_api_token
+      #
+      # @example using a block to use custom validation logic
+      #
+      #   required_config :email do |attr, value, subject|
+      #     raise UserError, "Must be an email address" unless value =~ /@/
+      #   end
+      #
+      # @param attr [String] configuration attribute name
+      # @yieldparam attr [Symbol] the attribute name
+      # @yieldparam value [Object] the current value of the attribute
+      # @yieldparam object [Object] a reference to the instantiated object
+      def required_config(attr, &block)
+        if !block_given?
+          klass = self
+          block = lambda do |_, value, thing|
+            if value.nil? || value.to_s.empty?
+              attribute = "#{klass}#{thing.instance.to_str}#config[:#{attr}]"
+              raise UserError, "#{attribute} cannot be blank"
+            end
+          end
+        end
+        validations[attr] = block
+      end
+
+      # @return [Hash] a hash of attribute keys and default values which has
+      #   been merged with any superclass defaults
+      # @api private
+      def defaults
+        @defaults ||= Hash.new.merge(super_defaults)
+      end
+
+      # @return [Hash] a hash of defaults from the included class' superclass
+      #   if defined in the superclass, or an empty hash otherwise
+      # @api private
+      def super_defaults
+        if superclass.respond_to?(:defaults)
+          superclass.defaults
+        else
+          Hash.new
+        end
+      end
+
+      # @return [Hash] a hash of attribute keys and truthy/falsey values to
+      #   determine if said attribute needs to be fully file path expanded,
+      #   which has been merged with any superclass expanded paths
+      # @api private
+      def expanded_paths
+        @expanded_paths ||= Hash.new.merge(super_expanded_paths)
+      end
+
+      # @return [Hash] a hash of expanded paths from the included class'
+      #   superclass if defined in the superclass, or an empty hash otherwise
+      # @api private
+      def super_expanded_paths
+        if superclass.respond_to?(:expanded_paths)
+          superclass.expanded_paths
+        else
+          Hash.new
+        end
+      end
+
+      # @return [Hash] a hash of attribute keys and valudation callable blocks
+      #   which has been merged with any superclass valudations
+      # @api private
+      def validations
+        @validations ||= Hash.new.merge(super_validations)
+      end
+
+      # @return [Hash] a hash of validations from the included class'
+      #   superclass if defined in the superclass, or an empty hash otherwise
+      # @api private
+      def super_validations
+        if superclass.respond_to?(:validations)
+          superclass.validations
+        else
+          Hash.new
+        end
+      end
+    end
+  end
+end