appom 1.4.0 → 2.0.0

data/lib/appom/element_container.rb

@@ -1,313 +1,326 @@
-module Appom
-  module ElementContainer
-    def self.included(klass)
-      klass.extend ClassMethods
-    end
+# frozen_string_literal: true
 
-    # Raise if contain a block
-    def raise_if_block(obj, name, has_block, type)
-      return unless has_block
+# Element container module for Appom automation framework
+# Provides DSL methods for defining page elements, sections, and element collections
+module Appom::ElementContainer
+  include Appom::Logging
 
-      puts "Type passed in: #{type}"
-      puts "#{obj.class}##{name} does not accept blocks"
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
 
-      raise Appom::UnsupportedBlockError
-    end
+  # Raise if contain a block
+  def raise_if_block(obj, name, has_block, type)
+    return unless has_block
 
-    ##
-    # Options re-combiner. This takes the original inputs and combines
-    # them such that there is only one hash passed as a final argument
-    # to Appium.
-    #
-    def merge_args(find_args, runtime_args={})
-      find_args = find_args.dup.flatten
-      runtime_args = runtime_args.dup
+    raise Appom::UnsupportedBlockError.new(name, "#{obj.class}##{type}")
+  end
 
-      [*find_args, *runtime_args]
-    end
+  ##
+  # Options re-combiner. This takes the original inputs and combines
+  # them such that there is only one hash passed as a final argument
+  # to Appium.
+  #
+  def merge_args(find_args, runtime_args = {})
+    find_args = find_args.dup.flatten
+    runtime_args = runtime_args.dup
 
-    module ClassMethods
-      attr_reader :mapped_items
-
-      ##
-      #
-      # Declare an element with name and args to find it
-      #
-      #     element :email, :accessibility_id, 'email_text_field'
-      #
-      # @param name             Element name
-      # @param *find_args       An array contain information to find the element. It contains locator strategy and search target
-      # http://appium.io/docs/en/commands/element/find-element/
-      #
-      # Element doesn't support block so that will raise if pass a block when declare
-      #
-      def element(name, *find_args)
-        build_element(name, *find_args) do
-          define_method(name) do |*runtime_args, &block|
-            raise_if_block(self, name, !block.nil?, :element)
-            _find(*merge_args(find_args, runtime_args))
-          end
+    [*find_args, *runtime_args]
+  end
 
-          create_get_element_params(name, find_args)
-        end
-      end
+  # Class methods for defining page elements and sections
+  module ClassMethods
+    attr_reader :mapped_items
 
-      ##
-      #
-      # Declare an elements with name and args to find it
-      #
-      #     elements :contact_cell, :accessibility_id, 'contact_cell'
-      #
-      # @param name             Element name
-      # @param *find_args       An array contain information to find the elements. It contains locator strategy and search target
-      # http://appium.io/docs/en/commands/element/find-element/
-      #
-      # Elements doesn't support block so that will raise if pass a block when declare
-      #
-      def elements(name, *find_args)
-        build_elements(name, *find_args) do
-          define_method(name) do |*runtime_args, &block|
-            raise_if_block(self, name, !block.nil?, :elements)
-            _all(*merge_args(find_args, runtime_args))
-          end
+    ##
+    #
+    # Declare an element with name and args to find it
+    #
+    #     element :email, :accessibility_id, 'email_text_field'
+    #
+    # @param name             Element name
+    # @param *find_args       An array contain information to find the element. It contains locator strategy and search target
+    # http://appium.io/docs/en/commands/element/find-element/
+    #
+    # Element doesn't support block so that will raise if pass a block when declare
+    #
+    def element(name, *find_args)
+      Appom::ElementValidation.validate_element_args(name, *find_args)
 
-          create_get_element_params(name, find_args)
+      build_element(name, *find_args) do
+        define_method(name) do |*runtime_args, &block|
+          raise_if_block(self, name, !block.nil?, :element)
+          _find(*merge_args(find_args, runtime_args))
         end
+
+        create_get_element_params(name, find_args)
       end
+    end
 
