howitzer 2.0.0 → 2.0.1

data/lib/howitzer/mail_adapters/abstract.rb

@@ -17,10 +17,11 @@ module Howitzer
       attr_reader :message
 
       # Finds an email in mailbox
-      # @param recipient [String] an email
-      # @param subject [String]
+      # @param _recipient [String] an email
+      # @param _subject [String]
+      # @param _wait [Integer] how much time is required to wait an email
 
-      def self.find(_recipient, _subject)
+      def self.find(_recipient, _subject, _wait:)
         raise NotImplementedError
       end
 

data/lib/howitzer/mail_adapters/mailgun.rb

@@ -10,11 +10,12 @@ module Howitzer
       # @note emails are stored for 3 days only!
       # @param recipient [String] an email
       # @param subject [String]
-      # @raise [EmailNotFoundError] if message blank
+      # @param wait [Integer] how much time is required to wait an email
+      # @raise [EmailNotFoundError] if blank message
 
-      def self.find(recipient, subject)
+      def self.find(recipient, subject, wait:)
         message = {}
-        retryable(find_retry_params) { message = retrieve_message(recipient, subject) }
+        retryable(find_retry_params(wait)) { message = retrieve_message(recipient, subject) }
         return new(message) if message.present?
         raise Howitzer::EmailNotFoundError,
               "Message with subject '#{subject}' for recipient '#{recipient}' was not found."
@@ -91,9 +92,9 @@ module Howitzer
       end
       private_class_method :event_by
 
-      def self.find_retry_params
+      def self.find_retry_params(wait)
         {
-          timeout: Howitzer.mailgun_idle_timeout,
+          timeout: wait || Howitzer.try(:mailgun_idle_timeout),
           sleep: Howitzer.mailgun_sleep_time,
           silent: true,
           logger: Howitzer::Log,

data/lib/howitzer/mailgun_api/client.rb

@@ -9,7 +9,7 @@ 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
+      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)
         @api_user = api_user

data/lib/howitzer/version.rb

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

data/lib/howitzer/web/base_section.rb

@@ -7,12 +7,12 @@ module Howitzer
   module Web
     # This class holds base functinality for sections
     class BaseSection
-      include CapybaraMethodsProxy
       include ElementDsl
       include SectionDsl
       include IframeDsl
+      include CapybaraMethodsProxy
 
-      attr_reader :parent, :capybara_context
+      attr_reader :parent
 
       class << self
         attr_reader :default_finder_args
@@ -20,7 +20,7 @@ module Howitzer
 
       def initialize(parent, context)
         @parent = parent
-        @capybara_context = context
+        capybara_scopes << context
       end
     end
   end

data/lib/howitzer/web/capybara_context_holder.rb

@@ -0,0 +1,19 @@
+module Howitzer
+  module Web
+    # This module mixin capybara context methods
+    module CapybaraContextHolder
+      # Returns capybara context. For example, capybara session, parent element, etc.
+
+      def capybara_context
+        capybara_scopes.last
+      end
+
+      private
+
+      def capybara_scopes
+        return super if defined?(super)
+        raise NotImplementedError, "Please define 'capybara_scopes' method for class holder"
+      end
+    end
+  end
+end

data/lib/howitzer/web/capybara_methods_proxy.rb

@@ -1,28 +1,36 @@
 require 'capybara'
 
 module Howitzer
-  # This module proxies required original capybara methods to recipient
-  module CapybaraMethodsProxy
-    PROXIED_CAPYBARA_METHODS = Capybara::Session::SESSION_METHODS +
-                               Capybara::Session::MODAL_METHODS +
-                               [:driver, :text]
+  module Web
+    # This module proxies required original capybara methods to recipient
+    module CapybaraMethodsProxy
+      PROXIED_CAPYBARA_METHODS = Capybara::Session::SESSION_METHODS + #:nodoc:
+                                 Capybara::Session::MODAL_METHODS +
+                                 [:driver, :text]
 
-    # Capybara form dsl methods are not compatible with page object pattern and Howitzer gem.
-    # 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) }
-    end
+      # Capybara form dsl methods are not compatible with page object pattern and Howitzer gem.
+      # 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) }
+      end
+
+      # Accepts or declines JS alert box by given flag
+      # @param flag [Boolean] Determines accept or decline alert box
+
+      def click_alert_box(flag)
+        if %w(selenium sauce).include? Howitzer.driver
+          alert = driver.browser.switch_to.alert
+          flag ? alert.accept : alert.dismiss
+        else
+          evaluate_script("window.confirm = function() { return #{flag}; }")
+        end
+      end
 
-    # Accepts or declines JS alert box by given flag
-    # @param flag [Boolean] Determines accept or decline alert box
+      private
 
