qat-web 6.0.0

data/lib/qat/web/elements/selector.rb

@@ -0,0 +1,108 @@
+require 'qat/web/configuration'
+require 'active_support/core_ext/hash/keys'
+
+module QAT
+  module Web
+    module Elements
+      # Helper methods for handling selectors and selector transformations
+      module Selector
+        include QAT::Web::Configuration
+
+        # Invalid Configuration Errors
+        class InvalidConfigurationError < StandardError
+          # Creates a new InvalidConfigurationError
+          # @param config [Hash] element selector configuration
+          def initialize(config)
+            super "Invalid configuration found:\n#{config.ai}"
+          end
+        end
+
+        # Returns the selector from configuration
+        # @param config [Hash] element selector configuration
+        # @param args [Array] (Optional) Substitutions to the XPATH string base in $ syntax
+        # @return [Array] selector
+        #
+        # @example
+        #   xpath with ".//div[@class='ng-pristine' and text()='$0']//span[contains(text(), '$1')]"
+        #   args with: ["Some Text", "More Text" ]
+        #   The final output will be ".//div[@class='ng-pristine' and text()='Some Text']//span[contains(text(), 'More Text')]"
+        #
+        def selector(config, *args)
+          extract_selector(config, *args)
+        end
+
+        private
+
+        # Extracts the ID or XPATH from the immediate node from the config
+        #
+        # @param config [Hash] element selector configuration
+        # @param args [Array] (Optional) Substitutions to the XPATH string base in $ syntax
+        # @return [Array] selector
+        #
+        # @example
+        #   xpath with ".//div[@class='ng-pristine' and text()='$0']//span[contains(text(), '$1')]"
+        #   args with: ["Some Text", "More Text" ]
+        #   The final output will be ".//div[@class='ng-pristine' and text()='Some Text']//span[contains(text(), 'More Text')]"
+        #
+        def extract_selector(config, *args)
+          type  = fetch_type(config)
+          value = parse_value(config[type], *args)
+          opts  = options(config)
+          save_config(type, value, opts)
+          if opts.any?
+            return type.to_sym, value, opts
+          else
+            return type.to_sym, value
+          end
+        end
+
+        # Returns the correct selector type from configuration
+        # @param config [Hash] element selector configuration
+        # @return [Symbol]
+        def fetch_type(config)
+          types = Capybara::Selector.all.keys & config.symbolize_keys.keys
+
+          raise InvalidConfigurationError.new config unless types.size == 1
+
+          types.first
+        end
+
+        # Parse the selector value for the given configuration through given arguments
+        # A list of substitutions will be applied from those arguments
+        # @param value [String] selector value
+        # @param args [Array] list of substitutions to apply
+        # @see #extract_selector
+        def parse_value(value, *args)
+          if args.empty?
+            value
+          else
+            args.each_with_index do |arg, index|
+              value = value.gsub("$#{index}", arg)
+            end
+            value
+          end
+        end
+
+        # Return valid options for Capybara
+        # @param config [Hash] element selector configuration
+        # @return [Array]
+        def options(config)
+          config.symbolize_keys.select { |key, _| Capybara::Queries::SelectorQuery::VALID_KEYS.include?(key) }
+        end
+
+        # Saves the last configuration access
+        # @param type [Symbol] selector type
+        # @param value [String] selector value
+        # @param opts [Hash] selector options
+        # @return [Hash]
+        def save_config(type, value, opts)
+          config                              = { type => value }.merge(opts)
+          QAT::Web::Configuration.last_access = config
+          @last_access                        = config
+        end
+
+        extend self
+      end
+    end
+  end
+end

data/lib/qat/web/elements/waiters.rb

