Module: Kitchen::Configurable

Included in:
Driver::Base, LifecycleHooks, Provisioner::Base, Transport::Base, Verifier::Base
Defined in:
lib/kitchen/configurable.rb

Overview

A mixin for providing configuration-related behavior such as default config (static, computed, inherited), required config, local path expansion, etc.

Author:

Defined Under Namespace

Modules: ClassMethods

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#instance ⇒ Kitchen::Instance (readonly)

Returns the associated instance.

Returns:



41
42
43
 
# File 'lib/kitchen/configurable.rb', line 41

def instance
  @instance
end

Class Method Details

.included(base) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Extends the including class with ClassMethods so that the default_config, required_config, and related DSL is available at the class level.

Parameters:

  • base (Class) —

    the class including this module



36
37
38
 
# File 'lib/kitchen/configurable.rb', line 36

def self.included(base)
  base.extend(ClassMethods)
end

Instance Method Details

#[](attr) ⇒ Object

Provides hash-like access to configuration keys.

Parameters:

  • attr (Object) —

    configuration key

Returns:

  • (Object) —

    value at configuration key



68
69
70
 
# File 'lib/kitchen/configurable.rb', line 68

def [](attr)
  config[attr]
end

#bourne_shell? ⇒ TrueClass, FalseClass

Returns true if :shell_type is "bourne" (or unset, for backwards compatibility).

Returns:

  • (TrueClass, FalseClass) —

    true if :shell_type is "bourne" (or unset, for backwards compatibility)



74
75
76
77
 
# File 'lib/kitchen/configurable.rb', line 74

def bourne_shell?
  shell_type = instance.platform.respond_to?(:shell_type) ? instance.platform.shell_type : nil
  ["bourne", nil].include?(shell_type)
end

#calculate_path(path, opts = {}) ⇒ String

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 segment of "roles" then the following will be tried in order (first match that exists wins):

  1. /a/b/server/roles
  2. /a/b/roles
  3. $PWD/roles

Parameters:

  • path (String) —

    the base path segment to search for

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :type (Symbol) —

    either :file or :directory (default)

  • :base_path (Symbol) —

    a custom base path to search under, default uses value from config[:test_base_path]

Returns:

  • (String) —

    path to the existing file or directory, or nil if file or directory was not found

Raises:

  • (UserError) —

    if config[:test_base_path] is used and is not set



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/kitchen/configurable.rb', line 98

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

#config_keys ⇒ Array

Returns an array of configuration keys.

Returns:

  • (Array) —

    array of configuration keys



118
119
120
 
# File 'lib/kitchen/configurable.rb', line 118

def config_keys
  config.keys
end

#diagnose ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information.

Returns:

  • (Hash) —

    a diagnostic hash



125
126
127
128
129
 
# File 'lib/kitchen/configurable.rb', line 125

def diagnose
  result = {}
  config_keys.sort.each { |k| result[k] = config[k] }
  result
end

#diagnose_plugin ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information associated with the plugin itself (such as loaded version, class name, etc.).

Returns:

  • (Hash) —

    a diagnostic hash



136
137
138
139
140
141
 
# File 'lib/kitchen/configurable.rb', line 136

def diagnose_plugin
  result = {}
  result[:name] = name
  result.merge!(self.class.diagnose)
  result
end

#finalize_config!(instance) ⇒ self

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 dependent data may be accessed 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.

Parameters:

  • instance (Instance) —

    an associated instance

Returns:

  • (self) —

    itself, for use in chaining

Raises:



52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/kitchen/configurable.rb', line 52

def finalize_config!(instance)
  raise ClientError, "Instance must be provided to #{self}" if instance.nil?

  @instance = instance
  expand_paths!
  deprecate_config!
  validate_config!
  load_needed_dependencies!

  self
end

#name ⇒ String

Returns the name of this plugin, suitable for display in a CLI.

Returns:

  • (String) —

    name of this plugin



146
147
148
 
# File 'lib/kitchen/configurable.rb', line 146

def name
  self.class.name.split("::").last
end

#powershell_shell? ⇒ TrueClass, FalseClass

Returns true if :shell_type is "powershell".

Returns:

  • (TrueClass, FalseClass) —

    true if :shell_type is "powershell"



151
152
153
154
 
# File 'lib/kitchen/configurable.rb', line 151

def powershell_shell?
  shell_type = instance.platform.respond_to?(:shell_type) ? instance.platform.shell_type : nil
  ["powershell"].include?(shell_type)
end

#remote_path_join(*parts) ⇒ String

Builds a file path based on the :os_type ("windows" or "unix").

Returns:

  • (String) —

    joined path for instance's os_type



159
160
161
162
 
# File 'lib/kitchen/configurable.rb', line 159

def remote_path_join(*parts)
  path = File.join(*parts)
  windows_os? ? path.tr("/", "\\") : path.tr("\\", "/")
end

#unix_os? ⇒ TrueClass, FalseClass

Returns true if :os_type is "unix" (or unset, for backwards compatibility).

Returns:

  • (TrueClass, FalseClass) —

    true if :os_type is "unix" (or unset, for backwards compatibility)



166
167
168
169
 
# File 'lib/kitchen/configurable.rb', line 166

def unix_os?
  os_type = instance.platform.respond_to?(:os_type) ? instance.platform.os_type : nil
  ["unix", nil].include?(os_type)
end

#verify_dependencies ⇒ Object

Performs whatever tests that may be required to ensure that this plugin will be able to function in the current environment. This may involve checking for the presence of certain directories, software installed, etc.

Raises:

  • (UserError) —

    if the plugin will not be able to perform or if a documented dependency is missing from the system



178
179
180
 
# File 'lib/kitchen/configurable.rb', line 178

def verify_dependencies
  # this method may be left unimplemented if that is applicable
end

#windows_os? ⇒ TrueClass, FalseClass

Returns true if :os_type is "windows".

Returns:

  • (TrueClass, FalseClass) —

    true if :os_type is "windows"



183
184
185
186
 
# File 'lib/kitchen/configurable.rb', line 183

def windows_os?
  os_type = instance.platform.respond_to?(:os_type) ? instance.platform.os_type : nil
  ["windows"].include?(os_type)
end