-      def section(name, *args, &block)
-        section_class, find_args = extract_section_options(args, &block)
-        build_element(name, *find_args) do
-          define_method(name) do |*runtime_args, &block|
-            section_element = _find(*merge_args(find_args, runtime_args))
-            section_class.new(self, section_element)
-          end
+    ##
+    #
+    # Declare an elements with name and args to find it
+    #
+    #     elements :contact_cell, :accessibility_id, 'contact_cell'
+    #
+    # @param name             Element name
+    # @param *find_args       An array contain information to find the elements. It contains locator strategy and search target
+    # http://appium.io/docs/en/commands/element/find-element/
+    #
+    # Elements doesn't support block so that will raise if pass a block when declare
+    #
+    def elements(name, *find_args)
+      Appom::ElementValidation.validate_element_args(name, *find_args)
 
-          create_get_element_params(name, find_args)
+      build_elements(name, *find_args) do
+        define_method(name) do |*runtime_args, &block|
+          raise_if_block(self, name, !block.nil?, :elements)
+          _all(*merge_args(find_args, runtime_args))
         end
+
+        create_get_element_params(name, find_args)
       end
+    end
 
-      def sections(name, *args, &block)
-        section_class, find_args = extract_section_options(args, &block)
-        build_sections(section_class, name, *find_args) do
-          define_method(name) do |*runtime_args, &block|
-            raise_if_block(self, name, !block.nil?, :sections)
-            _all(*merge_args(find_args, runtime_args)).map do |element|
-              section_class.new(self, element)
-            end
-          end
+    def section(name, *args, &)
+      Appom::ElementValidation.validate_section_args(name, *args)
 
-          create_get_element_params(name, find_args)
+      section_class, find_args = extract_section_options(args, &)
+      build_element(name, *find_args) do
+        define_method(name) do |*runtime_args|
+          section_element = _find(*merge_args(find_args, runtime_args))
+          section_class.new(self, section_element)
         end
-      end
 
-      ##
-      # Add item to @mapped_items array
-      #
-      # @param item         Item need to add
-      #
-      def add_to_mapped_items(item)
-        @mapped_items ||= []
-        @mapped_items << item
+        create_get_element_params(name, find_args)
       end
+    end
 
-      private
+    def sections(name, *args, &block)
+      Appom::ElementValidation.validate_section_args(name, *args)
 
-      # Add item to @mapped_items or define method for element and section
-      def build_element(name, *find_args)
-        if find_args.empty?
-          create_error_method(name)
-        else
-          add_to_mapped_items(name)
-          yield
+      section_class, find_args = extract_section_options(args, &block)
+      build_sections(section_class, name, *find_args) do
+        define_method(name) do |*runtime_args, &block|
+          raise_if_block(self, name, !block.nil?, :sections)
+          _all(*merge_args(find_args, runtime_args)).map do |element|
+            section_class.new(self, element)
+          end
         end
 
-        create_existence_checker(name, *find_args)
-        create_nonexistence_checker(name, *find_args)
-        create_enable_checker(name, *find_args)
-        create_disable_checker(name, *find_args)
+        create_get_element_params(name, find_args)
       end
+    end
 
-      # Add item to @mapped_items or define method for elements
-      def build_elements(name, *find_args)
-        if find_args.empty?
-          create_error_method(name)
-        else
-          add_to_mapped_items(name)
-          yield
-        end
+    ##
+    # Add item to @mapped_items array
+    #
+    # @param item         Item need to add
+    #
+    def add_to_mapped_items(item)
+      @mapped_items ||= []
+      @mapped_items << item
+    end
 
-        create_existence_checker(name, *find_args)
-        create_nonexistence_checker(name, *find_args)
-        create_get_all_elements(name, *find_args)
+    private
+
+    # Add item to @mapped_items or define method for element and section
+    def build_element(name, *find_args)
+      if find_args.empty?
+        create_error_method(name)
+      else
+        add_to_mapped_items(name)
+        yield
       end
 
-      # Add item to @mapped_items or define method for elements
-      def build_sections(section_class, name, *find_args)
-        if find_args.empty?
-          create_error_method(name)
-        else
-          add_to_mapped_items(name)
-          yield
-        end
+      create_existence_checker(name, *find_args)
+      create_nonexistence_checker(name, *find_args)
+      create_enable_checker(name, *find_args)
+      create_disable_checker(name, *find_args)
+    end
 
