Module: Beaker::DSL::Helpers::HostHelpers

Included in:
Beaker::DSL::Helpers
Defined in:
lib/beaker/dsl/helpers/host_helpers.rb

Overview

Methods that help you interact and manage the state of your Beaker SUTs, these methods do not require puppet to be installed to execute correctly

Instance Method Summary collapse

Instance Method Details

#add_system32_hosts_entry(host, opts = {}) ⇒ Object

Configure a host entry on the give host @example: will add a host entry for forge.puppetlabs.com

add_system32_hosts_entry(host, { :ip => '23.251.154.122', :name => 'forge.puppetlabs.com' })

Returns:

  • nil



324
325
326
327
328
329
330
331
332
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 324

def add_system32_hosts_entry(host, opts = {})
  if host['platform'] =~ /windows/
    hosts_file = "C:\\Windows\\System32\\Drivers\\etc\\hosts"
    host_entry = "#{opts['ip']}`t`t#{opts['name']}"
    on host, powershell("\$text = \\\"#{host_entry}\\\"; Add-Content -path '#{hosts_file}' -value \$text")
  else
    raise "nothing to do for #{host.name} on #{host['platform']}"
  end
end

#check_for_package(host, package_name) ⇒ Boolean

Check to see if a package is installed on a remote host

Parameters:

  • host (Host) —

    A host object

  • package_name (String) —

    Name of the package to check for.

Returns:

  • (Boolean) —

    true/false if the package is found



305
306
307
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 305

def check_for_package host, package_name
  host.check_for_package package_name
end

#create_remote_file(hosts, file_path, file_content, opts = {}) ⇒ Result

Note:

This method uses Tempfile in Ruby’s STDLIB as well as #scp_to.

Create a remote file out of a string