-    def click_alert_box(flag)
-      if %w(selenium sauce).include? Howitzer.driver
-        alert = driver.browser.switch_to.alert
-        flag ? alert.accept : alert.dismiss
-      else
-        evaluate_script("window.confirm = function() { return #{flag}; }")
+      def capybara_scopes
+        @_scopes ||= [Capybara.current_session]
       end
     end
   end

data/lib/howitzer/web/element_dsl.rb

@@ -1,24 +1,24 @@
+require 'howitzer/web/capybara_context_holder'
 module Howitzer
   module Web
     # This module combines element dsl methods
     module ElementDsl
+      include CapybaraContextHolder
+
       def self.included(base) #:nodoc:
         base.extend(ClassMethods)
       end
 
-      # Returns capybara context. For example, capybara session, parent element, etc.
-      # @abstract should be defined in parent context
-
-      def capybara_context
-        raise NotImplementedError, "Please define 'capybara_context' method for class holder"
-      end
-
       private
 
       def convert_arguments(args, params)
-        args.map do |arg|
-          arg.is_a?(Proc) ? arg.call(*params) : arg
+        hash = params.deep_dup.pop if params.last.is_a?(Hash)
+        args = args.map do |el|
+          next(el) unless el.is_a?(Proc)
+          el.call(*params.shift(el.arity))
         end
+        args << hash unless hash.nil?
+        args
       end
 
       # This module holds element dsl methods methods
@@ -34,6 +34,10 @@ module Howitzer
         #
         #   <b><em>element_name</em>_elements.first</b> - equals capybara #first(...) method
         #
+        #   <b>wait_for_<em>element_name</em>_element</b> - equals capybara #find(...) method but returns nil
+        #
+        #   <b>within_<em>element_name</em>_element</b> - equals capybara #within(...) method
+        #
         #   <b>has_<em>element_name</em>_element?</b> - equals capybara #has_selector(...) method
         #
         #   <b>has_no_<em>element_name</em>_element?</b> - equals capybara #has_no_selector(...) method
@@ -41,15 +45,28 @@ module Howitzer
         # @param args [Array] original Capybara arguments. For details, see `Capybara::Node::Finders#all.
         # @example Using in a page class
         #   class HomePage < Howitzer::Web::Page
+        #     element :top_panel, '.top'
+        #     element :bottom_panel, '.bottom'
         #     element :new_button, :xpath, ".//*[@name='New']"
         #
-        #     def press_new_button
-        #       new_button_element.click
+        #     def press_top_new_button
+        #       within_top_panel_element do
+        #         new_button_element.click
+        #       end
+        #     end
+        #
+        #     def press_bottom_new_button
+        #       within_bottom_panel_element do
+        #         new_button_element.click
+        #       end
         #     end
         #   end
         #
-        #   HomePage.on { is_expected.to have_new_button_element }
-        #   HomePage.on { is_expected.to have_no_new_button_element }
+        #   HomePage.on do
+        #     is_expected.to have_top_panel_element
+        #     press_top_new_element
+        #     is_expected.to have_no_new_button_element(match: :first)
+        #   end
         # @example Using in a section class
         #   class MenuSection < Howitzer::Web::Section
         #     me '.main-menu'
@@ -66,6 +83,8 @@ module Howitzer
           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)
         end
@@ -92,6 +111,26 @@ module Howitzer
           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))
+            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))
+            begin
+              capybara_scopes.push(new_scope)
+              block.call
+            ensure
+              capybara_scopes.pop
+            end
+          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))

data/lib/howitzer/web/iframe_dsl.rb

@@ -1,18 +1,14 @@
+require 'howitzer/web/capybara_context_holder'
 module Howitzer
   module Web
     # This module combines iframe dsl methods
     module IframeDsl
+      include CapybaraContextHolder
+
       def self.included(base) #:nodoc:
         base.extend(ClassMethods)
       end
 
-      # Returns capybara context. For example, capybara session, parent element, etc.
-      # @abstract should be defined in parent context
-
-      def capybara_context
-        raise NotImplementedError, "Please define 'capybara_context' method for class holder"
-      end
-
       private
 
       def iframe_element_selector(selector)

data/lib/howitzer/web/page.rb

@@ -1,5 +1,4 @@
 require 'singleton'
-require 'capybara'
 require 'rspec/expectations'
 require 'addressable/template'
 require 'howitzer/web/capybara_methods_proxy'
@@ -14,7 +13,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
+      UnknownPage = Class.new #:nodoc:
       include Singleton
       include CapybaraMethodsProxy
       include ElementDsl
@@ -25,22 +24,20 @@ module Howitzer
       include ::RSpec::Matchers
 
       # This Ruby callback makes all inherited classes as singleton classes.