-        create_existence_checker(name, *find_args)
-        create_nonexistence_checker(name, *find_args)
-        create_get_all_sections(section_class, name, *find_args)
+    # Add item to @mapped_items or define method for elements
+    def build_elements(name, *find_args)
+      if find_args.empty?
+        create_error_method(name)
+      else
+        add_to_mapped_items(name)
+        yield
       end
 
-      # Define method to notify that we can't find item without args
-      def create_error_method(name)
-        define_method(name) do
-          raise Appom::InvalidElementError
-        end
+      create_existence_checker(name, *find_args)
+      create_nonexistence_checker(name, *find_args)
+      create_get_all_elements(name, *find_args)
+    end
+
+    # Add item to @mapped_items or define method for elements
+    def build_sections(section_class, name, *find_args)
+      if find_args.empty?
+        create_error_method(name)
+      else
+        add_to_mapped_items(name)
+        yield
       end
 
-      def create_helper_method(proposed_method_name, *find_args)
-        if find_args.empty?
-          create_error_method(proposed_method_name)
-        else
-          yield
-        end
+      create_existence_checker(name, *find_args)
+      create_nonexistence_checker(name, *find_args)
+      create_get_all_sections(section_class, name, *find_args)
+    end
+
+    # Define method to notify that we can't find item without args
+    def create_error_method(name)
+      define_method(name) do
+        raise Appom::InvalidElementError, name
       end
+    end
 
-      ##
-      # Try to get all elements until not get empty array
-      #
-      def create_get_all_elements(element_name, *find_args)
-        method_name = "get_all_#{element_name}"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            wait_until_get_not_empty(*args)
-          end
-        end
+    def create_helper_method(proposed_method_name, *find_args)
+      if find_args.empty?
+        create_error_method(proposed_method_name)
+      else
+        yield
       end
+    end
 
-      ##
-      # Try to get all sections until not get empty array
-      #
-      def create_get_all_sections(section_class, element_name, *find_args)
-        method_name = "get_all_#{element_name}"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            wait_until_get_not_empty(*args).map do |element|
-              section_class.new(self, element)
-            end
-          end
+    ##
+    # Try to get all elements until not get empty array
+    #
+    def create_get_all_elements(element_name, *find_args)
+      method_name = "get_all_#{element_name}"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do |*runtime_args|
+          args = merge_args(find_args, runtime_args)
+          wait_until_get_not_empty(*args)
         end
       end
+    end
 
-      ##
-      # Check element exist
-      # We will try to find all elements with *find_args
-      # Condition is pass when response is not empty
-      #
-      def create_existence_checker(element_name, *find_args)
-        method_name = "has_#{element_name}"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            wait_until('at least one element exists', *args)
+    ##
+    # Try to get all sections until not get empty array
+    #
+    def create_get_all_sections(section_class, element_name, *find_args)
+      method_name = "get_all_#{element_name}"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do |*runtime_args|
+          args = merge_args(find_args, runtime_args)
+          wait_until_get_not_empty(*args).map do |element|
+            section_class.new(self, element)
           end
         end
       end
+    end
 
-      ##
-      # Check element non-existent
-      # We will try to find all elements with *find_args
-      # Condition is pass when response is empty
-      #
-      def create_nonexistence_checker(element_name, *find_args)
-        method_name = "has_no_#{element_name}"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            wait_until('no element exists', *args)
-          end
+    ##
+    # Check element exist
+    # We will try to find all elements with *find_args
+    # Condition is pass when response is not empty
+    #
+    def create_existence_checker(element_name, *find_args)
+      method_name = "has_#{element_name}"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do |*runtime_args|
+          args = merge_args(find_args, runtime_args)
+          wait_until('at least one element exists', *args)
         end
       end
+    end
 
-      ##
-      # Wait until element will be enable
-      #
-      def create_enable_checker(element_name, *find_args)
-        method_name = "#{element_name}_enable"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            wait_until('element enable', *args)
-          end
+    ##
+    # Check element non-existent
+    # We will try to find all elements with *find_args
+    # Condition is pass when response is empty
+    #
+    def create_nonexistence_checker(element_name, *find_args)
+      method_name = "has_no_#{element_name}"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do |*runtime_args|
+          args = merge_args(find_args, runtime_args)
+          wait_until('no element exists', *args)
         end
       end
