howitzer 2.0.3 → 2.3.0

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
@@ -45,6 +45,7 @@ module Howitzer
         #   <b>has_no_<em>frame_name</em>_iframe?</b> - equals capybara #has_no_selector(...) method
         # @param name [Symbol, String] an unique iframe name
         # @param args [Array] original Capybara arguments. For details, see `Capybara::Session#within_frame`.
+        # @raise [NameError] if page class can not be found
         # @example Using in a page class
         #   class FbPage < Howitzer::Web::Page
         #     element :like, :xpath, ".//*[text()='Like']"
@@ -57,8 +58,19 @@ module Howitzer
         #     end
         #   end
         #
+        #   module Utils
+        #     class GroupFbPage < Howitzer::Web::Page
+        #     end
+        #   end
+        #
         #   class HomePage < Howitzer::Web::Page
         #     iframe :fb, 1
+        #
+        #    # frame with explicit class declaration
+        #    # iframe :fb, FbPage, 1
+        #
+        #    # frame with namespace
+        #     iframe :utils_group_fb
         #   end
         #
         #   HomePage.on do
@@ -72,7 +84,10 @@ module Howitzer
 
         def iframe(name, *args)
           raise ArgumentError, 'iframe selector arguments must be specified' if args.blank?
-          klass = "#{name}_page".classify.constantize
+
+          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)
@@ -100,6 +115,11 @@ module Howitzer
             capybara_context.has_no_selector?(*iframe_element_selector(args, params))
           end
         end
+
+        def find_matching_class(name)
+          Howitzer::Web::Page.descendants.select { |el| el.name.underscore.tr('/', '_') == "#{name}_page" }
+                             .max_by { |el| el.name.count('::') }
+        end
       end
     end
   end

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
 
@@ -64,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
 
@@ -76,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
@@ -97,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
 
@@ -140,12 +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}"
+            "\tCurrent url: #{current_url}\n\tCurrent title: #{instance.title}"
         end
       end
 
@@ -153,7 +164,8 @@ module Howitzer
 
       def initialize
         check_validations_are_defined!
-        current_window.maximize if Howitzer.maximized_window && Howitzer.driver != 'headless_chrome'
+        current_window.maximize if Howitzer.maximized_window &&
+                                   !%w[chrome headless_chrome].include?(Capybara.current_driver)
       end
 
       # Reloads current page in a browser

data/lib/howitzer/web/page_dsl.rb

@@ -18,7 +18,7 @@ module Howitzer
         #  HomePage.on { expect(HomePage.given).to have_menu_section } # Bad
         #  HomePage.on { is_expected.to have_menu_section } # Good
 
-        def is_expected # rubocop:disable Style/PredicateName
+        def is_expected # rubocop:disable Naming/PredicateName
           expect(page_klass.given)
         end
 
@@ -29,10 +29,15 @@ module Howitzer
         #   * `out` method extracts an instance variable from an original context if starts from @.
         #    Otherwise it executes a method from an original context
 
-        def method_missing(name, *args, &block)
+        def method_missing(name, *args, **options, &block)
           return super if name =~ /\A(?:be|have)_/
-          return eval_in_out_context(*args, &block) if name == :out
-          page_klass.given.send(name, *args, &block)
+          return eval_in_out_context(*args, **options, &block) if name == :out
+
+          if options.present?
+            page_klass.given.send(name, *args, **options, &block)
+          else
+            page_klass.given.send(name, *args, &block)
+          end
         end
 
         # Makes proxied methods to be evaludated and returned as a proc
@@ -44,11 +49,17 @@ module Howitzer
 
         private
 
-        def eval_in_out_context(*args, &block)
+        def eval_in_out_context(*args, **options, &block)
           return nil if args.size.zero?
+
           name = args.shift
           return get_outer_instance_variable(name) if name.to_s.start_with?('@')
-          outer_context.send(name, *args, &block)
+
+          if options.present?
+            outer_context.send(name, *args, **options, &block)
+          else
+            outer_context.send(name, *args, &block)
+          end
         end
 
         def get_outer_instance_variable(name)
@@ -58,9 +69,10 @@ module Howitzer
         attr_accessor :page_klass, :outer_context
       end
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend(ClassMethods)
       end
+
       # This module holds page dsl class methods
       module ClassMethods
         # Allows to execute page methods in context of the page.

data/lib/howitzer/web/page_validator.rb

@@ -6,7 +6,7 @@ module Howitzer
     module PageValidator
       @validations = {}
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend(ClassMethods)
       end
 
@@ -21,17 +21,19 @@ module Howitzer
 
       def check_validations_are_defined!
         return if self.class.validations.present?
+
         raise Howitzer::NoValidationError, "No any page validation was found for '#{self.class.name}' page"
       end
 
       # This module holds page validation class methods
       module ClassMethods
         # Adds validation to validation list for current page
