howitzer 2.2.0 → 2.3.0

data/lib/howitzer/gmail_api/client.rb

@@ -1,11 +1,16 @@
-require 'gmail'
-
 module Howitzer
   module GmailApi
     # A GmailApi::Client object is used to communicate with the Gmail API.
     class Client
+      def self.load_gmail_gem!
+        require 'gmail'
+      rescue LoadError
+        raise LoadError, "Unable to load `gmail` library, please add following code to your Gemfile:\n\ngem 'gmail'"
+      end
+      load_gmail_gem!
+
       def initialize
-        @client = Gmail.connect(Howitzer.gmail_login, Howitzer.gmail_password)
+        self.client = Gmail.connect(Howitzer.gmail_login, Howitzer.gmail_password)
       end
 
       # Finds message according to given parameters
@@ -15,8 +20,12 @@ module Howitzer
       # @return [Gmail::Message] gmail message object
 
       def find_message(recipient, subject)
-        @client.inbox.emails(to: recipient, subject: subject).last
+        client.inbox.emails(to: recipient, subject: subject).last
       end
+
+      private
+
+      attr_accessor :client
     end
   end
 end

data/lib/howitzer/log.rb

@@ -80,13 +80,13 @@ module Howitzer
       Logger['ruby_log'].trace = true
     end
 
-    #:nocov:
+    # :nocov:
     def log_without_formatting
       self.base_formatter = blank_formatter
       yield
       self.base_formatter = default_formatter
     end
-    #:nocov:
+    # :nocov:
 
     def console_log
       StdoutOutputter.new(:console).tap { |o| o.only_at(INFO, DEBUG, WARN) }
@@ -96,13 +96,13 @@ module Howitzer
       StderrOutputter.new(:error, 'level' => ERROR)
     end
 
-    #:nocov:
+    # :nocov:
     def blank_formatter
       PatternFormatter.new(pattern: '%m')
     end
-    #:nocov:
+    # :nocov:
 
-    #:nocov:
+    # :nocov:
     def default_formatter
       params = if Howitzer.hide_datetime_from_log
                  { pattern: '[%l] %m' }
@@ -111,7 +111,7 @@ module Howitzer
                end
       PatternFormatter.new(params)
     end
-    #:nocov:
+    # :nocov:
 
     def base_formatter=(formatter)
       @logger.outputters.each { |outputter| outputter.formatter = formatter }

data/lib/howitzer/mailgun_api/client.rb

@@ -9,9 +9,10 @@ module Howitzer
     # wrapper around RestClient so you don't have to worry about the HTTP aspect
     # of communicating with Mailgun API.
     class Client
-      USER_AGENT = 'mailgun-sdk-ruby'.freeze #:nodoc:
+      USER_AGENT = 'mailgun-sdk-ruby'.freeze # :nodoc:
       attr_reader :api_user, :api_key, :api_host, :api_version, :ssl
-      def initialize(api_user: 'api', api_key:, api_host: 'api.mailgun.net', api_version: 'v3', ssl: true)
+
+      def initialize(api_user: 'api', api_key: 'key', api_host: 'api.mailgun.net', api_version: 'v3', ssl: true)
         @api_user = api_user
         @api_key = api_key
         @api_host = api_host

data/lib/howitzer/mailgun_api/response.rb

@@ -6,8 +6,7 @@ module Howitzer
     # by the Client request. The Response object supports deserialization of
     # the JSON result.
     class Response
-      attr_accessor :body
-      attr_accessor :code
+      attr_accessor :body, :code
 
       def initialize(response)
         @body = response.body

data/lib/howitzer/mailtrap_api/client.rb

@@ -5,7 +5,7 @@ module Howitzer
   module MailtrapApi
     # A Mailtrap::Client object is used to communicate with the Mailtrap API.
     class Client
-      BASE_URL = "https://mailtrap.io/api/v1/inboxes/#{Howitzer.mailtrap_inbox_id}".freeze #:nodoc:
+      BASE_URL = "https://mailtrap.io/api/v1/inboxes/#{Howitzer.mailtrap_inbox_id}".freeze # :nodoc:
 
       def initialize
         @api_token = Howitzer.mailtrap_api_token

data/lib/howitzer/meta/actions.rb

@@ -3,23 +3,26 @@ module Howitzer
     # 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 and
-      # inline options for element/s as a hash
-      def highlight(*args)
-        if xpath(*args).blank?
+      # @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
-        context.execute_script("document.evaluate('#{escape(xpath(*args))}', document, null, " \
-                          'XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue.style.border = "thick solid red"')
+        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 and
-      # inline options for element/s as a hash
+      # @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)
-        capybara_element(*args).try(:path)
+      def xpath(*args, **options)
+        capybara_element(*args, **options).try(:path)
       end
 
       private
@@ -27,12 +30,6 @@ module Howitzer
       def escape(xpath)
         xpath.gsub(/(['"])/, '\\\\\\1')
       end
-
-      def convert_args(args)
-        new_args = []
-        params = args.reject { |v| new_args << v if v.is_a?(Hash) }
-        [params, new_args.reduce(:merge)].flatten
-      end
     end
   end
 end

data/lib/howitzer/meta/element.rb

@@ -14,22 +14,24 @@ module Howitzer
       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 and
-      # inline options for element/s as a hash
+      # @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)
-        context.send("#{name}_elements", *args)
+      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 and
-      # inline options for element/s as a hash
+      # @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)
-        args << { match: :first, wait: wait }
-        args = convert_args(args)
-        context.send("#{name}_element", *args)
+      def capybara_element(*args, wait: 0, **options)
+        context.send("#{name}_element", *args, **options.merge(match: :first, wait: wait))
       rescue Capybara::ElementNotFound
         nil
       end

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.2.0'.freeze #:nodoc:
+  VERSION = '2.3.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_methods_proxy.rb

@@ -3,7 +3,7 @@ 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
@@ -13,7 +13,7 @@ class Capybara::Selenium::Driver # rubocop:disable Style/ClassAndModuleChildren
     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?
@@ -27,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]
 
@@ -41,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

data/lib/howitzer/web/element_dsl.rb

@@ -3,40 +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, params)
-        args, params, options = merge_element_options(args, params)
-        args = args.map do |el|
-          next(el) unless el.is_a?(Proc)
+      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
 
-          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
@@ -57,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'
@@ -93,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
@@ -111,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
@@ -145,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

data/lib/howitzer/web/page.rb

@@ -14,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
@@ -28,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
 
@@ -40,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?
@@ -151,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
 

data/lib/howitzer/web/page_dsl.rb

@@ -29,11 +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
+          return eval_in_out_context(*args, **options, &block) if name == :out
 
-          page_klass.given.send(name, *args, &block)
+          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
@@ -45,13 +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)
@@ -61,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.