howitzer 1.1.1 → 2.0.0

data/lib/howitzer/mailgun_api/response.rb

@@ -0,0 +1,28 @@
+require 'howitzer/exceptions'
+
+module Howitzer
+  module MailgunApi
+    # A MailgunApi::Response object is instantiated for each response generated
+    # by the Client request. The Response object supports deserialization of
+    # the JSON result.
+    class Response
+      attr_accessor :body
+      attr_accessor :code
+
+      def initialize(response)
+        @body = response.body
+        @code = response.code
+      end
+
+      # Return a response as a Ruby Hash
+      # @raise [ParseError] in case of an json parsing error
+      # @return [Hash] HTTP result as hash.
+
+      def to_h
+        JSON.parse(@body)
+      rescue StandardError => e
+        raise ParseError, e.message
+      end
+    end
+  end
+end

data/lib/howitzer/tasks/framework.rake

@@ -1,3 +1,3 @@
 namespace :howitzer do
- #This is for future usage of built-in tasks
-end
+  # This is for future usage of built-in tasks
+end

data/lib/howitzer/utils.rb

@@ -2,4 +2,10 @@ require 'repeater'
 require 'active_support'
 require 'active_support/all'
 
-Dir[File.join(File.dirname(__FILE__), "./utils/**/*.rb")].each {|f| require f}
+module Howitzer
+  # This module holds different util staff
+  module Utils
+  end
+end
+
+require 'howitzer/utils/string_extensions'

data/lib/howitzer/utils/string_extensions.rb

@@ -0,0 +1,66 @@
+module Howitzer
+  module Utils
+    # This module extends standard String class with useful methods for Cucumber step definitions
+    module StringExtensions
+      # Opens a page by name
+      # @example
+      #   'home'.open #=> HomePage.open
+      # @see Howitzer::Web::Page.open
+
+      def open(*args)
+        as_page_class.open(*args)
+      end
+
+      # Returns an instantiated page by name
+      # @example
+      #   'home'.given #=> HomePage.given
+      # @see Howitzer::Web::Page.given
+
+      def given
+        as_page_class.given
+      end
+
+      # Waits until a page is opened or raises error
+      # @example
+      #   'home'.displayed? #=> HomePage.displayed?
+      # @see Howitzer::Web::Page.displayed?
+
+      def displayed?
+        as_page_class.displayed?
+      end
+
+      # Returns a page class by name
+      # @example
+      #   'home'.as_page_class #=> HomePage
+      # @see Howitzer::Web::Page
+
+      def as_page_class
+        as_class('Page')
+      end
+
+      # Returns an email class by name
+      # @example
+      #   'Reset Password'.as_email_class #=> ResetPasswordEmail
+      # @see Howitzer::Email
+
+      def as_email_class
+        as_class('Email')
+      end
+
+      # Executes code in context of the page
+      # @example
+      #   'home'.on { puts 1 } #=> HomePage.on { puts 1 }
+      # @see Howitzer::Web::Page.on
+
+      def on(&block)
+        as_page_class.on(&block)
+      end
+
+      private
+
+      def as_class(type)
+        "#{gsub(/\s/, '_').camelize}#{type}".constantize
+      end
+    end
+  end
+end

data/lib/howitzer/version.rb

@@ -1,3 +1,4 @@
+# This module holds howitzer version
 module Howitzer
-  VERSION = "1.1.1"
+  VERSION = '2.0.0'.freeze
 end

data/lib/howitzer/web.rb

@@ -0,0 +1,11 @@
+module Howitzer
+  # This class holds everything related with web GUI
+  module Web
+  end
+end
+require 'howitzer/web/page_validator'
+require 'howitzer/web/element_dsl'
+require 'howitzer/web/section_dsl'
+require 'howitzer/web/section'
+require 'howitzer/web/page'
+require 'howitzer/web/blank_page'

data/lib/howitzer/web/base_section.rb

@@ -0,0 +1,27 @@
+require 'howitzer/web/capybara_methods_proxy'
+require 'howitzer/web/element_dsl'
+require 'howitzer/web/iframe_dsl'
+require 'howitzer/web/section_dsl'
+
+module Howitzer
+  module Web
+    # This class holds base functinality for sections
+    class BaseSection
+      include CapybaraMethodsProxy
+      include ElementDsl
+      include SectionDsl
+      include IframeDsl
+
+      attr_reader :parent, :capybara_context
+
+      class << self
+        attr_reader :default_finder_args
+      end
+
+      def initialize(parent, context)
+        @parent = parent
+        @capybara_context = context
+      end
+    end
+  end
+end

