testa_appium_driver 0.1.1 → 0.1.5

data/lib/testa_appium_driver/common/scroll_actions/w3c_scroll_actions.rb

@@ -3,7 +3,7 @@ module TestaAppiumDriver
 
     private
     # @return [Array]
-    def w3c_each(skip_scroll_to_start, &block)
+    def w3c_each(direction, &block)
       elements = []
       begin
         @driver.disable_wait_for_idle
@@ -13,7 +13,14 @@ module TestaAppiumDriver
         iterations = 0
 
 
-        scroll_to_start unless skip_scroll_to_start
+        if direction.nil?
+          scroll_to_start
+          if @scrollable.scroll_orientation == :vertical
+            direction = :down
+          else
+            direction = :right
+          end
+        end
 
         until is_end_of_scroll?
           matches = @locator.execute(skip_cache: true)
@@ -27,6 +34,7 @@ module TestaAppiumDriver
           end
           iterations += 1
           break if !@max_scrolls.nil? && iterations == @max_scrolls
+          self.send("page_#{direction}")
         end
       rescue => e
         raise e
@@ -37,13 +45,13 @@ module TestaAppiumDriver
       elements
     end
 
-    def w3c_align(with)
+    def w3c_align(with, scroll_to_find)
       @driver.disable_wait_for_idle
       default_deadzone!
 
 
 
-      @locator.scroll_to unless @raise # called with !
+      @locator.scroll_to if scroll_to_find
 
       element = @locator.execute
       @driver.disable_implicit_wait

data/lib/testa_appium_driver/common/scroll_actions.rb

@@ -3,19 +3,24 @@ require_relative 'scroll_actions/w3c_scroll_actions'
 
 
 module TestaAppiumDriver
-  #noinspection RubyResolve,RubyTooManyInstanceVariablesInspection
-  class ScrollActions
 
+  # Class for handling scroll actions
+  class ScrollActions
+    # @param [TestaAppiumDriver::Locator, nil] scrollable container that will be used to determine the bounds for scrolling
+    # @param [Hash] params
+    #   acceptable params
+    #     - locator - element that should be found with scrolling actions
+    #     - deadzone - [Hash] that stores top, bottom, left and right deadzone values. If deadzone[:top] is 200 then 200px from top of the scrollable container will not be used for scrolling
+    #     - max_scrolls - [Integer] maximum number of scrolls before exception is thrown
+    #     - default_scroll_strategy - defines which scroll strategy will be used if a scroll action is valid for multiple strategies
     def initialize(scrollable, params = {})
       @scrollable = scrollable
       @locator = params[:locator]
       @deadzone = params[:deadzone]
-      @direction = params[:direction]
       @max_scrolls = params[:max_scrolls]
       @default_scroll_strategy = params[:default_scroll_strategy]
       @driver = @locator.driver
 
-      @raise = params[:raise]
 
       if @scrollable.nil?
         # if we dont have a scrollable element or if we do have it, but it is not compatible with uiautomator
@@ -35,16 +40,33 @@ module TestaAppiumDriver
     end
 
 
-    def align(with)
-      w3c_align(with)
+    def align(with, scroll_to_find)
+      w3c_align(with, scroll_to_find)
       @locator
     end
 
     # @return [Array]
-    def each(skip_scroll_to_start, &block)
-      w3c_each(skip_scroll_to_start, &block)
+    def each(&block)
+      w3c_each(nil, &block)
+    end
+
+    def each_down(&block)
+      w3c_each(:down, &block)
+    end
+
+    def each_up(&block)
+      w3c_each(:up, &block)
     end
 
+    def each_right(&block)
+      w3c_each(:right, &block)
+    end
+
+    def each_left(&block)
+      w3c_each(:left, &block)
+    end
+
+
     def resolve_strategy
       if @strategy.nil?
         @default_scroll_strategy

data/lib/testa_appium_driver/common/selenium_element.rb

@@ -1,19 +1,19 @@
 module Selenium
   module WebDriver
-    #noinspection RubyClassVariableUsageInspection
     class Element
+      # sets the testa appium driver instance for the current phone
       def self.set_driver(driver, udid)
         udid = "unknown" if udid.nil?
         @@drivers ||= {}
         @@drivers[udid] = driver
       end
 
+      # @return [TestaAppiumDriver::Driver] testa appium driver instance for the current phone
       def get_driver
         udid = @bridge.capabilities.instance_variable_get(:@capabilities)["udid"]
         udid = "unknown" if udid.nil?
         @@drivers[udid]
       end
-
     end
   end
 end

data/lib/testa_appium_driver/driver.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'em/pure_ruby'
+require 'appium_lib_core'
+
 require_relative 'common/bounds'
 require_relative 'common/exceptions/strategy_mix_exception'
 require_relative 'common/helpers'
@@ -10,18 +13,24 @@ require_relative 'common/selenium_element'
 module TestaAppiumDriver
   class Driver
     include Helpers
+
+    # @return [::Appium::Core::Base::Driver] the ruby_lib_core appium driver
     attr_accessor :driver
