Module: Beaker::DSL::Roles

Included in:
Beaker::DSL
Defined in:
lib/beaker/dsl/roles.rb

Overview

Identifying hosts.

This aids in reaching common subsets of hosts in a testing matrix.

It requires the class it is mixed into to provide the attribute ‘hosts` which contain the hosts to search, these should implement Host’s interface. They, at least, must have #[] and #to_s available and provide an array when #[](‘roles’) is called.

Also the constant Outcomes::FailTest needs to be defined it will be raised in error conditions

Instance Method Summary collapse

Instance Method Details

#add_role_def(role) ⇒ Object

Create a new role method for a given arbitrary role name. Makes it possible to be able to run commands without having to refer to role by String or Symbol. Will not add a new method definition if the name is already in use. Symbol or an Array of Strings or Symbols.

Examples:

Basic usage

add_role_def('myrole')
on myrole, "run command"

Parameters:

  • role (String, Symbol, Array[String,Symbol]) —

    The role that you wish to create a definition for, either a String



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/beaker/dsl/roles.rb', line 101

def add_role_def role
  if role.kind_of?(Array)
    role.each do |r|
      add_role_def r
    end
  else
    if not respond_to? role
      if role !~ /\A[[:alpha:]]+[a-zA-Z0-9_]*[!?=]?\Z/
        raise "Role name format error for '#{role}'.  Allowed characters are: \na-Z\n0-9 (as long as not at the beginning of name)\n'_'\n'?', '!' and '=' (only as individual last character at end of name)"
      end
      self.class.send :define_method, role.to_s do
        hosts_with_role = hosts_as role.to_sym
        if hosts_with_role.length == 1
          hosts_with_role = hosts_with_role.pop
        end
        hosts_with_role
      end
    end
  end
end

#agents ⇒ Array<Host>

The hosts for which [‘roles’] include ‘agent’

Examples:

Basic usage

agents.each do |agent|
  ...test each agent in turn...
end

Returns:

  • (Array<Host>) —

    May be empty



28
29
30
 
# File 'lib/beaker/dsl/roles.rb', line 28

def agents
  hosts_as 'agent'
end

#any_hosts_as?(role) ⇒ Boolean

Determine if there is a host or hosts with the given role defined if any_hosts_as?(:master)

puts "master is defined"

end

Examples:

Usage

Returns:

  • (Boolean) —

    True if there is a host with role, false otherwise



131
132
133
 
# File 'lib/beaker/dsl/roles.rb', line 131

def any_hosts_as?(role)
  hosts_as(role).length > 0
end

#dashboard ⇒ Host

The host for which [‘roles’] include ‘dashboard’

Examples:

Basic usage

on, agent, "curl https://#{database}/nodes/#{agent}"

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



71
72
73
 
# File 'lib/beaker/dsl/roles.rb', line 71

def dashboard
  find_host_with_role :dashboard
end

#database ⇒ Host

The host for which [‘roles’] include ‘database’

Examples:

Basic usage

on, agent, "curl -k http://#{database}:8080"

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



58
59
60
 
# File 'lib/beaker/dsl/roles.rb', line 58

def database
  find_host_with_role :database
end

#default ⇒ Host

The default host

- if only one host defined, then that host
OR
- host with 'default' as a role
OR
- host with 'master' as a role

Examples:

Basic usage

on, default, "curl https://#{database}/nodes/#{agent}"

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



89
90
91
 
# File 'lib/beaker/dsl/roles.rb', line 89

def default
  find_host_with_role :default
end

#find_at_most_one(role) ⇒ Host

Returns the host, or nil if not found

Parameters:

  • role (Symbol, String) —

    The role to find a host for

Returns:

  • (Host) —

    Returns the host, or nil if not found

Raises:

  • Raises a failure exception if more than one host that matches the specified role is found.



182
183
184
185
186
 
# File 'lib/beaker/dsl/roles.rb', line 182

def find_at_most_one role
  find_at_most_one_host_with_role(hosts, role)
rescue ArgumentError => e
  raise DSL::Outcomes::FailTest, e.to_s
end

#find_host_with_role(role) ⇒ Host

finds the appropriate number of hosts for a given role determines whether to allow no server using the masterless option

Parameters:

  • role (Symbol, String) —

    The role to find a host for

Returns:

  • (Host) —

    Returns the host, or nil if masterless and none are found for that role

Raises:

  • Throws an exception if an inappropriate number of hosts are found for that role



160
161
162
163
164
165
166
 
# File 'lib/beaker/dsl/roles.rb', line 160

def find_host_with_role role
  if (defined? options) && options[:masterless]
    find_at_most_one role
  else
    find_only_one role
  end
end

#find_only_one(role) ⇒ Host

Returns the host, if one and only one is found

Parameters:

  • role (Symbol, String) —

    The role to find a host for

Returns:

  • (Host) —

    Returns the host, if one and only one is found

Raises:

  • Raises a failure exception if one and only one host that matches the specified role is NOT found.



172
173
174
175
176
 
# File 'lib/beaker/dsl/roles.rb', line 172

def find_only_one role
  only_host_with_role(hosts, role)
rescue ArgumentError => e
  raise DSL::Outcomes::FailTest, e.to_s
end

#hosts_as(desired_role = nil) ⇒ Array<Host>

Select hosts that include a desired role from #hosts

Examples:

Basic usage

hairy = hosts_as :yak
hairy.each do |yak|
  on yak, 'shave'
end

Parameters:

  • desired_role (String, Symbol) (defaults to: nil) —

    The role to select for

Returns:

  • (Array<Host>) —

    The hosts that match desired_role, may be empty



148
149
150
 
# File 'lib/beaker/dsl/roles.rb', line 148

def hosts_as(desired_role = nil)
  hosts_with_role(hosts, desired_role)
end

#master ⇒ Host

The host for which [‘roles’] include ‘master’. If no host has the ‘master’ role, then use the host defined as ‘default’. If no host is defined as a ‘master’ and there is no ‘default’ host defined then it either raises an error (has a master), or it returns nil (masterless)

Examples:

Basic usage

on, master, 'cat /etc/puppet/puppet.conf'

Returns:

  • (Host) —

    Returns the host, or nil if not found & masterless

Raises:



45
46
47
 
# File 'lib/beaker/dsl/roles.rb', line 45

def master
  find_host_with_role :master
end