howitzer 2.1.1 → 2.4.0

data/lib/howitzer/meta/actions.rb

@@ -0,0 +1,35 @@
+module Howitzer
+  module Meta
+    # Module with utility actions for elements
+    module Actions
+      # Highlights element with red border on the page
+      # @param args [Array] arguments for elements described with lambda locators
+      # @param options [Hash] original Capybara options. For details, see `Capybara::Node::Finders#all`
+      def highlight(*args, **options)
+        if xpath(*args, **options).blank?
+          Howitzer::Log.debug("Element #{name} not found on the page")
+          return
+        end
+        element = escape(xpath(*args, **options))
+        context.execute_script(
+          "document.evaluate('#{element}', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null)." \
+          'singleNodeValue.style.border = "thick solid red"'
+        )
+      end
+
+      # Returns xpath for the element
+      # @param args [Array] arguments for elements described with lambda locators
+      # @param options [Hash] original Capybara options. For details, see `Capybara::Node::Finders#all`
+      # @return [String, nil]
+      def xpath(*args, **options)
+        capybara_element(*args, **options).try(:path)
+      end
+
+      private
+
+      def escape(xpath)
+        xpath.gsub(/(['"])/, '\\\\\\1')
+      end
+    end
+  end
+end

data/lib/howitzer/meta/element.rb

@@ -0,0 +1,40 @@
+module Howitzer
+  module Meta
+    # This class represents element entity within howitzer meta information interface
+    class Element
+      attr_reader :name, :context
+
+      include Howitzer::Meta::Actions
+      # Creates new meta element with meta information and utility actions
+      # @param name [String] name of the element
+      # @param context [Howitzer::Web::Page] page element belongs to
+      def initialize(name, context)
+        @name = name
+        @context = context
+      end
+
+      # Finds all instances of element on the page and returns them as array of capybara elements
+      # @param args [Array] arguments for elements described with lambda locators
+      # @param options [Hash] original Capybara options. For details, see `Capybara::Node::Finders#all`
+      # @return [Array]
+      def capybara_elements(*args, **options)
+        if options.present?
+          context.send("#{name}_elements", *args, **options)
+        else
+          context.send("#{name}_elements", *args)
+        end
+      end
+
+      # Finds element on the page and returns as a capybara element
+      # @param args [Array] arguments for elements described with lambda locators
+      # @param options [Hash] original Capybara options. For details, see `Capybara::Node::Finders#all`
+      # @param wait [Integer] wait time for element search
+      # @return [Capybara::Node::Element, nil]
+      def capybara_element(*args, wait: 0, **options)
+        context.send("#{name}_element", *args, **options.merge(match: :first, wait: wait))
+      rescue Capybara::ElementNotFound
+        nil
+      end
+    end
+  end
+end

data/lib/howitzer/meta/entry.rb

@@ -0,0 +1,62 @@
+module Howitzer
+  module Meta
+    # This class provides access to meta information entities
+    class Entry
+      attr_reader :context
+
+      # Creates new meta entry instance for the page which provides access to elements, iframes and sections
+      # @param context [Howitzer::Web::Page] page for which entry is created
+      def initialize(context)
+        @context = context
+      end
+
+      # Returns array of elements
+      # @return [Array]
+      def elements
+        @elements ||= context
+                      .private_methods
+                      .grep(/\A(?!wait_)\w+_element\z/)
+                      .map { |el| Meta::Element.new(el.to_s.gsub('_element', ''), context) }
+      end
+
+      # Finds element by name
+      # @param name [String, Symbol] element name
+      # @return [Meta::Element]
+      def element(name)
+        elements.find { |el| el.name == name.to_s }
+      end
+
+      # Returns array of sections
+      # @return [Array]
+      def sections
+        @sections ||= context
+                      .public_methods
+                      .grep(/\A(?!wait_)\w+_section$\z/)
+                      .map { |el| Meta::Section.new(el.to_s.gsub('_section', ''), context) }
+      end
+
+      # Finds section by name
+      # @param name [String, Symbol] section name
+      # @return [Meta::Section]
+      def section(name)
+        sections.find { |el| el.name == name.to_s }
+      end
+
+      # Returns array of iframes
+      # @return [Array]
+      def iframes
+        @iframes ||= context
+                     .public_methods
+                     .grep(/\A(?!wait_)\w+_iframe$\z/)
+                     .map { |el| Meta::Iframe.new(el.to_s.gsub('_iframe', ''), context) }
+      end
+
+      # Finds iframe by name
+      # @param name [String, Symbol] iframe name
+      # @return [Meta::Iframe]
+      def iframe(name)
+        iframes.find { |el| el.name == name.to_s }
+      end
+    end
+  end
+end

data/lib/howitzer/meta/iframe.rb

@@ -0,0 +1,41 @@
+module Howitzer
+  module Meta
+    # This class represents iframe entity within howitzer meta information interface
+    class Iframe
+      attr_reader :name, :context
+
+      include Howitzer::Meta::Actions
+
+      # Creates new meta iframe element with meta information and utility actions
+      # @param name [String] name of the iframe
+      # @param context [Howitzer::Web::Page] page which has this iframe
+      def initialize(name, context)
+        @name = name
+        @context = context
+      end
+
+      # Finds all instances of iframe on the page and returns them as array of capybara elements
+      # @return [Array]
+      def capybara_elements
+        context.capybara_context.all("iframe[src='#{site_value}']")
+      end
+
+      # Finds iframe on the page and returns as a capybara element
+      # @param wait [Integer] wait time for element search
+      # @return [Capybara::Node::Element, nil]
+      def capybara_element(wait: 0)
+        context.capybara_context.find("iframe[src='#{site_value}']", match: :first, wait: wait)
+      rescue Capybara::ElementNotFound
+        nil
+      end
+
+      # Returns url value for iframe
+      # @return [String]
+      def site_value
+        return @site_value if @site_value.present?
+
+        context.send("#{name}_iframe") { |frame| @site_value = frame.class.send(:site_value) }
+      end
+    end
+  end
+end

data/lib/howitzer/meta/section.rb

@@ -0,0 +1,30 @@
+module Howitzer
+  module Meta
+    # This class represents section entity within howitzer meta information interface
+    class Section
+      attr_reader :name, :context
+
+      include Howitzer::Meta::Actions
+      # Creates meta section element with meta information and utility actions
+      # @param name [String] name of the section
+      # @param context [Howitzer::Web::Page] page which has this section
+      def initialize(name, context)
+        @name = name
+        @context = context
+      end
+
+      # Finds all instances of section on the page and returns them as array of capybara elements
+      # @return [Array]
+      def capybara_elements
+        context.send("#{name}_sections").map(&:capybara_context)
+      end
+
+      # Finds section on the page and returns as a capybara element
+      # @return [Capybara::Node::Element, nil]
+      def capybara_element
+        section = context.send("#{name}_sections").first
+        section.try(:capybara_context)
+      end
+    end
+  end
+end

data/lib/howitzer/meta.rb

@@ -0,0 +1,11 @@
+module Howitzer
+  # This module holds meta-information about elements on the page
+  module Meta
+  end
+end
+
+require 'howitzer/meta/actions'
+require 'howitzer/meta/element'
+require 'howitzer/meta/section'
+require 'howitzer/meta/iframe'
+require 'howitzer/meta/entry'

data/lib/howitzer/utils/string_extensions.rb

@@ -7,8 +7,12 @@ module Howitzer
       #   'home'.open #=> HomePage.open
       # @see Howitzer::Web::Page.open
 
-      def open(*args)
-        as_page_class.open(*args)
+      def open(*args, **options)
+        if options.present?
+          as_page_class.open(*args, **options)
+        else
+          as_page_class.open(*args)
+        end
       end
 
       # Returns an instantiated page by name

data/lib/howitzer/version.rb

@@ -1,4 +1,4 @@
 # This module holds howitzer version
 module Howitzer
-  VERSION = '2.1.1'.freeze #:nodoc:
+  VERSION = '2.4.0'.freeze # :nodoc:
 end

data/lib/howitzer/web/base_section.rb

@@ -15,7 +15,7 @@ module Howitzer
       attr_reader :parent
 
       class << self
-        attr_reader :default_finder_args
+        attr_reader :default_finder_args, :default_finder_options
       end
 
       def initialize(parent, context)

data/lib/howitzer/web/capybara_context_holder.rb

@@ -12,6 +12,7 @@ module Howitzer
 
       def capybara_scopes
         return super if defined?(super)
+
         raise NotImplementedError, "Please define 'capybara_scopes' method for class holder"
       end
     end

data/lib/howitzer/web/capybara_methods_proxy.rb

@@ -3,19 +3,21 @@ require 'active_support'
 require 'active_support/core_ext'
 
 # Remove this monkey patch after fixing the bugs in selenium-webdriver / capybara
-#:nocov:
+# :nocov:
 class Capybara::Selenium::Driver # rubocop:disable Style/ClassAndModuleChildren
   #
   # https://github.com/teamcapybara/capybara/issues/1845
   def title
     return browser.title unless within_frame?
+
     find_xpath('/html/head/title').map { |n| n[:text] }.first.to_s
   end
 
-  # Known issue, works differently for phantomjs and real browsers
+  # Known issue, works differently for real browsers
   # https://github.com/seleniumhq/selenium/issues/1727
   def current_url
     return browser.current_url unless within_frame?
+
     execute_script('return document.location.href')
   end
 
@@ -25,13 +27,13 @@ class Capybara::Selenium::Driver # rubocop:disable Style/ClassAndModuleChildren
     !(@frame_handles.blank? || @frame_handles[browser.window_handle].blank?)
   end
 end
-#:nocov:
+# :nocov:
 
 module Howitzer
   module Web
     # This module proxies required original capybara methods to recipient
     module CapybaraMethodsProxy
-      PROXIED_CAPYBARA_METHODS = Capybara::Session::SESSION_METHODS + #:nodoc:
+      PROXIED_CAPYBARA_METHODS = Capybara::Session::SESSION_METHODS + # :nodoc:
                                  Capybara::Session::MODAL_METHODS +
                                  %i[driver text]
 
@@ -39,7 +41,13 @@ module Howitzer
       # Instead of including Capybara::DSL module, we proxy most interesting Capybara methods and
       # prevent using extra methods which can potentially broke main principles and framework concept
       PROXIED_CAPYBARA_METHODS.each do |method|
-        define_method(method) { |*args, &block| Capybara.current_session.send(method, *args, &block) }
+        define_method(method) do |*args, **options, &block|
+          if options.present?
+            Capybara.current_session.send(method, *args, **options, &block)
+          else
+            Capybara.current_session.send(method, *args, &block)
+          end
+        end
       end
 
       # Accepts or declines JS alert box by given flag
@@ -57,7 +65,8 @@ module Howitzer
       private
 
       def capybara_scopes
-        @_scopes ||= [Capybara.current_session]
+        @capybara_scopes ||= Hash.new { |hash, key| hash[key] = [Capybara.current_session] }
+        @capybara_scopes[Howitzer.session_name]
       end
     end
   end

data/lib/howitzer/web/element_dsl.rb

@@ -3,39 +3,68 @@ module Howitzer
   module Web
     # This module combines element dsl methods
     module ElementDsl
+      # This module holds element helper methods
+      module Helpers
+        private
+
+        def lambda_args(*args, **keyword_args)
+          {
+            lambda_args: {
+              args: args,
+              keyword_args: keyword_args
+            }
+          }
+        end
+      end
+
       include CapybaraContextHolder
+      include Helpers
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend(ClassMethods)
       end
 
-      private
+      def convert_arguments(args, options, block_args, block_options)
+        conv_args = args.map { |el| el.is_a?(Proc) ? proc_to_selector(el, block_args, block_options) : el }
+        args_options = pop_options_from_array(conv_args)
+        block_args_options = pop_options_from_array(block_args)
+        conv_options = [args_options, options, block_args_options, block_options].map do |el|
+          el.transform_keys(&:to_sym)
+        end.reduce(&:merge).except(:lambda_args)
+        [conv_args, conv_options]
+      end
 
-      def convert_arguments(args, params)
-        args, params, options = merge_element_options(args, params)
-        args = args.map do |el|
-          next(el) unless el.is_a?(Proc)
-          el.call(*params.shift(el.arity))
+      def proc_to_selector(proc, block_args, block_options)
+        lambda_args = extract_lambda_args(block_args, block_options)
+        if lambda_args
+          if lambda_args[:keyword_args].present?
+            proc.call(*lambda_args[:args], **lambda_args[:keyword_args])
+          else
+            proc.call(*lambda_args[:args])
+          end
+        else
+          puts "WARNING! Passing lambda arguments with element options is deprecated.\n" \
+               "Please use 'lambda_args' method, for example: foo_element(lambda_args(title: 'Example'), wait: 10)"
+          proc.call(*block_args.shift(proc.arity))
         end
-        args << options unless options.blank?
-        args
       end
 
-      def merge_element_options(args, params)
-        new_args, args_hash = extract_element_options(args)
-        new_params, params_hash = extract_element_options(params)
-        [new_args, new_params, args_hash.merge(params_hash)]
+      def extract_lambda_args(block_args, block_options)
+        (block_args.first.is_a?(Hash) && block_args.first[:lambda_args]) || block_options[:lambda_args]
       end
 
-      def extract_element_options(args)
-        new_args = args.deep_dup
-        args_hash = {}
-        args_hash = new_args.pop if new_args.last.is_a?(Hash)
-        [new_args, args_hash]
+      def pop_options_from_array(value)
+        if value.last.is_a?(Hash) && !value.last.key?(:lambda_args)
+          value.pop
+        else
+          {}
+        end
       end
 
-      # This module holds element dsl methods methods
+      # This module holds element dsl methods
       module ClassMethods
+        include Helpers
+
         protected
 
         # Creates a group of methods to interact with described HTML element(s) on page
@@ -56,6 +85,7 @@ module Howitzer
         #   <b>has_no_<em>element_name</em>_element?</b> - equals capybara #has_no_selector(...) method
         # @param name [Symbol, String] an unique element name
         # @param args [Array] original Capybara arguments. For details, see `Capybara::Node::Finders#all`.
+        # @param options [Hash] original Capybara options. For details, see `Capybara::Node::Finders#all`.
         # @example Using in a page class
         #   class HomePage < Howitzer::Web::Page
         #     element :top_panel, '.top'
@@ -92,14 +122,14 @@ module Howitzer
         # @raise [BadElementParamsError] if wrong element arguments
         # @!visibility public
 
-        def element(name, *args)
+        def element(name, *args, **options)
           validate_arguments!(args)
-          define_element(name, args)
-          define_elements(name, args)
-          define_wait_for_element(name, args)
-          define_within_element(name, args)
-          define_has_element(name, args)
-          define_has_no_element(name, args)
+          define_element(name, args, options)
+          define_elements(name, args, options)
+          define_wait_for_element(name, args, options)
+          define_within_element(name, args, options)
+          define_has_element(name, args, options)
+          define_has_no_element(name, args, options)
         end
 
         private
@@ -110,31 +140,51 @@ module Howitzer
           raise Howitzer::BadElementParamsError, 'Using more than 1 proc in arguments is forbidden'
         end
 
-        def define_element(name, args)
-          define_method("#{name}_element") do |*block_args|
-            capybara_context.find(*convert_arguments(args, block_args))
+        def define_element(name, args, options)
+          define_method("#{name}_element") do |*block_args, **block_options|
+            conv_args, conv_options = convert_arguments(args, options, block_args, block_options)
+            if conv_options.present?
+              capybara_context.find(*conv_args, **conv_options)
+            else
+              capybara_context.find(*conv_args)
+            end
           end
           private "#{name}_element"
         end
 
-        def define_elements(name, args)
-          define_method("#{name}_elements") do |*block_args|
-            capybara_context.all(*convert_arguments(args, block_args))
+        def define_elements(name, args, options)
+          define_method("#{name}_elements") do |*block_args, **block_options|
+            conv_args, conv_options = convert_arguments(args, options, block_args, block_options)
+            if conv_options.present?
+              capybara_context.all(*conv_args, **conv_options)
+            else
+              capybara_context.all(*conv_args)
+            end
           end
           private "#{name}_elements"
         end
 
-        def define_wait_for_element(name, args)
-          define_method("wait_for_#{name}_element") do |*block_args|
-            capybara_context.find(*convert_arguments(args, block_args))
+        def define_wait_for_element(name, args, options)
+          define_method("wait_for_#{name}_element") do |*block_args, **block_options|
+            conv_args, conv_options = convert_arguments(args, options, block_args, block_options)
+            if conv_options.present?
+              capybara_context.find(*conv_args, **conv_options)
+            else
+              capybara_context.find(*conv_args)
+            end
             return nil
           end
           private "wait_for_#{name}_element"
         end
 
-        def define_within_element(name, args)
-          define_method("within_#{name}_element") do |*block_args, &block|
-            new_scope = capybara_context.find(*convert_arguments(args, block_args))
+        def define_within_element(name, args, options)
+          define_method("within_#{name}_element") do |*block_args, **block_options, &block|
+            conv_args, conv_options = convert_arguments(args, options, block_args, block_options)
+            new_scope = if conv_options.present?
+                          capybara_context.find(*conv_args, **conv_options)
+                        else
+                          capybara_context.find(*conv_args)
+                        end
             begin
               capybara_scopes.push(new_scope)
               block.call
@@ -144,15 +194,25 @@ module Howitzer
           end
         end
 
-        def define_has_element(name, args)
-          define_method("has_#{name}_element?") do |*block_args|
-            capybara_context.has_selector?(*convert_arguments(args, block_args))
+        def define_has_element(name, args, options)
+          define_method("has_#{name}_element?") do |*block_args, **block_options|
+            conv_args, conv_options = convert_arguments(args, options, block_args, block_options)
+            if conv_options.present?
+              capybara_context.has_selector?(*conv_args, **conv_options)
+            else
+              capybara_context.has_selector?(*conv_args)
+            end
           end
         end
 
-        def define_has_no_element(name, args)
-          define_method("has_no_#{name}_element?") do |*block_args|
-            capybara_context.has_no_selector?(*convert_arguments(args, block_args))
+        def define_has_no_element(name, args, options)
+          define_method("has_no_#{name}_element?") do |*block_args, **block_options|
+            conv_args, conv_options = convert_arguments(args, options, block_args, block_options)
+            if conv_options.present?
+              capybara_context.has_no_selector?(*conv_args, **conv_options)
+            else
+              capybara_context.has_no_selector?(*conv_args)
+            end
           end
         end
       end

data/lib/howitzer/web/iframe_dsl.rb

@@ -5,7 +5,7 @@ module Howitzer
     module IframeDsl
       include CapybaraContextHolder
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend(ClassMethods)
       end
 
@@ -26,7 +26,7 @@ module Howitzer
 
       def convert_iframe_arguments(args, params)
         new_args = args.deep_dup
-        hash = new_args.pop.merge(params) if new_args.last.is_a?(Hash)
+        hash = new_args.pop.transform_keys(&:to_sym).merge(params.transform_keys(&:to_sym)) if new_args.last.is_a?(Hash)
         new_args << hash if hash.present?
         new_args
       end
@@ -84,8 +84,10 @@ module Howitzer
 
         def iframe(name, *args)
           raise ArgumentError, 'iframe selector arguments must be specified' if args.blank?
+
           klass = args.first.is_a?(Class) ? args.shift : find_matching_class(name)
           raise NameError, "class can not be found for #{name} iframe" if klass.blank?
+
           define_iframe(klass, name, args)
           define_has_iframe(name, args)
           define_has_no_iframe(name, args)

data/lib/howitzer/web/page.rb

@@ -1,6 +1,7 @@
 require 'singleton'
 require 'rspec/expectations'
 require 'addressable/template'
+require 'howitzer/meta'
 require 'howitzer/web/capybara_methods_proxy'
 require 'howitzer/web/page_validator'
 require 'howitzer/web/element_dsl'
@@ -13,7 +14,7 @@ module Howitzer
   module Web
     # This class represents a single web page. This is a parent class for all web pages
     class Page
-      UnknownPage = Class.new #:nodoc:
+      UnknownPage = Class.new # :nodoc:
       include Singleton
       include CapybaraMethodsProxy
       include ElementDsl
@@ -27,6 +28,7 @@ module Howitzer
       # This Ruby callback makes all inherited classes as singleton classes.
 
       def self.inherited(subclass)
+        super
         subclass.class_eval { include Singleton }
       end
 
@@ -39,7 +41,6 @@ module Howitzer
 
       def self.open(validate: true, url_processor: nil, **params)
         url = expanded_url(params, url_processor)
-        modify_user_agent if Howitzer.user_agent.present?
         Howitzer::Log.info "Open #{name} page by '#{url}' url"
         retryable(tries: 2, logger: Howitzer::Log, trace: true, on: Exception) do |retries|
           Howitzer::Log.info 'Retry...' unless retries.zero?
@@ -65,6 +66,7 @@ module Howitzer
         page_list = matched_pages
         return UnknownPage if page_list.count.zero?
         return page_list.first if page_list.count == 1
+
         raise Howitzer::AmbiguousPageMatchingError, ambiguous_page_msg(page_list)
       end
 
@@ -77,6 +79,7 @@ module Howitzer
         end_time = ::Time.now + timeout
         until ::Time.now > end_time
           return true if opened?
+
           sleep(0.5)
         end
         raise Howitzer::IncorrectPageError, incorrect_page_msg
@@ -98,9 +101,16 @@ module Howitzer
         if defined?(path_value)
           return "#{site_value}#{Addressable::Template.new(path_value).expand(params, url_processor)}"
         end
+
         raise Howitzer::NoPathForPageError, "Please specify path for '#{self}' page. Example: path '/home'"
       end
 
+      # Provides access to meta information about entities on the page
+      # @return [Meta::Entry]
+      def meta
+        @meta ||= Meta::Entry.new(self)
+      end
+
       class << self
         protected
 
@@ -141,22 +151,12 @@ module Howitzer
 
         def incorrect_page_msg
           "Current page: #{current_page}, expected: #{self}.\n" \
-                    "\tCurrent url: #{current_url}\n\tCurrent title: #{instance.title}"
+            "\tCurrent url: #{current_url}\n\tCurrent title: #{instance.title}"
         end
 
         def ambiguous_page_msg(page_list)
           "Current page matches more that one page class (#{page_list.join(', ')}).\n" \
-                    "\tCurrent url: #{current_url}\n\tCurrent title: #{instance.title}"
-        end
-
-        def modify_user_agent
-          driver = Capybara.current_session.driver
-          case Howitzer.driver.to_sym
-            when CapybaraHelpers::POLTERGEIST
-              driver.add_headers('User-Agent' => Howitzer.user_agent)
-            when CapybaraHelpers::WEBKIT
-              driver.header('User-Agent', Howitzer.user_agent)
-          end
+            "\tCurrent url: #{current_url}\n\tCurrent title: #{instance.title}"
         end
       end