@@ -0,0 +1,103 @@
+require_relative 'selector'
+require_relative 'config'
+require 'retriable'
+require 'qat/logger'
+
+module QAT
+  module Web
+    module Elements
+      # Helper methods for handling timeouts and wait periods
+      module Waiters
+        include QAT::Logger
+        include Selector
+        include Config
+
+        # Defines timeouts through a configuration file path
+        # @param path [String] path to timeouts configuration file
+        # @return [HashWithIndifferentAccess]
+        def timeouts_file(path)
+          raise(ArgumentError, "File '#{path}' does not exist!") unless File.exist?(path)
+          @timeouts_file = path
+          begin
+            config = YAML.load(File.read(@timeouts_file)) || {}
+          rescue Psych::SyntaxError
+            log.error "Failed to load file '#{@timeouts_file}'."
+            raise
+          end
+          timeouts_config(config)
+        end
+
+        # Defines timeouts through a configuration hash
+        # @param timeouts [Hash] timeouts configuration
+        # @return [HashWithIndifferentAccess]
+        def timeouts_config(timeouts)
+          valid_config?(timeouts, 'timeouts')
+          @timeouts = HashWithIndifferentAccess.new(timeouts)
+        end
+
+        # Returns the timeouts configuration
+        # @return [HashWithIndifferentAccess]
+        def timeouts
+          @timeouts
+        end
+
+        # Waits a maximum timeout time until an element is present on page
+        # @param selector [Hash] element selector
+        # @param timeout [Integer] maximum time to wait
+        def wait_until_present(selector, timeout)
+          type, value, options = build_selector(selector, { visible: false, wait: timeout })
+          has_selector?(type, value, options)
+        end
+
+        # Waits a maximum timeout time until an element is visible on page
+        # @param selector [Hash] element selector
+        # @param timeout [Integer] maximum time to wait
+        def wait_until_visible(selector, timeout)
+          type, value, options = build_selector(selector, { visible: true, wait: timeout })
+          has_selector?(type, value, options)
+        end
+
+        # Waits a maximum timeout time until an element is no longer present on page
+        # @param selector [Hash] element selector
+        # @param timeout [Integer] maximum time to wait
+        def wait_until_not_present(selector, timeout)
+          type, value, options = build_selector(selector, { wait: timeout })
+          has_no_selector?(type, value, options)
+        end
+
+        # Waits a maximum timeout time until an element is no longer visible on page
+        # @param selector [Hash] element selector
+        # @param timeout [Integer] maximum time to wait
+        def wait_until_not_visible(selector, timeout)
+          type, value, options = build_selector(selector, { visible: false, wait: timeout })
+          has_no_selector?(type, value, options)
+        end
+
+        # Generic wait method
+        # @param timeout [Integer] max time to wait
+        # @param klass [Class] (nil) an optional exception class to retry on error
+        # @yield
+        def wait_until(timeout, klass = nil, &block)
+          default_time = Capybara.default_max_wait_time
+          timeout      ||= default_time
+          tries        = timeout / default_time
+          exceptions   = [Capybara::ElementNotFound, Capybara::ExpectationNotMet]
+          exceptions << klass if klass
+          Retriable.retriable(on:            exceptions,
+                              tries:         tries.ceil,
+                              base_interval: default_time) do
+            yield
+          end
+        end
+
+        private
+
+        def build_selector(selector, options)
+          type, value, opts = *selector
+          options           = opts.merge(options) if opts&.any?
+          [type, value, options]
+        end
+      end
+    end
+  end
+end

data/lib/qat/web/error.rb

@@ -0,0 +1,14 @@
+require_relative 'version'
+require_relative 'error/enrichment'
+
+module QAT::Web
+  #Basic Web error class
+  #@since 1.0.0
+  class Error < StandardError
+    include Enrichment
+
+    def initialize(msg=nil)
+      super(rich_msg(msg))
+    end
+  end
+end

data/lib/qat/web/error/enrichment.rb

@@ -0,0 +1,14 @@
+require_relative '../configuration'
+# Module to handle exception enrichment.
+# Should be include in the target exception class to be enriched in runtime.
+module Enrichment
+  extend self
+
+  # Enrichs an exception message with the last configuration access in QAT::Web
+  #@param msg [String] exception message to be enriched
+  #@return [String]
+  def rich_msg(msg)
+    access = QAT::Web::Configuration.last_access
+    "#{msg}\nQAT::Web last access to configuration was '#{access}'"
+  end
+end