+    end
 
-      ##
-      # Wait until an element will be disable
-      #
-      def create_disable_checker(element_name, *find_args)
-        method_name = "#{element_name}_disable"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do |*runtime_args|
-            args = merge_args(find_args, runtime_args)
-            wait_until('element disable', *args)
-          end
+    ##
+    # Wait until element will be enable
+    #
+    def create_enable_checker(element_name, *find_args)
+      method_name = "#{element_name}_enable"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do |*runtime_args|
+          args = merge_args(find_args, runtime_args)
+          wait_until('element enable', *args)
         end
       end
+    end
 
-      ##
-      # Get parameter is passed when declared element
-      #
-      def create_get_element_params(element_name, *find_args)
-        method_name = "#{element_name}_params"
-        create_helper_method(method_name, *find_args) do
-          define_method(method_name) do
-            merge_args(find_args)
-          end
+    ##
+    # Wait until an element will be disable
+    #
+    def create_disable_checker(element_name, *find_args)
+      method_name = "#{element_name}_disable"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do |*runtime_args|
+          args = merge_args(find_args, runtime_args)
+          wait_until('element disable', *args)
         end
       end
+    end
 
-      ##
-      # Extract section options
-      # @return section class name and the remaining parameters
-      #
-      def extract_section_options(args, &block)
-        if args.first.is_a?(Class)
-          klass = args.shift
-          section_class = klass if klass.ancestors.include?(Appom::Section)
+    ##
+    # Get parameter is passed when declared element
+    #
+    def create_get_element_params(element_name, *find_args)
+      method_name = "#{element_name}_params"
+      create_helper_method(method_name, *find_args) do
+        define_method(method_name) do
+          merge_args(find_args)
         end
+      end
+    end
 
-        section_class = deduce_section_class(section_class, &block)
-        arguments = deduce_search_arguments(section_class, args)
-        [section_class, arguments]
+    ##
+    # Extract section options
+    # @return section class name and the remaining parameters
+    #
+    def extract_section_options(args, &)
+      if args.first.is_a?(Class)
+        klass = args.shift
+        section_class = klass if klass.ancestors.include?(Appom::Section)
       end
 
-      ##
-      # Deduce section class
-      #
-      def deduce_section_class(base_class, &block)
-        klass = base_class
+      section_class = deduce_section_class(section_class, &)
+      arguments = deduce_search_arguments(section_class, args)
+      [section_class, arguments]
+    end
 
-        klass = Class.new(klass || Appom::Section, &block) if block_given?
+    ##
+    # Deduce section class
+    #
+    def deduce_section_class(base_class, &)
+      klass = base_class
 
-        unless klass
-          raise ArgumentError, 'You should provide descendant of Appom::Section class or/and a block as the second argument.'
-        end
-        klass
-      end
+      klass = Class.new(klass || Appom::Section, &) if block_given?
 
-      ##
-      # Deduce search parameters
-      #
-      def deduce_search_arguments(section_class, args)
-        extract_search_arguments(args) ||
-          extract_search_arguments(section_class.default_search_arguments) ||
-          raise(ArgumentError, 'You should provide search arguments in section creation or set_default_search_arguments within section class')
+      unless klass
+        raise Appom::InvalidSectionError,
+              'You should provide descendant of Appom::Section class or/and a block as the second argument.'
       end
 
-      def extract_search_arguments(args)
-        args if args && !args.empty?
-      end
+      klass
+    end
+
+    ##
+    # Deduce search parameters
+    #
+    def deduce_search_arguments(section_class, args)
+      extract_search_arguments(args) ||
+        extract_search_arguments(section_class.respond_to?(:default_search_arguments) ? section_class.default_search_arguments : nil) ||
+        raise(Appom::InvalidSectionError,
+              'You should provide search arguments in section creation or set_default_search_arguments within section class',)
+    end
+
+    def extract_search_arguments(args)
+      args if args && !args.empty?
     end
   end
 end