howitzer 2.1.1 → 2.4.0

data/lib/howitzer/web/page_dsl.rb

@@ -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

data/lib/howitzer/web/section_dsl.rb

@@ -5,7 +5,7 @@ module Howitzer
     module SectionDsl
       include CapybaraContextHolder
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend(ClassMethods)
       end
 
@@ -17,8 +17,9 @@ module Howitzer
 
           # Instantiates an anynomous or named section and executes block code in the section scope
 
-          def initialize(name, *args, &block)
+          def initialize(name, *args, **options, &block)
             @args = args
+            @options = options
             self.section_class =
               if block
                 Class.new(Howitzer::Web::BaseSection)
@@ -29,29 +30,40 @@ module Howitzer
           end
 
           # # Defines an element on the section
-          # # @see Howitzer::PageDsl::ClassMethods#element
+          # # @see Howitzer::Web::ElementDsl::ClassMethods#element
 
-          def element(*args)
-            section_class.send(:element, *args)
+          def element(*args, **options)
+            section_class.send(:element, *args, **options)
           end
 
           # Delegates a section describing to the section class
 
-          def section(name, *args, &block)
-            section_class.send(:section, name, *args, &block)
+          def section(name, *args, **options, &block)
+            section_class.send(:section, name, *args, **options, &block)
           end
 
-          # Returns a selector for the section.
+          # Returns selector arguments for the section.
           # @note If anonymous section uses, then inline selector should be specified.
           #   Otherwise arguments should be defined with `.me` dsl method in named section
           # @return [Array]
           # @raise [ArgumentError] when finder arguments were not specified
 
           def finder_args
-            @finder_args ||= begin
-              return @args if @args.present?
-              section_class.default_finder_args || raise(ArgumentError, 'Missing finder arguments')
-            end
+            return @args if @args.present?
+
+            @finder_args ||= (section_class.default_finder_args || raise(ArgumentError, 'Missing finder arguments'))
+          end
+
+          # Returns selector options for the section.
+          # @note If anonymous section uses, then inline selector should be specified.
+          #   Otherwise arguments should be defined with `.me` dsl method in named section
+          # @return [Array]
+          # @raise [ArgumentError] when finder arguments were not specified
+
+          def finder_options
+            @options if @args.present? # it is ok to have blank options, so we rely here on the argments
+
+            @finder_options ||= (section_class.default_finder_options || {})
           end
         end
 
@@ -74,6 +86,9 @@ module Howitzer
         # @param args [Array] original Capybara arguments. For details, see `Capybara::Node::Finders#all.
         #  (In most cases should be ommited for named sections because the section selector is specified
         #  with `#me` method. But must be specified for anonymous sections)
+        # @param options [Hash] original Capybara options. For details, see `Capybara::Node::Finders#all.
+        #  (In most cases should be ommited for named sections because the section selector is specified
+        #  with `#me` method. But may be specified for anonymous sections)
         # @param block [Proc] this block can contain nested sections and elements
         # @example Named section
         #   class MenuSection < Howitzer::Web::Section
@@ -109,37 +124,57 @@ module Howitzer
         #   HomePage.on { info_panel_section.edit_info(title: 'Test Title') }
         # @!visibility public
 
-        def section(name, *args, &block)
-          scope = SectionScope.new(name, *args, &block)
-          define_section_method(scope.section_class, name, scope.finder_args)
-          define_sections_method(scope.section_class, name, scope.finder_args)
-          define_has_section_method(name, scope.finder_args)
-          define_has_no_section_method(name, scope.finder_args)
+        def section(name, *args, **options, &block)
+          scope = SectionScope.new(name, *args, **options, &block)
+          define_section_method(scope.section_class, name, *scope.finder_args, **scope.finder_options)
+          define_sections_method(scope.section_class, name, *scope.finder_args, **scope.finder_options)
+          define_has_section_method(name, *scope.finder_args, **scope.finder_options)
+          define_has_no_section_method(name, *scope.finder_args, **scope.finder_options)
         end
 
         private
 