data/lib/qat/web/exceptions.rb

@@ -0,0 +1,15 @@
+require 'capybara'
+require 'qat/web/error'
+
+module QAT::Web
+  module Exceptions
+    GLOBAL = [
+      QAT::Web::Error,
+      Capybara::CapybaraError
+    ]
+  end
+end
+
+if defined?(Selenium)
+  QAT::Web::Exceptions::GLOBAL << Selenium::WebDriver::Error::WebDriverError
+end

data/lib/qat/web/finders.rb

@@ -0,0 +1,49 @@
+require_relative 'version'
+require_relative 'configuration'
+require 'capybara'
+
+module QAT::Web
+  #Module with custom finders based on configuration
+  #since 1.0.0
+  module Finders
+    include Configuration
+    #Alias to Capybara::Node::Finders#find method with parameter loading from configuration.
+    #An +Hash+ should be provided to calculate the correct parameters to pass to the original +find+ method.
+    #@param config [Hash] Configuration to extract parameters from
+    #@option config [String] :type Selector type (Capybara.default_selector)
+    #@option config [String] :value Selector value
+    #@see Capybara::Node::Finders#find
+    #@see Capybara::Queries::SelectorQuery
+    #@return [Capybara::Session] Current session
+    #@since 1.0.0
+    def find_from_configuration config
+      type, value, opts = parse_configuration config
+      page.find type, value, opts
+    end
+
+    #Alias to Capybara::Node::Finders#within method with parameter loading from configuration.
+    #An +Hash+ should be provided to calculate the correct parameters to pass to the original +within+ method.
+    #@param config [Hash] Configuration to extract parameters from
+    #@option config [String] :type Selector type (Capybara.default_selector)
+    #@option config [String] :value Selector value
+    #@see Capybara::Node::Finders#find
+    #@see Capybara::Queries::SelectorQuery
+    #@return [Capybara::Session] Current session
+    #@since 1.0.0
+    def within_from_configuration config, &block
+      type, value, opts = parse_configuration config
+      page.within type.to_sym, value, opts, &block
+    end
+
+    #Alias to Capybara::DSL base method
+    #@return [Capybara::Session] Current session
+    #@since 1.0.0
+    def page
+      Capybara.current_session
+    end
+  end
+end
+
+Capybara::Node::Base.include QAT::Web::Finders
+Capybara::Node::Simple.include QAT::Web::Finders
+

data/lib/qat/web/hooks/common.rb

@@ -0,0 +1,17 @@
+module QAT
+  module Web
+    module Hooks
+      module Common
+        def scenario_tag(scenario)
+          tag = QAT[:current_test_run_id] if QAT.respond_to?(:[])
+
+          tag ||= Time.now.strftime("%H%M%S%L")
+
+          "#{scenario.name.parameterize}_#{tag}"
+        end
+
+        module_function :scenario_tag
+      end
+    end
+  end
+end

data/lib/qat/web/hooks/har_exporter.rb

@@ -0,0 +1,32 @@
+After do |scenario|
+  if scenario.failed? and QAT::Web::Drivers::Firefox::HarExporter::EXCEPTIONS.include?(scenario.exception.class)
+
+    begin
+      log.info 'Saving HAR file'
+
+      Retriable.retriable(on:            Selenium::WebDriver::Error::JavascriptError,
+                          tries:         30,
+                          base_interval: 5,
+                          multiplier:    1,
+                          rand_factor:   0,
+                          on_retry:      (proc do |exception, _scenario, _duration, _try|
+                            log.warn 'Error saving HAR!'
+                            log.debug exception
+                          end)) do
+        result = Capybara.current_session.evaluate_script <<-JS
+          HAR.triggerExport({
+            token: '#{QAT::Web::Drivers::Firefox::HarExporter::TOKEN}',    // Value of the token in your preferences
+            fileName: "http_requests_%d-%m-%yT%T",    // T%T True if you want to also get HAR data as a string in the callback
+          }).then(result => {
+              // The local file is available now, result.data is null since options.getData wasn't set.
+          });
+        JS
+      end
+
+      log.info "Saved HAR file in configured folder."
+    rescue => e
+      log.error 'Could not save HAR file:'
+      log.error e
+    end
+  end
+end