data/lib/howitzer/web/blank_page.rb

@@ -0,0 +1,12 @@
+require 'howitzer/web/page'
+
+module Howitzer
+  module Web
+    # This class represents standard blank page in browser
+    class BlankPage < Page
+      site ''
+      path 'about:blank'
+      validate :url, /^about:blank$/
+    end
+  end
+end

data/lib/howitzer/web/capybara_methods_proxy.rb

@@ -0,0 +1,29 @@
+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]
+
+    # 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
+  end
+end

data/lib/howitzer/web/element_dsl.rb

@@ -0,0 +1,109 @@
+module Howitzer
+  module Web
+    # This module combines element dsl methods
+    module ElementDsl
+      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
+        end
+      end
+
+      # This module holds element dsl methods methods
+      module ClassMethods
+        protected
+
+        # Creates a group of methods to interact with described HTML element(s) on page
+        # @note This method generates following dynamic methods:
+        #
+        #   <b><em>element_name</em>_element</b> - equals capybara #find(...) method
+        #
+        #   <b><em>element_name</em>_elements</b> - equals capybara #all(...) method
+        #
+        #   <b><em>element_name</em>_elements.first</b> - equals capybara #first(...) 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
+        # @param name [Symbol, String] an unique element name
+        # @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 :new_button, :xpath, ".//*[@name='New']"
+        #
+        #     def press_new_button
+        #       new_button_element.click
+        #     end
+        #   end
+        #
+        #   HomePage.on { is_expected.to have_new_button_element }
+        #   HomePage.on { is_expected.to have_no_new_button_element }
+        # @example Using in a section class
+        #   class MenuSection < Howitzer::Web::Section
+        #     me '.main-menu'
+        #     element :menu_item, '.item'
+        #
+        #     def menu_items
+        #       menu_item_elements.map(&:text)
+        #     end
+        #   end
+        # @raise [BadElementParamsError] if wrong element arguments
+        # @!visibility public
+
+        def element(name, *args)
+          validate_arguments!(args)
+          define_element(name, args)
+          define_elements(name, args)
+          define_has_element(name, args)
+          define_has_no_element(name, args)
+        end
+
+        private
+
+        def validate_arguments!(args)
+          return unless args.map(&:class).count(Proc) > 1
+
+          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))
+          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))
+          end
+          private "#{name}_elements"
+        end
+
+        def define_has_element(name, args)
+          define_method("has_#{name}_element?") do |*block_args|
+            capybara_context.has_selector?(*convert_arguments(args, block_args))
+          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))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/howitzer/web/iframe_dsl.rb

@@ -0,0 +1,93 @@
+module Howitzer
+  module Web
+    # This module combines iframe dsl methods
+    module IframeDsl
+      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)
+        selector.is_a?(Integer) ? ["iframe:nth-of-type(#{selector + 1})"] : [:frame, selector]
+      end
+
+      # This module holds frame dsl class methods
+      module ClassMethods
+        protected
+
+        # Creates a group of methods to interact with described HTML frame on page
+        # @note This method generates following dynamic methods:
+        #
+        #   <b><em>frame_name</em>_iframe</b> - equals capybara #within_frame(...) method
+        #
+        #   <b>has_<em>frame_name</em>_iframe?</b> - equals capybara #has_selector(...) method
+        #
+        #   <b>has_no_<em>frame_name</em>_iframe?</b> - equals capybara #has_no_selector(...) method
+        # @param name [Symbol, String] an unique iframe name
+        # @param selector [Integer, String] frame name/id or index. Possible to specify id as #some_id
+        # @example Using in a page class
+        #   class FbPage < Howitzer::Web::Page
+        #     element :like, :xpath, ".//*[text()='Like']"
+        #     def like
+        #       like_element.click
+        #     end
+        #
+        #     def liked?
+        #       #some code here
+        #     end
+        #   end
+        #
+        #   class HomePage < Howitzer::Web::Page
+        #     iframe :fb, 1
+        #   end
+        #
+        #   HomePage.on do
+        #     fb_iframe do |frame|
+        #       frame.like
+        #       expect(frame).to be_liked
+        #     end
+        #   end
+        #   HomePage.on { is_expected.to have_fb_iframe }
+        # @!visibility public
+
+        def iframe(name, selector)
+          klass = "#{name}_page".classify.constantize
+          define_iframe(klass, name, selector)
+          define_has_iframe(name, selector)
+          define_has_no_iframe(name, selector)
+        end
+
+        private
+
+        def define_iframe(klass, name, selector)
+          define_method "#{name}_iframe" do |&block|
+            iframe_selector = selector.is_a?(Integer) ? selector : selector.split('#').last
+            capybara_context.within_frame(iframe_selector) do
+              block.call klass.instance
+            end
+          end
+        end
+
+        def define_has_iframe(name, selector)
+          define_method("has_#{name}_iframe?") do
+            capybara_context.has_selector?(*iframe_element_selector(selector))
+          end
+        end
+
+        def define_has_no_iframe(name, selector)
+          define_method("has_no_#{name}_iframe?") do
+            capybara_context.has_no_selector?(*iframe_element_selector(selector))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/howitzer/web/page.rb

