module SitePrism::DSL::ClassMethods

SitePrism::DSL::ClassMethods This exposes all of the DSL definitions users will use when generating their POM classes.

Many of these methods will be used in-line to allow users to generate a multitude of methods and locators for finding elements / sections on a page or section of a page

Attributes

expected_items[R]

Public Instance Methods

element(name, *find_args) click to toggle source

Creates an instance of a SitePrism Element - This will create several methods designed to Locate the element -> @return [Capybara::Node::Element] Check the elements presence or non-presence -> @return [Boolean] Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error] Validate certain properties about the element

# File lib/site_prism/dsl.rb, line 120
def element(name, *find_args)
  SitePrism::Deprecator.deprecate('Passing a block to :element') if block_given?
  build(:element, name, *find_args) do
    define_method(name) do |*runtime_args, &element_block|
      warn_if_dsl_collision(self, name)
      raise_if_block(self, name, !element_block.nil?, :element)
      _find(*merge_args(find_args, runtime_args))
    end
  end
end
elements(name, *find_args) click to toggle source

Creates a enumerable instance of a SitePrism Element - This will create several methods designed to Locate the enumerable element -> @return [Capybara::Result] Check the elements presence or non-presence -> @return [Boolean] Wait for the elements to be present or not -> @return [TrueClass, SitePrism::Error] Validate certain properties about the elements

# File lib/site_prism/dsl.rb, line 136
def elements(name, *find_args)
  SitePrism::Deprecator.deprecate('Passing a block to :elements') if block_given?
  build(:elements, name, *find_args) do
    define_method(name) do |*runtime_args, &element_block|
      warn_if_dsl_collision(self, name)
      raise_if_block(self, name, !element_block.nil?, :elements)
      _all(*merge_args(find_args, runtime_args))
    end
  end
end
expected_elements(*elements) click to toggle source

Sets the `expected_items` iVar on a class. This property is used in conjunction with `all_there?` to provide a way of granularising the check made to only interrogate a sub-set of DSL defined items

# File lib/site_prism/dsl.rb, line 150
def expected_elements(*elements)
  @expected_items = elements
end
iframe(name, klass, *args) click to toggle source
# File lib/site_prism/dsl.rb, line 187
def iframe(name, klass, *args)
  SitePrism.logger.debug('Block passed into iFrame construct at build time') if block_given?
  element_find_args = deduce_iframe_element_find_args(args)
  scope_find_args = deduce_iframe_scope_find_args(args)
  build(:iframe, name, *element_find_args) do
    define_method(name) do |&block|
      raise MissingBlockError unless block

      within_frame(*scope_find_args) { block.call(klass.new) }
    end
  end
end
mapped_items(legacy: true) click to toggle source

Return a list of all mapped items on a SitePrism class instance (Page or Section) If legacy is set to true (Default) -> @return [Array] If legacy is set to false (New behaviour) -> @return [Hash]

# File lib/site_prism/dsl.rb, line 203
def mapped_items(legacy: true)
  return old_mapped_items if legacy

  new_mapped_items
end
section(name, *args, &block) click to toggle source

Creates an instance of a SitePrism Section - This will create several methods designed to Locate the section -> @return [SitePrism::Section] Check the section presence or non-presence -> @return [Boolean] Wait for the section to be present or not -> @return [TrueClass, SitePrism::Error] Validate certain properties about the section

# File lib/site_prism/dsl.rb, line 159
def section(name, *args, &block)
  section_class, find_args = extract_section_options(args, &block)
  build(:section, name, *find_args) do
    define_method(name) do |*runtime_args, &runtime_block|
      warn_if_dsl_collision(self, name)
      section_element = _find(*merge_args(find_args, runtime_args))
      section_class.new(self, section_element, &runtime_block)
    end
  end
end
sections(name, *args, &block) click to toggle source

Creates an enumerable instance of a SitePrism Section - This will create several methods designed to Locate the sections -> @return [Array] Check the sections presence or non-presence -> @return [Boolean] Wait for the sections to be present or not -> @return [TrueClass, SitePrism::Error] Validate certain properties about the section

# File lib/site_prism/dsl.rb, line 175
def sections(name, *args, &block)
  section_class, find_args = extract_section_options(args, &block)
  build(:sections, name, *find_args) do
    define_method(name) do |*runtime_args, &element_block|
      raise_if_block(self, name, !element_block.nil?, :sections)
      _all(*merge_args(find_args, runtime_args)).map do |element|
        section_class.new(self, element)
      end
    end
  end
end

Private Instance Methods

add_helper_methods(name, *find_args) click to toggle source
# File lib/site_prism/dsl.rb, line 239
def add_helper_methods(name, *find_args)
  create_existence_checker(name, *find_args)
  create_nonexistence_checker(name, *find_args)
  SitePrism::RspecMatchers.new(name)._create_rspec_existence_matchers if defined?(RSpec)
  create_visibility_waiter(name, *find_args)
  create_invisibility_waiter(name, *find_args)
end
build(type, name, *find_args) { || ... } click to toggle source
# File lib/site_prism/dsl.rb, line 224
def build(type, name, *find_args)
  if find_args.empty?
    create_error_method(name)
  else
    map_item(type, name)
    yield
  end
  add_helper_methods(name, *find_args)
end
create_error_method(name) click to toggle source
# File lib/site_prism/dsl.rb, line 297
def create_error_method(name)
  SitePrism.logger.error("#{name} has come from an item with no locators.")
  SitePrism::Deprecator.soft_deprecate(
    'DSL definition with no find_args',
    'All DSL elements should have find_args'
  )
  define_method(name) { raise SitePrism::InvalidElementError }