+
+    # @return [String] iOS or Android
     attr_reader :device
+
+    # @return [String] driver automation name (uiautomator2 or xcuitest)
     attr_reader :automation_name
 
     # custom options
-    # - default_strategy: default strategy to be used for finding elements. Available strategies :uiautomator or :xpath
+    # - default_find_strategy: default strategy to be used for finding elements. Available strategies :uiautomator or :xpath
+    # - default_scroll_strategy: default strategy to be used for scrolling. Available strategies: :uiautomator(android only), :w3c
     def initialize(opts = {})
       @testa_opts = opts[:testa_appium_driver] || {}
 
 
-
-      core = ::Appium::Core.for(opts)
+      core = Appium::Core.for(opts)
       extend_for(core.device, core.automation_name)
       @device = core.device
       @automation_name = core.automation_name
@@ -29,14 +38,15 @@ module TestaAppiumDriver
       handle_testa_opts
 
       @driver = core.start_driver
-      invalidate_cache!
+      invalidate_cache
 
 
-      ::Selenium::WebDriver::Element.set_driver(self, opts[:caps][:udid])
+      Selenium::WebDriver::Element.set_driver(self, opts[:caps][:udid])
     end
 
 
-    def invalidate_cache!
+    # invalidates current find_element cache
+    def invalidate_cache
       @cache = {
           strategy: nil,
           selector: nil,
@@ -49,11 +59,13 @@ module TestaAppiumDriver
 
 
 
-    #noinspection RubyScope
+    # Executes the find_element with the resolved locator strategy and selector. Find_element might be skipped if cache is hit.
+    # Cache stores last executed find_element with given selector, strategy and from_element. If given values are the same within
+    # last 5 seconds element is retrieved from cache.
     # @param [TestaAppiumDriver::Locator, TestaAppiumDriver::Driver] from_element element from which start the search
-    # @param [String] selector resolved string of a [TestaAppiumDriver::Locator] selector xpath for xpath strategy, java UiSelectors for uiautomator
+    # @param [String] selector resolved string of a [TestaAppiumDriver::Locator] selector xpath for xpath strategy, java UiSelectors for uiautomator or id for ID strategy
     # @param [Boolean] single fetch single or multiple results
-    # @param [Symbol, nil] strategy [TestaAppiumDriver:FIND_STRATEGY_UIAUTOMATOR] or [FIND_STRATEGY_XPATH]
+    # @param [Symbol, nil] strategy [TestaAppiumDriver::FIND_STRATEGY_UIAUTOMATOR], [TestaAppiumDriver::FIND_STRATEGY_XPATH] or [TestaAppiumDriver::FIND_STRATEGY_ID]
     # @param [Symbol] default_strategy if strategy is not enforced, default can be used
     # @param [Boolean] skip_cache to skip checking and storing cache
     # @return [Selenium::WebDriver::Element, Array] element is returned if single is true, array otherwise
@@ -107,21 +119,27 @@ module TestaAppiumDriver
 
 
     # method missing is used to forward methods to the actual appium driver
+    # after the method is executed, find element cache is invalidated
     def method_missing(method, *args, &block)
-      @driver.send(method, *args, &block)
+      r = @driver.send(method, *args, &block)
+      invalidate_cache
+      r
     end
 
+    # disables implicit wait
     def disable_implicit_wait
       @implicit_wait_ms = @driver.get_timeouts["implicit"]
       @driver.manage.timeouts.implicit_wait = 0
     end
 
+    # enables implicit wait, can be called only after disabling implicit wait
     def enable_implicit_wait
       raise "Implicit wait is not disabled" if @implicit_wait_ms.nil?
       # get_timeouts always returns in milliseconds, but we should set in seconds
       @driver.manage.timeouts.implicit_wait = @implicit_wait_ms / 1000
     end
 
+    # disables wait for idle, only executed for android devices
     def disable_wait_for_idle
       if @device == :android
         @wait_for_idle_timeout = @driver.settings.get["waitForIdleTimeout"]
@@ -129,6 +147,7 @@ module TestaAppiumDriver
       end
     end
 
+    # enables wait for idle, only executed for android devices
     def enable_wait_for_idle
       if @device == :android
         raise "Wait for idle is not disabled" if @wait_for_idle_timeout.nil?
@@ -136,12 +155,15 @@ module TestaAppiumDriver
       end
     end
 
+
+    # @@return [String] current package under test
     def current_package
       @driver.current_package
     end
 
-    def window_size(*args)
-      @driver.window_size(*args)
+
+    def window_size
+      @driver.window_size
     end
 
     def back
@@ -166,6 +188,7 @@ module TestaAppiumDriver
     end
 
 
+    # @return [Array<Selenium::WebDriver::Element] array of 2 elements, the first element without children and the last element without children in the current page
     def first_and_last_leaf(from_element = @driver)
       disable_wait_for_idle
       disable_implicit_wait

data/lib/testa_appium_driver/ios/driver.rb

@@ -7,6 +7,7 @@ module TestaAppiumDriver
     include TypeSelectors
 
 
+    private
     def handle_testa_opts
       if @testa_opts[:default_find_strategy].nil?
         @default_find_strategy = DEFAULT_IOS_FIND_STRATEGY

data/lib/testa_appium_driver/ios/locator/attributes.rb

@@ -1,7 +1,5 @@
 module TestaAppiumDriver
-  #noinspection RubyYardReturnMatch
-  class Locator
-
+  module Attributes
 
     #noinspection RubyNilAnalysis
     def attribute(name, *args)
@@ -76,4 +74,8 @@ module TestaAppiumDriver
     alias_method :bounds, :rect
     alias_method :text, :label
   end
+  #noinspection RubyYardReturnMatch
+  class Locator
+    include TestaAppiumDriver::Attributes
+  end
 end

data/lib/testa_appium_driver/ios/locator.rb

@@ -1,7 +1,6 @@
 require_relative 'locator/attributes'
 
 module TestaAppiumDriver
-  #noinspection RubyTooManyInstanceVariablesInspection
   class Locator
     include TypeSelectors
 
@@ -24,6 +23,7 @@ module TestaAppiumDriver
     end
 
 
+    # @return [Array] returns 2 elements. The first is the resolved find element strategy and the second is the resolved selector
     def strategy_and_selector
       if @can_use_id_strategy
         return FIND_STRATEGY_NAME, @can_use_id_strategy
@@ -32,7 +32,8 @@ module TestaAppiumDriver
     end
 
 
-    # @return [Locator] existing locator element
+
+    # @return [Locator] new child locator element
     def add_child_selector(params)
       params, selectors = extract_selectors_from_params(params)
       single = params[:single]

data/lib/testa_appium_driver/version.rb

@@ -1,5 +1,5 @@
-# frozen_string_literal: true
-
-module TestaAppiumDriver
-  VERSION = "0.1.1"
-end
+# frozen_string_literal: true
+
+module TestaAppiumDriver
+  VERSION = "0.1.5"
+end

data/testa_appium_driver.gemspec

@@ -9,13 +9,14 @@ Gem::Specification.new do |spec|
   spec.email = ["karlo.razumovic@gmail.com"]
 
   spec.summary = "Appium made easy"
-  spec.description = "Testa appium driver is a wrapper around ruby_lib_core. It significantly reduces the amount of code need to achieve your goals."
+  spec.description = "Testa appium driver is a wrapper around ruby_lib_core. It leverages all driver features and makes them simple and easy to use, significantly reduces the amount of code needed and enables you to define locators that can be reused"
   spec.homepage = "https://github.com/Karazum/testa_appium_driver"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.4.0"
 
   #spec.metadata["allowed_push_host"] = "Set to 'https://mygemserver.com'"
 
+  spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/testa_appium_driver"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/Karazum/testa_appium_driver"
   spec.metadata["changelog_uri"] = "https://github.com/Karazum/testa_appium_driver"
@@ -30,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "appium_lib_core", ["= 4.7.0"]
-  spec.add_runtime_dependency "json", [">= 2.3.0"]
+  spec.add_runtime_dependency "json", ["~> 2.3"]
 
   spec.add_development_dependency "rubocop", ["= 1.19.0"]
   spec.add_development_dependency "rake", ["~> 13.0"]

data/testa_appium_driver.iml

@@ -11,7 +11,7 @@
     <orderEntry type="sourceFolder" forTests="false" />
     <orderEntry type="library" scope="PROVIDED" name="appium_lib_core (v4.7.0, ruby-2.6.5-p114) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ast (v2.4.2, ruby-2.6.5-p114) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="bundler (v2.2.25, ruby-2.6.5-p114) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v2.1.4, ruby-2.6.5-p114) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="childprocess (v3.0.0, ruby-2.6.5-p114) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.4.4, ruby-2.6.5-p114) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="eventmachine (v1.2.7, ruby-2.6.5-p114) [gem]" level="application" />

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: testa_appium_driver
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.5
 platform: ruby
 authors:
 - karlo.razumovic
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-19 00:00:00.000000000 Z
+date: 2021-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appium_lib_core
@@ -28,16 +28,16 @@ dependencies:
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -66,8 +66,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Testa appium driver is a wrapper around ruby_lib_core. It significantly
-  reduces the amount of code need to achieve your goals.
+description: Testa appium driver is a wrapper around ruby_lib_core. It leverages all
+  driver features and makes them simple and easy to use, significantly reduces the
+  amount of code needed and enables you to define locators that can be reused
 email:
 - karlo.razumovic@gmail.com
 executables: []
@@ -123,6 +124,7 @@ homepage: https://github.com/Karazum/testa_appium_driver
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://www.rubydoc.info/gems/testa_appium_driver
   homepage_uri: https://github.com/Karazum/testa_appium_driver
   source_code_uri: https://github.com/Karazum/testa_appium_driver
   changelog_uri: https://github.com/Karazum/testa_appium_driver