module Testable

rubocop:disable Style/DocumentationMethod

Constants

NATIVE_QUALIFIERS
VERSION

Attributes

browser[RW]

This accessor is needed so that Testable itself can provide a browser reference to indicate connection to WebDriver. This is a class-level access to the browser.

browser[RW]

This accessor is needed so that internal API calls, like `markup` or `text`, have access to the browser instance. This is also necessary in order for element handling to be called appropriately on the a valid browser instance. This is an instance-level access to whatever browser Testable is using.

parent[R]

This accessor is needed so that the parent of a region is recognized as part of the overall execution context of Testable.

region_element[R]

This accessor is needed so that the region_element is recognized as part of the overall execution context of Testable.

Public Class Methods

api() click to toggle source

This provides the API that is defined by Testable when you have a working model, such as a page object.

# File lib/testable.rb, line 232
def api
  methods - Object.public_methods
end
configure() { |self| ... } click to toggle source

Provides a means to allow a configure block on Testable. This allows you to setup Testable, as such:

Testable.configure do |config|
  config.driver_timeout = 5
  config.wire_level_logging = :info
  config.log_level = :debug
end
# File lib/testable.rb, line 101
def configure
  yield self
end
driver_timeout=(value) click to toggle source

Watir provides a default timeout of 30 seconds. This allows you to change that in the Testable context. For example:

Testable.driver_timeout = 5

This would equivalent to doing this:

Watir.default_timeout = 5
# File lib/testable.rb, line 113
def driver_timeout=(value)
  Watir.default_timeout = value
end
included(caller) click to toggle source

This is the core method of Testable which makes the various components of the framework available to tests.

# File lib/testable.rb, line 21
def self.included(caller)
  caller.extend Testable::Pages::Attribute
  caller.extend Testable::Pages::Element
  caller.extend Testable::Pages::Region
  caller.__send__ :include, Testable::Ready
  caller.__send__ :include, Testable::Pages
  caller.__send__ :include, Testable::Element::Locator
  caller.__send__ :include, Testable::DataSetter
end
log_level() click to toggle source

To query what level is being logged, do this:

Testable.log_level

The logging level will be UNKNOWN by default.

# File lib/testable.rb, line 149
def log_level
  %i[DEBUG INFO WARN ERROR FATAL UNKNOWN][logger.level]
end
log_level=(value) click to toggle source

To enable logging, do this:

Testable.log_level = :DEBUG
Testable.log_level = 'DEBUG'
Testable.log_level = 0

This can accept any of a Symbol / String / Integer as an input To disable all logging, which is the case by default, do this:

Testable.log_level = :UNKNOWN
# File lib/testable.rb, line 140
def log_level=(value)
  logger.level = value
end
log_path=(logdev) click to toggle source

The writer method allows you to configure where you want the output of the Testable logs to go, with the default being standard output. Here is how you could change this to a specific file:

Testable.log_path = 'testable.log'
# File lib/testable.rb, line 158
def log_path=(logdev)
  logger.reopen(logdev)
end
logger() click to toggle source

The Testable logger object. To log messages:

Testable.logger.info('Some information.')
Testable.logger.debug('Some diagnostics')

To alter or check the current logging level, you can call `.log_level=` or `.log_level`. By default the logger will output all messages to the standard output ($stdout) but it can be altered to log to a file or to another IO location by calling `.log_path=`.

# File lib/testable.rb, line 126
def logger
  @logger ||= Testable::Logger.new.create
end
new(browser = nil, region_element = nil, parent = nil, &block) click to toggle source

Initialization is used to establish a browser instance within the context of the framework. The logic here requires determining under what condition a browser instance may have been set.

# File lib/testable.rb, line 34
def initialize(browser = nil, region_element = nil, parent = nil, &block)
  @browser = Testable.browser unless Testable.browser.nil?
  @browser = browser if Testable.browser.nil?
  @region_element = region_element || Testable.browser
  @parent = parent
  definition_setup
  instance_eval(&block) if block
end
pluralize(method) click to toggle source

This method will allow a particular element name to be pluralized.

@example

Empirical.pluralize(:div) => divs
Empirical.pluralize(:checkbox) => checkboxes
# File lib/testable/element.rb, line 53
def self.pluralize(method)
  value = method.to_s

  # This bit is not what you would call optimized. Essentially, it just
  # tries to ppluralize with "s" and see if that method is included in the
  # Watir methods. If that fails, then an attempt to pluralize with "es" is
  # tried. If that fails, the assumption is made that a pluralized form of
  # the Watir method does not exist.
  if @elements.include?(:"#{value}s")
    :"#{value}s"
  elsif @elements.include?(:"#{value}es")
    :"#{value}es"
  else
    raise Testable::Errors::PluralizedElementError, "Unable to find plural form for #{value}!"
  end
end
quit_browser() click to toggle source

Generates a quit event on the browser instance. This is passed through to Watir which will ultimately delegate browser handling to Selenium and thus WebDriver.