end
create_existence_checker(element_name, *find_args) click to toggle source
# File lib/site_prism/dsl.rb, line 253
def create_existence_checker(element_name, *find_args)
  method_name = "has_#{element_name}?"
  create_helper_method(method_name, *find_args) do
    define_method(method_name) do |*runtime_args|
      args = merge_args(find_args, runtime_args)
      element_exists?(*args)
    end
  end
end
create_helper_method(proposed_method_name, *find_args) { || ... } click to toggle source
# File lib/site_prism/dsl.rb, line 247
def create_helper_method(proposed_method_name, *find_args)
  return create_error_method(proposed_method_name) if find_args.empty?

  yield
end
create_invisibility_waiter(element_name, *find_args) click to toggle source
# File lib/site_prism/dsl.rb, line 285
def create_invisibility_waiter(element_name, *find_args)
  method_name = "wait_until_#{element_name}_invisible"
  create_helper_method(method_name, *find_args) do
    define_method(method_name) do |*runtime_args|
      args = merge_args(find_args, runtime_args, visible: true)
      return true if element_does_not_exist?(*args)

      raise SitePrism::ElementInvisibilityTimeoutError
    end
  end
end
create_nonexistence_checker(element_name, *find_args) click to toggle source
# File lib/site_prism/dsl.rb, line 263
def create_nonexistence_checker(element_name, *find_args)
  method_name = "has_no_#{element_name}?"
  create_helper_method(method_name, *find_args) do
    define_method(method_name) do |*runtime_args|
      args = merge_args(find_args, runtime_args)
      element_does_not_exist?(*args)
    end
  end
end
create_visibility_waiter(element_name, *find_args) click to toggle source
# File lib/site_prism/dsl.rb, line 273
def create_visibility_waiter(element_name, *find_args)
  method_name = "wait_until_#{element_name}_visible"
  create_helper_method(method_name, *find_args) do
    define_method(method_name) do |*runtime_args|
      args = merge_args(find_args, runtime_args, visible: true)
      return true if element_exists?(*args)

      raise SitePrism::ElementVisibilityTimeoutError
    end
  end
end
deduce_iframe_element_find_args(args) click to toggle source
# File lib/site_prism/dsl.rb, line 315
def deduce_iframe_element_find_args(args)
  warn_on_invalid_selector_input(args)
  case args[0]
  when Integer then "iframe:nth-of-type(#{args[0] + 1})"
  when String  then [:css, args[0]]
  else args
  end
end
deduce_iframe_scope_find_args(args) click to toggle source
# File lib/site_prism/dsl.rb, line 306
def deduce_iframe_scope_find_args(args)
  warn_on_invalid_selector_input(args)
  case args[0]
  when Integer then [args[0]]
  when String  then [:css, args[0]]
  else args
  end
end
deduce_search_arguments(section_class, args) click to toggle source
# File lib/site_prism/dsl.rb, line 354
def deduce_search_arguments(section_class, args)
  extract_search_arguments(args) ||
    extract_search_arguments(section_class.default_search_arguments) ||
    invalidate_search_arguments!
end
deduce_section_class(base_class, &block) click to toggle source
# File lib/site_prism/dsl.rb, line 346
def deduce_section_class(base_class, &block)
  klass = base_class
  klass = Class.new(klass || SitePrism::Section, &block) if block
  return klass if klass

  raise ArgumentError, 'You should provide descendant of SitePrism::Section class or/and a block as the second argument.'
end
extract_search_arguments(args) click to toggle source
# File lib/site_prism/dsl.rb, line 360
def extract_search_arguments(args)
  args if args && !args.empty?
end
extract_section_options(args, &block) click to toggle source
# File lib/site_prism/dsl.rb, line 335
def extract_section_options(args, &block)
  if args.first.is_a?(Class)
    klass = args.shift
    section_class = klass if klass <= SitePrism::Section
  end

  section_class = deduce_section_class(section_class, &block)
  arguments = deduce_search_arguments(section_class, args)
  [section_class, arguments]
end
invalidate_search_arguments!() click to toggle source
# File lib/site_prism/dsl.rb, line 364
def invalidate_search_arguments!
  SitePrism.logger.error('Could not deduce search_arguments')
  raise(ArgumentError, 'search arguments are needed in `section` definition or alternatively use `set_default_search_arguments`')
end
looks_like_xpath?(arg) click to toggle source
# File lib/site_prism/dsl.rb, line 331
def looks_like_xpath?(arg)
  arg.is_a?(String) && arg.start_with?('/', './')
end
map_item(type, name) click to toggle source
# File lib/site_prism/dsl.rb, line 234
def map_item(type, name)
  old_mapped_items << { type => name }
  new_mapped_items[type] << name.to_sym
end
new_mapped_items() click to toggle source
# File lib/site_prism/dsl.rb, line 220
def new_mapped_items
  @new_mapped_items ||= { element: [], elements: [], section: [], sections: [], iframe: [] }
end
old_mapped_items() click to toggle source
# File lib/site_prism/dsl.rb, line 211
def old_mapped_items
  SitePrism::Deprecator.soft_deprecate(
    '.mapped_items on a class',
    'To allow easier recursion through the items in conjunction with #all_there?',
    '.mapped_items(legacy: false)'
  )
  @old_mapped_items ||= []
end
warn_on_invalid_selector_input(args) click to toggle source
# File lib/site_prism/dsl.rb, line 324
def warn_on_invalid_selector_input(args)
  return unless looks_like_xpath?(args[0])

  SitePrism.logger.warn('The arguments passed in look like xpath. Check your locators.')
  SitePrism.logger.debug("Default locator strategy: #{Capybara.default_selector}")
end