Parameters:

  • hosts (Host, #do_scp_to) —

    One or more hosts (or some object that responds like Host#do_scp_from.

  • file_path (String) —

    A remote path to place file_content at.

  • file_content (String) —

    The contents of the file to be placed.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

  • :protocol (String) —

    Name of the underlying transfer method. Valid options are ‘scp’ or ‘rsync’.

Returns:

  • (Result) —

    Returns the result of the underlying SCP operation.



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 242

def create_remote_file(hosts, file_path, file_content, opts = {})
  Tempfile.open 'beaker' do |tempfile|
    File.open(tempfile.path, 'w') {|file| file.puts file_content }

    opts[:protocol] ||= 'scp'
    case opts[:protocol]
      when 'scp'
        scp_to hosts, tempfile.path, file_path, opts
      when 'rsync'
        rsync_to hosts, tempfile.path, file_path, opts
      else
        logger.debug "Unsupported transfer protocol, returning nil"
        nil
    end
  end
end

#create_tmpdir_on(host, path_prefix = '', user = nil) ⇒ String+

Create a temp directory on remote host owned by specified user.

directory. directory. If no username is specified defaults to the currently logged in user per host

Parameters:

  • host (Host, Array<Host>, String, Symbol) —

    One or more hosts to act upon, or a role (String or Symbol) that identifies one or more hosts.

  • path_prefix (String) (defaults to: '') —

    A remote path prefix for the new temp

  • user (String) (defaults to: nil) —

    The name of user that should own the temp

Returns:

  • (String, Array<String>) —

    Returns the name of the newly-created dir, or an array of names of newly-created dirs per-host



480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 480

def create_tmpdir_on(host, path_prefix = '', user=nil)

  block_on host do | host |
    # use default user logged into this host
    if not user
      user = host['user']
    end

    if not on(host, "getent passwd #{user}").exit_code == 0
      raise "User #{user} does not exist on #{host}."
    end

    if defined? host.tmpdir
      dir = host.tmpdir(path_prefix)
      on host, "chown #{user}:#{user} #{dir}"
      dir
    else
      raise "Host platform not supported by `create_tmpdir_on`."
    end
  end
end

#curl_on(host, cmd, opts = {}, &block) ⇒ Object

Run a curl command on the provided host(s)

Parameters:

  • host (Host, Array<Host>, String, Symbol) —

    One or more hosts to act upon, or a role (String or Symbol) that identifies one or more hosts.

  • cmd (String, Command) —

    The curl command to execute on host.

  • block (Proc) —

    Additional actions or assertions.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.



367
368
369
370
371
372
373
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 367

def curl_on(host, cmd, opts = {}, &block)
  if options.is_pe? #check global options hash
    on host, "curl --tlsv1 %s" % cmd, opts, &block
  else
    on host, "curl %s" % cmd, opts, &block
  end
end

#curl_with_retries(desc, host, url, desired_exit_codes, max_retries = 60, retry_interval = 1) ⇒ Object 



376
377
378
379
380
381
382
383
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 376

def curl_with_retries(desc, host, url, desired_exit_codes, max_retries = 60, retry_interval = 1)
  opts = {
    :desired_exit_codes => desired_exit_codes,
    :max_retries => max_retries,
    :retry_interval => retry_interval
  }
  retry_on(host, "curl -m 1 #{url}", opts)
end

#deploy_package_repo(host, path, name, version) ⇒ Object

Note:

To ensure the repo configs are available for deployment, you should run ‘rake pl:jenkins:deb_repo_configs` and `rake pl:jenkins:rpm_repo_configs` on your project checkout

Deploy packaging configurations generated by github.com/puppetlabs/packaging to a host.

Parameters:

  • host (Host)
  • path (String) —

    The path to the generated repository config files. ex: /myproject/pkg/repo_configs

  • name (String) —

    A human-readable name for the repository

  • version (String) —

    The version of the project, as used by the packaging tools. This can be determined with ‘rake pl:print_build_params` from the packaging repo.



225
226
227
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 225

def deploy_package_repo host, path, name, version
  host.deploy_package_repo path, name, version
end

#exit_code ⇒ Object

Deprecated.

An proxy for the last Result#exit_code returned by a method that makes remote calls. Use the Result object returned by the method directly instead. For Usage see Result.



136
137
138
139
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 136

def exit_code
  return nil if @result.nil?
  @result.exit_code
end

#install_package(host, package_name, package_version = nil) ⇒ Result

Install a package on a host

Parameters:

  • host (Host) —

    A host object

  • package_name (String) —

    Name of the package to install

Returns:

  • (Result) —

    An object representing the outcome of *install command*.



295
296
297
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 295

def install_package host, package_name, package_version = nil
  host.install_package package_name, '', package_version
end

#on(host, command, opts = {}, &block) ⇒ Result

The primary method for executing commands on some set of hosts.

Examples:

Most basic usage

on hosts, 'ls /tmp'

Allowing additional exit codes to pass

on agents, 'puppet agent -t', :acceptable_exit_codes => [0,2]

Using the returned result for any kind of checking

if on(host, 'ls -la ~').stdout =~ /\.bin/
  ...do some action...
end

Using TestCase helpers from within a test.

agents.each do |agent|
  on agent, 'cat /etc/puppet/puppet.conf' do
    assert_match stdout, /server = #{master}/, 'WTF Mate'
  end
end

Using a role (defined in a String) to identify the host

on "master", "echo hello"

Using a role (defined in a Symbol) to identify the host

on :dashboard, "echo hello"

Parameters:

  • host (Host, Array<Host>, String, Symbol) —

    One or more hosts to act upon, or a role (String or Symbol) that identifies one or more hosts.

  • command (String, Command) —

    The command to execute on host.

  • block (Proc) —

    Additional actions or assertions.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

Returns:

  • (Result) —

    An object representing the outcome of command.

Raises:

  • (FailTest) —

    Raises an exception if command obviously fails.



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 53

def on(host, command, opts = {}, &block)
  block_on host do | host |
    cur_command = command
    if command.is_a? Command
      cur_command = command.cmd_line(host)
    end
    cmd_opts = {}
    #add any additional environment variables to the command
    if opts[:environment]
      cmd_opts['ENV'] = opts[:environment]
    end
    @result = host.exec(Command.new(cur_command.to_s, [], cmd_opts), opts)

    # Also, let additional checking be performed by the caller.
    if block_given?
      case block.arity
        #block with arity of 0, just hand back yourself
        when 0
          yield self
        #block with arity of 1 or greater, hand back the result object
        else
          yield @result
      end
    end
    @result
  end
end

#retry_on(host, command, opts = {}, &block) ⇒ Object

This command will execute repeatedly until success or it runs out with an error

Parameters:

  • host (Host, Array<Host>, String, Symbol) —

    One or more hosts to act upon, or a role (String or Symbol) that identifies one or more hosts.

  • command (String, Command) —

    The command to execute on host.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

  • block (Proc) —

    Additional actions or assertions.

Options Hash (opts):

  • :desired_exit_codes (Array<Fixnum>, Fixnum) — default: 0 —

    An array or integer exit code(s) that should be considered acceptable. An error will be thrown if the exit code never matches one of the values in this list.

  • :max_retries (Fixnum) — default: 60 —

    number of times the command will be tried before failing

  • :retry_interval (Float) — default: 1 —

    number of seconds that we’ll wait between tries

  • :verbose (Boolean) — default: false 


402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 402

def retry_on(host, command, opts = {}, &block)
  option_exit_codes     = opts[:desired_exit_codes]
  option_max_retries    = opts[:max_retries].to_i
  option_retry_interval = opts[:retry_interval].to_f
  desired_exit_codes    = option_exit_codes ? [option_exit_codes].flatten : [0]
  desired_exit_codes    = [0] if desired_exit_codes.empty?
  max_retries           = option_max_retries == 0 ? 60 : option_max_retries  # nil & "" both return 0
  retry_interval        = option_retry_interval == 0 ? 1 : option_retry_interval
  verbose               = true.to_s == opts[:verbose]

  log_prefix = host.log_prefix
  logger.debug "\n#{log_prefix} #{Time.new.strftime('%H:%M:%S')}$ #{command}"
  logger.debug "  Trying command #{max_retries} times."
  logger.debug ".", add_newline=false

  result = on host, command, {:acceptable_exit_codes => (0...127), :silent => !verbose}, &block
  num_retries = 0
  until desired_exit_codes.include?(result.exit_code)
    sleep retry_interval
    result = on host, command, {:acceptable_exit_codes => (0...127), :silent => !verbose}, &block
    num_retries += 1
    logger.debug ".", add_newline=false
    if (num_retries > max_retries)
      logger.debug "  Command \`#{command}\` failed."
      fail("Command \`#{command}\` failed.")
    end
  end
  logger.debug "\n#{log_prefix} #{Time.new.strftime('%H:%M:%S')}$ #{command} ostensibly successful."
  result
end

#rsync_to(host, from_path, to_path, opts = {}) ⇒ Result

Note:

rsync is required on the local host.

Move a local file or directory to a remote host using rsync

Parameters:

  • host (Host, #do_scp_to) —

    A host object that responds like Host.

  • from_path (String) —

    A local path to a file or directory.

  • to_path (String) —

    A remote path to copy from_path to.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

Returns:

  • (Result) —

    Returns the result of the rsync operation



199
200
201
202
203
204
205
206
207
208
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 199

def rsync_to host, from_path, to_path, opts = {}
  block_on host do | host |
    if host['platform'] =~ /windows/ && to_path.match('`cygpath')
      result = host.echo "#{to_path}"
      to_path = result.raw_output.chomp
    end
    @result = host.do_rsync_to(from_path, to_path, opts)
    @result
  end
end

#run_script(script, opts = {}, &block) ⇒ Object

Move a local script to default host and execute it

See Also:



285
286
287
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 285

def run_script(script, opts = {}, &block)
  run_script_on(default, script, opts, &block)
end

#run_script_on(host, script, opts = {}, &block) ⇒ Result

Note:

this relies on #on and #scp_to

Move a local script to a remote host and execute it

Parameters:

  • host (Host, #do_scp_to) —

    One or more hosts (or some object that responds like Host#do_scp_from.

  • script (String) —

    A local path to find an executable script at.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

  • block (Proc) —

    Additional tests to run after script has executed

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

Returns:

  • (Result) —

    Returns the result of the underlying SCP operation.



270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 270

def run_script_on(host, script, opts = {}, &block)
  # this is unsafe as it uses the File::SEPARATOR will be set to that
  # of the coordinator node.  This works for us because we use cygwin
  # which will properly convert the paths.  Otherwise this would not
  # work for running tests on a windows machine when the coordinator
  # that the harness is running on is *nix. We should use
  # {Beaker::Host#temp_path} instead. TODO
  remote_path = File.join("", "tmp", File.basename(script))

  scp_to host, script, remote_path
  on host, remote_path, opts, &block
end

#scp_from(host, from_path, to_path, opts = {}) ⇒ Result

Note:

If using Host for the hosts scp is not required on the system as it uses Ruby’s net/scp library. The net-scp gem however is required (and specified in the gemspec).

Move a file from a remote to a local path

Parameters:

  • host (Host, #do_scp_from) —

    One or more hosts (or some object that responds like Host#do_scp_from.

  • from_path (String) —

    A remote path to a file.

  • to_path (String) —

    A local path to copy from_path to.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

Returns:

  • (Result) —

    Returns the result of the SCP operation



154
155
156
157
158
159
160
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 154

def scp_from host, from_path, to_path, opts = {}
  block_on host do | host |
    @result = host.do_scp_from(from_path, to_path, opts)
    @result.log logger
    @result
  end
end

#scp_to(host, from_path, to_path, opts = {}) ⇒ Result

Note:

If using Host for the hosts scp is not required on the system as it uses Ruby’s net/scp library. The net-scp gem however is required (and specified in the gemspec. When using SCP with Windows it will now auto expand path when using ‘cygpath instead of failing or requiring full path

Move a local file to a remote host using scp

Parameters:

  • host (Host, #do_scp_to) —

    One or more hosts (or some object that responds like Host#do_scp_to.

  • from_path (String) —

    A local path to a file.

  • to_path (String) —

    A remote path to copy from_path to.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

Returns:

  • (Result) —

    Returns the result of the SCP operation



177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 177

def scp_to host, from_path, to_path, opts = {}
  block_on host do | host |
    if host['platform'] =~ /windows/ && to_path.match('`cygpath')
      result = on host, "echo #{to_path}"
      to_path = result.raw_output.chomp
    end
    @result = host.do_scp_to(from_path, to_path, opts)
    @result.log logger
    @result
  end
end

#shell(command, opts = {}, &block) ⇒ Result

The method for executing commands on the default host

Examples:

Most basic usage

shell 'ls /tmp'

Allowing additional exit codes to pass

shell 'puppet agent -t', :acceptable_exit_codes => [0,2]

Using the returned result for any kind of checking

if shell('ls -la ~').stdout =~ /\.bin/
  ...do some action...
end

Using TestCase helpers from within a test.

agents.each do |agent|
  shell('cat /etc/puppet/puppet.conf') do |result|
    assert_match result.stdout, /server = #{master}/, 'WTF Mate'
  end
end

Parameters:

  • command (String, Command) —

    The command to execute on host.

  • block (Proc) —

    Additional actions or assertions.

  • opts (Hash{Symbol=>String}) (defaults to: {}) —

    Options to alter execution.

Options Hash (opts):

  • :silent (Boolean) — default: false —

    Do not produce log output

  • :acceptable_exit_codes (Array<Fixnum>) — default: [0] —

    An array (or range) of integer exit codes that should be considered acceptable. An error will be thrown if the exit code does not match one of the values in this list.

  • :environment (Hash{String=>String}) — default: {} —

    These will be treated as extra environment variables that should be set before running the command.

Returns:

  • (Result) —

    An object representing the outcome of command.

Raises:

  • (FailTest) —

    Raises an exception if command obviously fails.



107
108
109
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 107

def shell(command, opts = {}, &block)
  on(default, command, opts, &block)
end

#stderr ⇒ Object

Deprecated.

An proxy for the last Result#stderr returned by a method that makes remote calls. Use the Result object returned by the method directly instead. For Usage see Result.



126
127
128
129
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 126

def stderr
  return nil if @result.nil?
  @result.stderr
end

#stdout ⇒ Object

Deprecated.

An proxy for the last Result#stdout returned by a method that makes remote calls. Use the Result object returned by the method directly instead. For Usage see Result.



116
117
118
119
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 116

def stdout
  return nil if @result.nil?
  @result.stdout
end

#upgrade_package(host, package_name) ⇒ Result

Upgrade a package on a host. The package must already be installed

Parameters:

  • host (Host) —

    A host object

  • package_name (String) —

    Name of the package to install

Returns:

  • (Result) —

    An object representing the outcome of *upgrade command*.



315
316
317
 
# File 'lib/beaker/dsl/helpers/host_helpers.rb', line 315

def upgrade_package host, package_name
  host.upgrade_package package_name
end