-      # In additional it addes current page to page validator pages in case
-      # if it has any defined validations.
 
       def self.inherited(subclass)
         subclass.class_eval { include Singleton }
-        PageValidator.pages << subclass if subclass.validations.present?
       end
 
       # Opens a web page in browser
       # @note It tries to open the page twice and then raises the error if a validation is failed
       # @param validate [Boolean] if fase will skip current page validation (is opened)
+      # @param url_processor [Class] custom url processor. For details see 'addressable' gem
       # @param params [Array] placeholder names and their values
       # @return [Page]
 
-      def self.open(validate: true, **params)
-        url = expanded_url(params)
+      def self.open(validate: true, url_processor: nil, **params)
+        url = expanded_url(params, url_processor)
         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?
@@ -70,7 +67,7 @@ module Howitzer
       end
 
       # Waits until a web page is opened
-      # @param time_out [Integer] time in seconds a required web page to be loaded
+      # @param timeout [Integer] time in seconds a required web page to be loaded
       # @return [Boolean]
       # @raise [IncorrectPageError] when timeout expired and the page is not displayed
 
@@ -91,11 +88,14 @@ module Howitzer
 
       # Returns an expanded page url for the page opening
       # @param params [Array] placeholders and their values
+      # @param url_processor [Class] custom url processor. For details see Addressable gem
       # @return [String]
       # @raise [NoPathForPageError] if an url is not specified for the page
 
-      def self.expanded_url(params = {})
-        return "#{app_host}#{Addressable::Template.new(path_template).expand(params)}" unless path_template.nil?
+      def self.expanded_url(params = {}, url_processor = nil)
+        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
 
@@ -113,7 +113,8 @@ module Howitzer
         # @!visibility public
 
         def path(value)
-          @path_template = value.to_s
+          define_singleton_method(:path_value) { value.to_s }
+          private_class_method :path_value
         end
 
         # DSL to specify a site for the page opening
@@ -130,14 +131,12 @@ module Howitzer
         # @!visibility public
 
         def site(value)
-          define_singleton_method(:app_host) { value }
-          private_class_method :app_host
+          define_singleton_method(:site_value) { value }
+          private_class_method :site_value
         end
 
         private
 
-        attr_reader :path_template
-
         def incorrect_page_msg
           "Current page: #{current_page}, expected: #{self}.\n" \
                     "\tCurrent url: #{current_url}\n\tCurrent title: #{instance.title}"
@@ -162,12 +161,6 @@ module Howitzer
         Howitzer::Log.info "Reload '#{current_url}'"
         visit current_url
       end
-
-      # Returns capybara context as current session
-
-      def capybara_context
-        Capybara.current_session
-      end
     end
   end
 end

data/lib/howitzer/web/page_dsl.rb

@@ -8,6 +8,7 @@ module Howitzer
 
         def initialize(page_klass, &block)
           self.page_klass = page_klass
+          self.outer_context = eval('self', block.binding) if block.present?
           instance_eval(&block)
         end
 
@@ -20,10 +21,16 @@ module Howitzer
           expect(page_klass.given)
         end
 
-        # Proxies all methods to page instance except methods with be_ and have_ prefixes
+        # Proxies all methods to a page instance.
+        #
+        # @note There are some exceptions:
+        #   * Methods with `be_` and `have_` prefixes are excluded
+        #   * `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)
           return super if name =~ /\A(?:be|have)_/
+          return eval_in_out_context(*args, &block) if name == :out
           page_klass.given.send(name, *args, &block)
         end
 
@@ -36,10 +43,21 @@ module Howitzer
 
         private
 
-        attr_accessor :page_klass
+        def eval_in_out_context(*args, &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)
+        end
+
+        def get_outer_instance_variable(name)
+          outer_context.instance_variable_get(name)
+        end
+
+        attr_accessor :page_klass, :outer_context
       end
 
-      def self.included(base)
+      def self.included(base) #:nodoc:
         base.extend(ClassMethods)
       end
       # This module holds page dsl class methods
@@ -47,12 +65,22 @@ module Howitzer
         # Allows to execute page methods in context of the page.
         # @note It additionally checks the page is really displayed
         #   on each method call, otherwise it raises error
-        # @example
+        # @example Standard case
         #   LoginPage.open
         #   LoginPage.on do
         #     fill_form(name: 'John', email: 'jkarpensky@gmail.com')
         #     submit_form
         #   end
+        # @example More complex case with outer context
+        #   @name = 'John'
+        #   def email(domain = 'gmail.com')
+        #     "jkarpensky@#{domain}"
+        #   end
+        #   LoginPage.open
+        #   LoginPage.on do
+        #     fill_form(name: out(:@name), email: out(:email, 'yahoo.com'))
+        #     submit_form
+        #   end
 
         def on(&block)
           PageScope.new(self, &block)