Module: Kitchen::Configurable

Included in:
Driver::Base, Driver::SSHBase, 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.

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:



34
35
36
 
# File 'lib/kitchen/configurable.rb', line 34

def instance
  @instance
end

Class Method Details

.included(base) ⇒ Object 



29
30
31
 
# File 'lib/kitchen/configurable.rb', line 29

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



61
62
63
 
# File 'lib/kitchen/configurable.rb', line 61

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)



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

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 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`

Returns:

  • (String) —

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

Raises:



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/kitchen/configurable.rb', line 91

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



111
112
113
 
# File 'lib/kitchen/configurable.rb', line 111

def config_keys
  config.keys
end

#diagnose ⇒ Hash

Returns a Hash of configuration and other useful diagnostic information.

Returns:

  • (Hash) —

    a diagnostic hash



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

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



129
130
131
132
133
134
 
# File 'lib/kitchen/configurable.rb', line 129

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 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.

Parameters:

  • instance (Instance) —

    an associated instance

Returns:

  • (self) —

    itself, for use in chaining

Raises:



45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/kitchen/configurable.rb', line 45

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



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

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”`



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

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



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

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)



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

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



171
172
173
 
# File 'lib/kitchen/configurable.rb', line 171

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”`



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

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