-        # @param name [Symbol, String] a validation type. Possible values [:url, :element_presence, :title]
-        # @param value [Symbol, String, Regexp]
+        # @param type [Symbol, String] a validation type. Possible values [:url, :element_presence, :title]
+        # @param pattern_or_element_name [Symbol, String, Regexp]
         #   For :url and :title validation types must be <b>Regexp</b>
-        #   For :element_presence must be one of element names described for page
-        # @param additional_value [Object, nil] any value required to pass for a labmda selector
+        #   For :element_presence must be one of element names described for the page
+        # @param args [Array] any arguments required to pass for a lambda selector (:element_presence type only)
+        # @param options [Hash] keyword arguments required to pass for a lambda selector (:element_presence type only)
         # @raise  [Howitzer::UnknownValidationError] if unknown validation type
         # @raise  [Howitzer::UndefinedElementError] if :element_presence validations refers to undefined element name
         # @example
@@ -44,12 +46,23 @@ module Howitzer
         #   end
         # @example
         #   class HomePage < Howitzer::Web::Page
-        #     validate :element_presence, :menu_item, 'Logout'
-        #     element :menu_item, :xpath, ->(name) { ".//a[.='#{name}']" }
+        #     validate :element_presence, :menu_item, lambda_args(text: 'Logout')
+        #     element :menu_item, :xpath, ->(text:) { ".//a[.='#{text}']" }
         #   end
 
-        def validate(name, value, additional_value = nil)
-          validate_by_type(name, value, additional_value)
+        def validate(type, pattern_or_element_name, *args, **options)
+          case type.to_s.to_sym
+          when :url, :title
+            if args.present? || options.present?
+              raise ArgumentError, "Additional arguments and options are not supported by '#{type}' the validator"
+            end
+
+            send("validate_by_#{type}", pattern_or_element_name)
+          when :element_presence
+            validate_by_element_presence(pattern_or_element_name, *args, **options)
+          else
+            raise Howitzer::UnknownValidationError, "unknown '#{type}' validation type"
+          end
         end
 
         # Check whether current page is opened or no
@@ -60,6 +73,7 @@ module Howitzer
 
         def opened?(sync: true)
           return validations.all? { |(_, validation)| validation.call(self, sync) } if validations.present?
+
           raise Howitzer::NoValidationError, "No any page validation was found for '#{name}' page"
         end
 
@@ -78,17 +92,17 @@ module Howitzer
 
         private
 
-        def validate_element(element_name, value = nil)
+        def validate_by_element_presence(element_name, *args, **options)
           validations[:element_presence] =
             lambda do |web_page, sync|
               if element_name.present? && !private_method_defined?("#{element_name}_element")
                 raise(Howitzer::UndefinedElementError, ':element_presence validation refers to ' \
-                     "undefined '#{element_name}' element on '#{name}' page.")
+                                                       "undefined '#{element_name}' element on '#{name}' page.")
               end
               if sync
-                web_page.instance.public_send(*["has_#{element_name}_element?", value].compact)
+                web_page.instance.public_send("has_#{element_name}_element?", *args, **options)
               else
-                !web_page.instance.public_send(*["has_no_#{element_name}_element?", value].compact)
+                !web_page.instance.public_send("has_no_#{element_name}_element?", *args, **options)
               end
             end
         end
@@ -102,19 +116,6 @@ module Howitzer
           validations[:title] =
             ->(web_page, sync) { sync ? web_page.instance.has_title?(pattern) : pattern === web_page.instance.title }
         end
-
-        def validate_by_type(type, value, additional_value)
-          case type.to_s.to_sym
-            when :url
-              validate_by_url(value)
-            when :element_presence
-              validate_element(value, additional_value)
-            when :title
-              validate_by_title(value)
-            else
-              raise Howitzer::UnknownValidationError, "unknown '#{type}' validation type"
-          end
-        end
       end
     end
   end

data/lib/howitzer/web/section.rb

@@ -1,25 +1,36 @@
 require 'howitzer/web/base_section'
+require 'howitzer/meta'
 
 module Howitzer
   module Web
     # This class uses for named sections which possible to reuse in different pages
     class Section < BaseSection
+      # Provides access to meta information about entities in section
+      # @return [Meta::Entry]
+      def meta
+        @meta ||= Meta::Entry.new(self)
+      end
+
       class << self
         protected
 
         # DSL method which specifies section container selector represented by HTML element.
         # Any elements described in sections will start in this HTML element.
         # @param args [Array] original Capybara arguments. For details, see `Capybara::Node::Finders#all.
+        # @param options [Array] original Capybara options. For details, see `Capybara::Node::Finders#all.
         # @raise [ArgumentError] if no arguments were passed
         # @example
         #   class MenuSection < Howitzer::Web::Section
-        #     me :xpath, ".//*[@id='panel']"
+        #     me :xpath, ".//*[@id='panel']",
         #   end
         # @!visibility public
 
-        def me(*args)
+        def me(*args, **options)
           raise ArgumentError, 'Finder arguments are missing' if args.blank?
+
           @default_finder_args = args
+          @default_finder_options = options
+          self
         end
       end
     end