# File lib/testable.rb, line 226
def quit_browser
  @browser.quit
end
selenium_api() click to toggle source

Returns information about the API that is specific to Selenium.

# File lib/testable.rb, line 204
def selenium_api
  browser.driver.methods - Object.public_methods
end
set_browser(app = :chrome, *args) click to toggle source

This sets the browser instance so that Testable is aware of what that instance is. This is how a test, using the Testable framework, will be able to know which browser to communicate with.

# File lib/testable.rb, line 216
def set_browser(app = :chrome, *args)
  @browser = Watir::Browser.new(app, *args)
  Testable.browser = @browser
end
Also aliased as: start_browser
start_browser(app = :chrome, *args)
Alias for: set_browser
watir_api() click to toggle source

Returns information about the API that Watir exposes. This does not include Selenium elements, which Watir is wrapping.

# File lib/testable.rb, line 198
def watir_api
  browser.methods - Object.public_methods -
    Watir::Container.instance_methods
end
wire_level_logging() click to toggle source

Report the current logging level.

# File lib/testable.rb, line 192
def wire_level_logging
  %i[DEBUG INFO WARN ERROR FATAL UNKNOWN][Watir.logger.level]
end
wire_level_logging=(value) click to toggle source

Level of logging.

# File lib/testable.rb, line 187
def wire_level_logging=(value)
  Watir.logger.level = value
end
wire_path=(logdev) click to toggle source

Path for the logger to use.

# File lib/testable.rb, line 182
def wire_path=(logdev)
  Watir.logger.reopen(logdev)
end

Public Instance Methods

definition_setup() click to toggle source

This method is used to setup any definitions provided as part of the executable of Testable. This generally means any page definitions that include Testable.

# File lib/testable.rb, line 46
def definition_setup
  begin_with if respond_to?(:begin_with)
  initialize_page if respond_to?(:initialize_page)
  initialize_region if respond_to?(:initialize_region)
  initialize_regions
end
dependencies() click to toggle source

Returns all of the dependencies that Testable relies on.

# File lib/testable/version.rb, line 25
def dependencies
  Gem.loaded_specs.values.map { |spec| "#{spec.name} #{spec.version}\n" }
     .uniq.sort.join(",").split(",")
end
elements() click to toggle source

Provides a list of all elements that Watir knows how to work with. This is generated from the Watir container itself so the list should always be up to date.

# File lib/testable/element.rb, line 24
def elements
  @elements ||= Watir::Container.instance_methods unless @elements
end
elements?() click to toggle source

This predicate method returns all of the elements that can be recognized by Watir.

# File lib/testable/element.rb, line 11
def elements?
  @elements
end
gem_version(name) click to toggle source

Returns a gem version for a given gem, assuming the gem has been loaded.

# File lib/testable/version.rb, line 18
def gem_version(name)
  Gem.loaded_specs[name].version
rescue NoMethodError
  puts "No gem loaded for #{name}."
end
initialize_regions() click to toggle source

This method is used to interate through any definitions that provide an “initialize_region” method. What happens here is essentially that new polymorphic modules are created based on classes. This is what allows a region to be part of a page definition, the latter of which is nothing more than a standard Ruby class.

# File lib/testable.rb, line 58
def initialize_regions
  @initialized_regions ||= []

  # The goal here is get all included and extended modules.
  modules = self.class.included_modules + (class << self; self end).included_modules
  modules.uniq!

  # Then each of those modules can be initialized.
  modules.each do |m|
    # First a check is made the that constructor is defined and that it has
    # not been called before.
    next if @initialized_regions.include?(m) || !m.instance_methods.include?(:initialize_region)

    m.instance_method(:initialize_region).bind(self).call

    @initialized_regions << m
  end
end
plural?(method) click to toggle source

This predicate method checks if a given element is a valid element that Watir knows how to interact with, but in plural form.

@example

Testable.recognizes?(:spans) # => true
Testable.recognizes?(:divs) # => true
Testable.recognizes?(:class) # => false
Testable.recognizes?(:classes) # => false
# File lib/testable/element.rb, line 36
def plural?(method)
  value = method.to_s
  plural = value.to_sym

  # Remove the trailing "s" or "es" to de-pluralize.
  single = value.sub(/e?s$/, '').to_sym

  !value.match(/s$/).nil? &&
    @elements.include?(plural) &&
    @elements.include?(single)
end
recognizes?(method) click to toggle source

This predicate method checks if a given element is in the list of known elements that Watir knows how to interact with.

# File lib/testable/element.rb, line 17
def recognizes?(method)
  @elements.include? method.to_sym
end
version() click to toggle source

Returns version information about Testable and its core dependencies.

# File lib/testable/version.rb, line 8
  def version
    """
Testable v#{Testable::VERSION}
watir: #{gem_version('watir')}
selenium-webdriver: #{gem_version('selenium-webdriver')}
    """
  end