data/lib/qat/web/hooks/html_dump.rb

@@ -0,0 +1,21 @@
+require_relative 'common'
+require 'qat/web/exceptions'
+
+module QAT::Web
+  module Exceptions
+    HTML_DUMP = GLOBAL.dup
+  end
+end
+
+Before do |scenario|
+  QAT::Web::Browser::HTMLDump.html_dump_path    = File.join('public', "#{QAT::Web::Hooks::Common.scenario_tag(scenario)}.html")
+end
+
+After do |scenario|
+  if scenario.failed?
+    if QAT::Web::Exceptions::HTML_DUMP.any? { |exception| scenario.exception.kind_of?(exception) }
+      # Embeds an existing HTML dump to Cucumber's HTML report
+      embed(QAT::Web::Browser::HTMLDump.take_html_dump, 'text/plain', 'HTML dump')
+    end
+  end
+end

data/lib/qat/web/hooks/screenshot.rb

@@ -0,0 +1,20 @@
+require_relative 'common'
+require 'qat/web/exceptions'
+
+module QAT::Web
+  module Exceptions
+    SCREENSHOT = GLOBAL.dup
+  end
+end
+
+Before do |scenario|
+  QAT::Web::Browser::Screenshot.screenshot_path = File.join('public', "#{QAT::Web::Hooks::Common.scenario_tag(scenario)}.png")
+end
+
+After do |scenario|
+  if scenario.failed?
+    if QAT::Web::Exceptions::SCREENSHOT.any? { |exception| scenario.exception.kind_of?(exception) }
+      embed QAT::Web::Browser::Screenshot.take_screenshot, 'image/png', 'Screenshot'
+    end
+  end
+end

data/lib/qat/web/page.rb