-        def define_section_method(klass, name, args)
-          define_method("#{name}_section") do
-            klass.new(self, capybara_context.find(*args))
+        def define_section_method(klass, name, *args, **options)
+          define_method("#{name}_section") do |**block_options|
+            kwdargs = options.transform_keys(&:to_sym).merge(block_options.transform_keys(&:to_sym))
+            if kwdargs.present?
+              klass.new(self, capybara_context.find(*args, **kwdargs))
+            else
+              klass.new(self, capybara_context.find(*args))
+            end
           end
         end
 
-        def define_sections_method(klass, name, args)
-          define_method("#{name}_sections") do
-            capybara_context.all(*args).map { |el| klass.new(self, el) }
+        def define_sections_method(klass, name, *args, **options)
+          define_method("#{name}_sections") do |**block_options|
+            kwdargs = options.transform_keys(&:to_sym).merge(block_options.transform_keys(&:to_sym))
+            if kwdargs.present?
+              capybara_context.all(*args, **kwdargs).map { |el| klass.new(self, el) }
+            else
+              capybara_context.all(*args).map { |el| klass.new(self, el) }
+            end
           end
         end
 
-        def define_has_section_method(name, args)
-          define_method("has_#{name}_section?") do
-            capybara_context.has_selector?(*args)
+        def define_has_section_method(name, *args, **options)
+          define_method("has_#{name}_section?") do |**block_options|
+            kwdargs = options.transform_keys(&:to_sym).merge(block_options.transform_keys(&:to_sym))
+            if kwdargs.present?
+              capybara_context.has_selector?(*args, **kwdargs)
+            else
+              capybara_context.has_selector?(*args)
+            end
           end
         end
 
-        def define_has_no_section_method(name, args)
-          define_method("has_no_#{name}_section?") do
-            capybara_context.has_no_selector?(*args)
+        def define_has_no_section_method(name, *args, **options)
+          define_method("has_no_#{name}_section?") do |**block_options|
+            kwdargs = options.transform_keys(&:to_sym).merge(block_options.transform_keys(&:to_sym))
+            if kwdargs.present?
+              capybara_context.has_no_selector?(*args, **kwdarg)
+            else
+              capybara_context.has_no_selector?(*args)
+            end
           end
         end
       end

data/lib/howitzer.rb

@@ -29,6 +29,45 @@ module Howitzer
       ::SexySettings::Base.instance.all['mailgun_idle_timeout']
     end
 
+    # @return active session name
+
+    def session_name
+      @session_name ||= 'default'
+    end
+
+    # Sets new session name
+    #
+    # @param name [String] string identifier for the session
+    #
+    # @example Executing code in another browser
+    # Howitzer.session_name = 'browser2'
+    # LoginPage.on do
+    #   expect(title).to eq('Login Page')
+    # end
+    #
+    # # Switching back to main browser
+    # Howitzer.session_name = 'default'
+
+    def session_name=(name)
+      @session_name = name
+      Capybara.session_name = @session_name
+    end
+
+    # Yield a block using a specific session name
+    #
+    # @param name [String] string identifier for the session
+    #
+    # @example Opening page in another browser
+    # Howitzer.using_session('browser2') do
+    #   LoginPage.on do
+    #     expect(title).to eq('Login Page')
+    #   end
+    # end
+
+    def using_session(name, &block)
+      Capybara.using_session(name, &block)
+    end
+
     attr_accessor :current_rake_task
   end
 
@@ -60,6 +99,7 @@ module Howitzer
 
   def self.sexy_setting!(name)
     return Howitzer.public_send(name) if Howitzer.respond_to?(name)
+
     raise UndefinedSexySettingError,
           "Undefined '#{name}' setting. Please add the setting to config/default.yml:\n #{name}: some_value\n"
   end