@@ -0,0 +1,173 @@
+require 'singleton'
+require 'capybara'
+require 'rspec/expectations'
+require 'addressable/template'
+require 'howitzer/web/capybara_methods_proxy'
+require 'howitzer/web/page_validator'
+require 'howitzer/web/element_dsl'
+require 'howitzer/web/iframe_dsl'
+require 'howitzer/web/page_dsl'
+require 'howitzer/web/section_dsl'
+require 'howitzer/exceptions'
+
+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
+      include Singleton
+      include CapybaraMethodsProxy
+      include ElementDsl
+      include IframeDsl
+      include PageDsl
+      include SectionDsl
+      include PageValidator
+      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 params [Array] placeholder names and their values
+      # @return [Page]
+
+      def self.open(validate: true, **params)
+        url = expanded_url(params)
+        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?
+          Capybara.current_session.visit(url)
+        end
+        given if validate
+      end
+
+      # Returns a singleton instance of the web page
+      # @return [Page]
+
+      def self.given
+        displayed?
+        instance
+      end
+
+      # Tries to identify current page name or raise the error if ambiguous page matching
+      # @return [String] a page name
+      # @raise [UnknownPage] when no any matched pages
+      # @raise [AmbiguousPageMatchingError] when matched more than 1 page
+
+      def self.current_page
+        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
+
+      # Waits until a web page is opened
+      # @param time_out [Integer] time in seconds a required web page to be loaded
+      # @return [Boolean]
+      # @raise [IncorrectPageError] when timeout expired and the page is not displayed
+
+      def self.displayed?(timeout = Howitzer.page_load_idle_timeout)
+        end_time = ::Time.now + timeout
+        until ::Time.now > end_time
+          return true if opened?
+          sleep(0.5)
+        end
+        raise Howitzer::IncorrectPageError, incorrect_page_msg
+      end
+
+      # @return [String] current page url from browser
+
+      def self.current_url
+        Capybara.current_session.current_url
+      end
+
+      # Returns an expanded page url for the page opening
+      # @param params [Array] placeholders and their values
+      # @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?
+        raise Howitzer::NoPathForPageError, "Please specify path for '#{self}' page. Example: path '/home'"
+      end
+
+      class << self
+        protected
+
+        # DSL to specify an relative path pattern for the page opening
+        # @param value [String] a path pattern, for details please see Addressable gem
+        # @see .site
+        # @example
+        #   class ArticlePage < Howitzer::Web::Page
+        #     url '/articles/:id'
+        #   end
+        #   ArticlePage.open(id: 10)
+        # @!visibility public
+
+        def path(value)
+          @path_template = value.to_s
+        end
+
+        # DSL to specify a site for the page opening
+        # @note By default it specifies Howitzer.app_uri.site as a site
+        # @param value [String] a site as combination of protocol, host and port
+        # @example
+        #   class AuthPage < Howitzer::Web::Page
+        #     site 'https:/example.com'
+        #   end
+        #
+        #   class LoginPage < AuthPage
+        #     path '/login'
+        #   end
+        # @!visibility public
+
+        def site(value)
+          define_singleton_method(:app_host) { value }
+          private_class_method :app_host
+        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}"
+        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
+      end
+
+      site Howitzer.app_uri.site
+
+      def initialize
+        check_validations_are_defined!
+        current_window.maximize if Howitzer.maximized_window
+      end
+
+      # Reloads current page in a browser
+
+      def reload
+        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