@@ -0,0 +1,158 @@
+require_relative 'version'
+require_relative 'elements'
+require_relative 'page/validators'
+
+module QAT::Web
+
+  #Class to represent a Web Page. Works based on a DSL to write user friendly and powerful transition models.
+  #Two class methods are provided by this class, in order to allow the mapping of getters for page values, and also map
+  #page transitions.
+  #The use of Capybara::DSL in the implementation is recommended.
+  # @example Sample Page Object implementation for http://localhost:8090/example
+  #   class ExamplePage < QAT::Web::Page
+  #     include Capybara::DSL
+  #
+  #    def initialize
+  #      visit 'http://localhost:8090/example'
+  #    end
+  #
+  #     get_value :title do
+  #       find 'h1'
+  #     end
+  #
+  #     action :more_information, returns: ExampleInformationPage do
+  #       click_link 'More information...'
+  #       ExampleInformationPage.new
+  #     end
+  #   end
+  #
+  #   current_page = ExamplePage.new
+  #   current_page.title # 'Example Domain'
+  #   current_page = current_page.more_information # ExampleInformationPage instance
+  #
+  #@see http://www.rubydoc.info/github/jnicklas/capybara/master/Capybara/DSL Capybara::DSL
+  #@abstract
+  #@since 1.0.0
+  class Page
+    include Elements
+    extend Elements
+    extend Elements::Waiters
+
+    class << self
+      include Validators
+
+      #@return [Array<Symbol>] List of value getter functions
+      def values
+        @values ||= []
+        if superclass.ancestors.include? QAT::Web::Page
+          @values + superclass.values
+        else
+          @values
+        end
+      end
+
+
+      #@return [Hash<Symbol, Array<QAT::Web::Page>>] List of page actions and respective transition return types
+      def actions
+        @actions ||= {}
+        if superclass.ancestors.include? QAT::Web::Page
+          superclass.actions.merge @actions
+        else
+          @actions
+        end
+      end
+
+      #Define a new method to get a value from a page. A new instance method will be defined with the given name
+      #parameter, and with the block as the method's code to be executed. The name of the method will be added to {QAT::Web::Page#values}
+      #@param name [String/Symbol] Name of the funcion to be defined
+      #@yield Block of code to define the getter method. The block will only be executed then the function defined by "name" is called
+      def get_value name, &block
+        name = name.to_sym
+        define_method name, &block
+        @values ||= []
+        @values << name
+      end
+
+      #Define a new method to represent a possible page transition to another page object controller. A new instance method
+      #will be defined with the given name parameter, and with the block as the method's code to be executed.
+      #Additionally, all possible return types must be delacred in the :returns key in the opts parameter.
+      #All return types must be implementarions of QAT::Web::Page.
+      #@param name [String/Symbol] Name of the funcion to be defined
+      #@param opts [Hash] Options hash
+      #@option opts [Class/Array<Class>] :returns Sublass or list of subclasses of QAT::Web::Page that can be returned by the method definition
+      #@yield Block of code to define the getter method. The block will only be executed then the function defined by "name" is called
+      #@yieldreturn [QAT::Web::Page] Instance of the destination page object
+      def action name, opts, &block
+
+        raise TypeError.new 'The opts parameter should be an Hash with a :returns key' unless opts.is_a? Hash
+
+        return_value = validate_return_value(opts[:returns])
+
+        name = name.to_sym
+        define_method name, &block
+        @actions       ||= {}
+        @actions[name] = return_value
+      end
+
+      # Loads elements configuration from a configuration file given a file path
+      # @param path [String] path to configuration file
+      # @return [HashWithIndifferentAccess]
+      def elements_file(path)
+        raise(ArgumentError, "File '#{path}' does not exist!") unless File.exist?(path)
+        @elements_file = path
+        elements_config(load_elements_file(@elements_file))
+      end
+
+      # Defines elements through a configuration hash
+      # @param elements [Hash] elements configuration
+      # @return [HashWithIndifferentAccess]
+      def elements_config(elements)
+        valid_config?(elements, 'elements')
+        @elements = HashWithIndifferentAccess.new(elements)
+      end
+
+      # Returns the elements configuration
+      # @return [HashWithIndifferentAccess]
+      def elements
+        @elements
+      end
+
+      # Defines a web element accessor identified through the given name and configuration
+      # Auxiliary methods are also dynamically defined such as the element acessor, waiters and the configuration accessor
+      # @param args [Array] One or two arguments are expected. The first argument is the element *name*
+      # and the second an optional *configuration*.
+      # If none is given, it will be automatically loaded from the loaded configuration by the element name
+      # @see Capybara::Node::Finders#find
+      def web_element(*args)
+        element = QAT::Web::Elements::Element.new(elements, *args)
+        define_web_element_methods(element)
+      end
+
+      # Defines a list of web element accessors identified through the given names
+      # Configuration will be automatically loaded from the loaded configuration by element name
+      # Auxiliary methods are also dynamically defined such as the element acessor, waiters and the configuration accessor
+      # @param elements [Array|Symbol] list of names to load elements
+      # @see Capybara::Node::Finders#find
+      def web_elements(*elements)
+        elements.each { |element| web_element(element) }
+      end
+
+      # Defines a collection of web elements identified through a given name and configuration
+      # Auxiliary methods are also dynamically defined such as the element acessor, waiters and the configuration accessor
+      # @param args [Array] One or two arguments are expected. The first argument is the element *name*
+      # and the second an optional *configuration*.
+      # If none is given, it will be automatically loaded from the loaded configuration by the element name
+      # @see Capybara::Node::Finders#all
+      def web_collection(*args)
+        collection = QAT::Web::Elements::Collection.new(elements, *args)
+        define_web_element_methods(collection)
+      end
+    end
+
+    # Returns the elements configuration
+    # @return [HashWithIndifferentAccess]
+    def elements
+      self.class.elements
+    end
+  end
+end