locatine 0.02878 → 0.03050

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 457cb5d21eae999673da17f8c5c200181755f846946e81c81d9a23bbafa85528
-  data.tar.gz: f3ae98ffc268889f4781126b71106ffc99c29c73f9cd4e8321743388fb56bf70
+  metadata.gz: 6ec7ffd6c0a45544ae5cbd20581f72190bbfa3ee5dd2c5e444740c1d03d7ba04
+  data.tar.gz: 7552e77cfc41106c4679a99554980f67ad4decc354348ee0d01479c9799687fa
 SHA512:
-  metadata.gz: ed6f3ad8a5e29ea3b3e672b5a5cbd006571fa9536821dbc0b1467b005cf0998efc19425ba17f166a608cf84b5a884908c1d718275dbbebd0a56372a85f10d988
-  data.tar.gz: a7e5b86fe05b8710fd5bbd675733937dab017f8c27d8e27e4dbd5865da9313211775877c931a56c36414e0f1a3d94d3c66365a511f543daad4022fb00be91b14
+  metadata.gz: 6d42ad78b43ff2335357546b50daa98734e1d06527e26fc6608540135ffb73d4f1aebcf9b5e3fb44c74b3125a31045b3206a8ddabdc0c08211f28f71390fdc9f
+  data.tar.gz: 2b752ff4e3a7b60ae8eb12f585eef9df6445f3c659169e7470bcfbc18f848938762815a8a977ce4825be250f527a425b0c2ff1b96d52240db4223e9d1d8a201e

data/README.md

@@ -14,7 +14,7 @@ That's it.
 
 ## Stage of development:
 
-Version of Locatine is **0.02878**. The 4th version since rewriting. 5-15 next versions is dedicated to bug fixing, tweaking.
+Version of Locatine is **0.03050**. The 4th version since rewriting. 5-15 next versions is dedicated to bug fixing, tweaking.
 
 ## Attention
 

data/lib/locatine.rb

@@ -6,6 +6,8 @@ require 'locatine/results_helpers/find_by_magic'
 require 'locatine/results_helpers/guess'
 require 'locatine/results_helpers/info_generator'
 require 'locatine/results_helpers/xpath_generator'
+require 'locatine/results_helpers/comparing'
+require 'locatine/results_helpers/config'
 
 require 'locatine/logger'
 require 'locatine/version'

data/lib/locatine/daemon.rb

@@ -4,7 +4,7 @@ require 'sinatra/base'
 require 'json'
 
 module Locatine
-  #
+  ##
   # Locatine daemon based on sinatra
   #
   # run Locatine::Daemon.run!
@@ -34,12 +34,6 @@ module Locatine
       { result: result }.to_json
     end
 
-    def send_error(error)
-      status error.status
-
-      error.answer
-    end
-
     # selenium calls
     post '/wd/hub/session/*/element' do
       content_type settings.headers['Content-Type']

data/lib/locatine/daemon_helpers/methods.rb

@@ -7,6 +7,8 @@ module Locatine
     #
     # Methods that are used by daemon
     module Methods
+      private
+
       def api_request(type, path, query_string, body, new_headers)
         uri = make_uri(path, query_string)
         req = Net::HTTP.const_get(type).new(uri,
@@ -80,6 +82,12 @@ module Locatine
         path_array = request.path_info.split('/')
         path_array.size >= 7 ? path_array[6] : nil
       end
+
+      def send_error(error)
+        status error.status
+
+        error.answer
+      end
     end
   end
 end

data/lib/locatine/element.rb

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
 module Locatine
-  #
+  ##
   # Locatine single element
+  #
+  # It is used to store element info and to return parent.
+  # I am thinking about moving staleness check here.
   class Element
     attr_accessor :answer
 
+    ##
+    # Init method
+    #
+    # +session+ is a Locatine::Session instance
+    # +element_code+ is an element hash returned by selenium it is shaped like:
+    # {"element-6066-11e4-a52e-4f735466cecf"=>"c95a0580-4ac7-4c6d-..."}
     def initialize(session, element_code)
       unless element_code
         raise ArgumentError, 'Cannot init element with no element data'
@@ -15,12 +24,17 @@ module Locatine
       @answer = element_code
     end
 
+    ##
+    # Returning a parent element
     def parent
       parent = File.read("#{HOME}/scripts/parent.js")
       new_answer = @session.execute_script(parent, self)
       new_answer.nil? ? nil : Locatine::Element.new(@session, new_answer)
     end
 
+    ##
+    # Method to get the info about particular element or return it if it was
+    # gathered before
     def info
       return @info if @info
 

data/lib/locatine/error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Locatine
-  #
+  ##
   # Simple error
   class Error
     attr_accessor :answer, :status

data/lib/locatine/logger.rb

@@ -3,9 +3,13 @@
 require 'colorize'
 
 module Locatine
-  #
+  ##
   # Methods for sending lines to STDOUT
+  #
+  # Some of methods are specific and should be run in a correct class only!
   module Logger
+    private
+
     def warn(text)
       puts "WARNING: #{Time.now}: ".yellow + text
     end
@@ -20,7 +24,7 @@ module Locatine
 
     def warn_locator
       warn("Locator is broken. For #{name} by"\
-           " #{@locator['using']}>>>'#{locator['value']}'")
+           " #{@locator['using']}>>>'#{@locator['value']}'")
     end
 
     def warn_guess

data/lib/locatine/results.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 module Locatine
+  ##
+  # Locatine results container.
   #
-  # Locatine results container
+  # Results is a pretty strange concept. It is an array of returned elements
+  # which is extended by methods of finding and gathering elements.
   class Results < Array
     include Locatine::ResultsHelpers::InfoGenerator
     include Locatine::ResultsHelpers::XpathGenerator
@@ -10,16 +13,49 @@ module Locatine
     include Locatine::ResultsHelpers::Common
     include Locatine::Logger
     include Locatine::ResultsHelpers::Guess
+    include Locatine::ResultsHelpers::Comparing
+    include Locatine::ResultsHelpers::Config
+
+    attr_accessor :name
+
+    ##
+    # Method to find elements
+    #
+    # +session+ instance of Locatine::Session
+    # +locator+ can be a classic locator shaped for webdriver protocol like:
+    # {'using => 'xpath', 'value' => '//div'} or
+    # {'using' => 'css selector', 'value' => 'div'}
+    # It also can be a locator with magic comment like
+    # {'using' => 'css selector', 'value' => 'div/*magic comment*/'}
+    # It also can be a locator with incapsulated json
+    # {'using' => 'css selector', 'value' => 'div/*{"name": "magic comment"}*/'}
+    # It can be a locatine locator
+    # {'using' => 'locatine', 'value' => '{"name": "magic comment"}'} or
+    # {'using' => 'locatine', 'value' => 'magic comment'
+    # +parent+ is the parent element to look for the nested ones.
+    def find(session, locator, parent)
+      configure(session, locator, parent)
+      timer
+      classic_find
+      guess if name_only?
+      return self unless empty?
 
-    attr_accessor :name, :config, :locator
+      find_by_magic if known && tolerance.positive?
+      similar? ? found : not_found
+    end
 
-    def configure(session, locator, parent)
-      @session = session
-      @locator = locator.clone
-      read_locator
-      @parent = parent
+    ##
+    # Method to return information about elements found
+    #
+    # Information is returned combined with the previously known data and can
+    # be stored and used as is. It means that its returning not the data about
+    # one particular search. But the combined data of all previous searches
+    def info
+      stability_bump(raw_info)
     end
 
+    private
+
     def simple_find
       path = @parent ? "/element/#{@parent}/elements" : '/elements'
       response = @session.api_request(path, 'Post', @locator.to_json)
@@ -75,16 +111,6 @@ module Locatine
       find_by_data(base) if empty? && !trusted.empty? && !base['0'].empty?
     end
 
-    def find
-      timer
-      classic_find
-      guess if name_only?
-      return self unless empty?
-
-      find_by_magic if known && tolerance.positive?
-      similar? ? found : not_found
-    end
-
     def found
       log_found
       uniq
@@ -94,35 +120,5 @@ module Locatine
       warn_lost
       []
     end
-
-    def read_locator
-      case @locator['using']
-      when 'css selector'
-        # "button/*{json}*/"
-        read_locator_routine(%r{/\*(.*)\*/$})
-      when 'xpath'
-        # "//button['{json}']"
-        read_locator_routine(/\[\'(.*)\'\]$/)
-      when 'locatine'
-        read_locator_routine(/(.*)/)
-      end
-    end
-
-    def read_locator_routine(regexp)
-      matched = @locator['value'].match(regexp)
-      @config = matched ? config_provided(matched[1]) : {}
-      @locator['value'] = @locator['value'].gsub(matched[0], '') if matched
-      @locator = @config['locator'] if @config['locator']
-      @name = @config['name'] || @locator['value']
-    end
-
-    def config_provided(config)
-      JSON.parse(config)
-    rescue StandardError
-      result = {}
-      result['tolerance'] = 0 if config.start_with?('exactly')
-      result['name'] = config.gsub('exactly ', '')
-      result
-    end
   end
 end

data/lib/locatine/results_helpers/common.rb

@@ -2,9 +2,11 @@
 
 module Locatine
   module ResultsHelpers
-    #
+    ##
     # Some common methods without much logic
     module Common
+      private
+
       def timer
         @time ||= Time.now
         timeout > Time.now - @time
@@ -27,15 +29,6 @@ module Locatine
         (item['name'] == hash['name']) && (item['type'] == hash['type'])
       end
 
-      def info_hash_eq(item, hash)
-        # Return true
-        # If type is unknown (but not a text)
-        # Or when type and name are similar
-        (unknown_no_text(item, hash) || same_name_type(item, hash)) &&
-          # And at the same time values are (almost) the same
-          (item['value'].downcase == hash['value'].downcase)
-      end
-
       def stability
         @config['stability'] || @session.stability
       end

data/lib/locatine/results_helpers/comparing.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Locatine
+  module ResultsHelpers
+    #
+    # Trying to guess element here
+    module Comparing
+      private
+
+      def count_similarity
+        all = 0
+        same = 0
+        # Next is necessary for unknown reason (smthing thread related)
+        raw = raw_info['0']
+        get_trusted(known['0']).each do |hash|
+          caught = (raw.select { |item| info_hash_eq(item, hash) }).first
+          all += 1
+          same += 1 if caught
+        end
+        similar_enough(same, all)
+      end
+
+      def similar?
+        return false if empty?
+
+        return true if tolerance == 100
+
+        count_similarity
+      rescue RuntimeError => e
+        raise e.message unless e.message == 'stale element reference'
+
+        warn_unstable_page
+        false
+      end
+
+      def similar_enough(same, all)
+        sameness = (same * 100) / all
+        sameness >= 100 - tolerance
+      end
+
+      def info_hash_eq(item, hash)
+        # Return true
+        # If type is unknown (but not a text)
+        # Or when type and name are similar
+        (unknown_no_text(item, hash) || same_name_type(item, hash)) &&
+          # And at the same time values are (almost) the same
+          (item['value'].downcase == hash['value'].downcase)
+      end
+    end
+  end
+end

data/lib/locatine/results_helpers/config.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Locatine
+  module ResultsHelpers
+    #
+    # Trying to guess element here
+    module Config
+      private
+
+      def configure(session, locator, parent)
+        @session = session
+        @locator = locator.clone
+        read_locator
+        @parent = parent
+      end
+
+      def read_locator
+        case @locator['using']
+        when 'css selector'
+          # "button/*{json}*/"
+          read_locator_routine(%r{/\*(.*)\*/$})
+        when 'xpath'
+          # "//button['{json}']"
+          read_locator_routine(/\[\'(.*)\'\]$/)
+        when 'locatine'
+          read_locator_routine(/(.*)/)
+        end
+      end
+
+      def read_locator_routine(regexp)
+        matched = @locator['value'].match(regexp)
+        @config = matched ? config_provided(matched[1]) : {}
+        @locator['value'] = @locator['value'].gsub(matched[0], '') if matched
+        @locator = @config['locator'] if @config['locator']
+        @name = @config['name'] || @locator['value']
+      end
+
+      def config_provided(config)
+        JSON.parse(config)
+      rescue StandardError
+        result = {}
+        result['tolerance'] = 0 if config.start_with?('exactly')
+        result['name'] = config.gsub('exactly ', '')
+        result
+      end
+    end
+  end
+end

data/lib/locatine/results_helpers/find_by_magic.rb

@@ -2,9 +2,11 @@
 
 module Locatine
   module ResultsHelpers
-    #
+    ##
     # Methods for active looking for element
     module FindByMagic
+      private
+
       def magic_thread
         Thread.new do
           while empty?

data/lib/locatine/results_helpers/guess.rb

@@ -2,9 +2,11 @@
 
 module Locatine
   module ResultsHelpers
-    #
+    ##
     # Trying to guess element here
     module Guess
+      private
+
       def guess
         warn_guess
         @config['tolerance'] = 100
@@ -40,37 +42,6 @@ module Locatine
         end
         answer
       end
-
-      def count_similarity
-        all = 0
-        same = 0
-        # Next is necessary for unknown reason (smthing thread related)
-        raw = raw_info['0']
-        get_trusted(known['0']).each do |hash|
-          caught = (raw.select { |item| info_hash_eq(item, hash) }).first
-          all += 1
-          same += 1 if caught
-        end
-        similar_enough(same, all)
-      end
-
-      def similar?
-        return false if empty?
-
-        return true if tolerance == 100
-
-        count_similarity
-      rescue RuntimeError => e
-        raise e.message unless e.message == 'stale element reference'
-
-        warn_unstable_page
-        false
-      end
-
-      def similar_enough(same, all)
-        sameness = (same * 100) / all
-        sameness >= 100 - tolerance
-      end
     end
   end
 end

data/lib/locatine/results_helpers/info_generator.rb

@@ -2,12 +2,10 @@
 
 module Locatine
   module ResultsHelpers
-    #
+    ##
     # Methods for gathering element info
     module InfoGenerator
-      def info
-        stability_bump(raw_info)
-      end
+      private
 
       def raw_info
         result = {}

data/lib/locatine/results_helpers/xpath_generator.rb

@@ -5,6 +5,8 @@ module Locatine
     ##
     # Methods for generation xpath from stored data
     module XpathGenerator
+      private
+
       def find_by_data(base = known)
         xpath = generate_xpath(base)
         @locator = { 'using' => 'xpath', 'value' => xpath }

data/lib/locatine/session.rb

@@ -1,18 +1,23 @@
 # frozen_string_literal: true
 
 module Locatine
+  ##
+  # Locatine Session class.
   #
-  # Locatine session operator finds and returns
+  # Each selenium session gets a locatine session. Locatine session knows
+  # selenium address and session_id so it is able to communicate with selenium.
+  # It has no complex logic, but acts like a bridge between daemon and selenium
+  # while element is searched
   class Session
     include Locatine::Logger
     attr_accessor :json, :depth, :trusted, :untrusted, :tolerance, :stability,
                   :elements, :timeout
 
-    def defaults
-      { json: "#{Dir.pwd}/locatine_files/default.json", depth: 3, trusted: [],
-        untrusted: [], tolerance: 50, stability: 10, timeout: 25 }
-    end
-
+    ##
+    # Init of the new session instance
+    #
+    # +selenium+ is a selenium address like "https://host:port"
+    # +session+ is a session id provided by selenium
     def initialize(selenium, session)
       @selenium = selenium
       @parsed_selenium = URI.parse @selenium
@@ -23,6 +28,10 @@ module Locatine
       configure defaults
     end
 
+    ##
+    # This method is to set settings
+    #
+    # +params+ is a hash of settings like {json: "some", depth: 0...}
     def configure(params)
       params.to_h.each_pair do |var, value|
         instance_variable_set("@#{var}", value)
@@ -31,23 +40,14 @@ module Locatine
       params
     end
 
-    def read
-      dir = File.dirname(@json)
-      FileUtils.mkdir_p(dir) unless File.directory?(dir)
-      unless File.exist?(@json)
-        File.open(@json, 'w') do |f|
-          f.write('{"elements" : {}}')
-        end
-      end
-      @elements = JSON.parse(File.read(@json))['elements']
-    end
-
-    def write
-      File.open(@json, 'w') do |f|
-        f.write(JSON.pretty_generate('elements' => @elements))
-      end
-    end
-
+    ##
+    # Find method is for finding elements.
+    #
+    # That is the part that is replacing simple finding by selenium
+    # +params+ is a hash of settings like {json: "some", depth: 0...}
+    # +parent+ is an element code of the element to look under. It is counted
+    # only for the most simple search. If element is lost parent will be
+    # ignored
     def find(params, parent = nil)
       find_routine(params, parent)
     rescue RuntimeError => e
@@ -57,17 +57,13 @@ module Locatine
       find(params, parent)
     end
 
-    def find_routine(params, parent)
-      results = Results.new
-      results.configure(self, params, parent)
-      answer = results.find
-      if !answer.empty? && answer.first.class != Locatine::Error
-        @elements[results.name] = results.info
-        write
-      end
-      answer
-    end
-
+    ##
+    # Session can execute js scripts on a page
+    #
+    # Note this method will be not called when you are asking selenoum via
+    # locatine to execute a script. This class is for internal use.
+    # +script+ some valid js code
+    # +*args+ arguments to be passed to script.
     def execute_script(script, *args)
       args.map! { |item| item.class == Locatine::Element ? item.answer : item }
       response = api_request('/execute/sync', 'Post',
@@ -79,6 +75,8 @@ module Locatine
       value
     end
 
+    ##
+    # Returning information about the current page
     def page
       # We need duplicated JSON parse since standart
       # chromedriver giving an error here if the page is too large
@@ -86,14 +84,14 @@ module Locatine
       JSON.parse(page, max_nesting: false)['result']
     end
 
-    def call_uri(path)
-      URI::HTTP.build(
-        host: @parsed_selenium.host,
-        port: @parsed_selenium.port,
-        path: "/wd/hub/session/#{@session}#{path}"
-      )
-    end
-
+    ##
+    # This method is used to ask selenium about something.
+    #
+    # We are using it to ask for elements found by selenium or
+    # for script execution
+    # +path+ is a relative path to call on selenium like '/elements'
+    # +method+ is an http method to perform ('Get', 'Post', etc.)
+    # +body+ is for request data. json here (selenium wants it) or nil
     def api_request(path, method, body)
       uri = call_uri(path)
       req = Net::HTTP.const_get(method)
@@ -103,5 +101,47 @@ module Locatine
       req.body = body
       Net::HTTP.new(uri.hostname, uri.port).start { |http| http.request(req) }
     end
+
+    private
+
+    def defaults
+      { json: "#{Dir.pwd}/locatine_files/default.json", depth: 3, trusted: [],
+        untrusted: [], tolerance: 50, stability: 10, timeout: 25 }
+    end
+
+    def read
+      dir = File.dirname(@json)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+      unless File.exist?(@json)
+        File.open(@json, 'w') do |f|
+          f.write('{"elements" : {}}')
+        end
+      end
+      @elements = JSON.parse(File.read(@json))['elements']
+    end
+
+    def write
+      File.open(@json, 'w') do |f|
+        f.write(JSON.pretty_generate('elements' => @elements))
+      end
+    end
+
+    def find_routine(params, parent)
+      results = Results.new
+      answer = results.find(self, params, parent)
+      if !answer.empty? && answer.first.class != Locatine::Error
+        @elements[results.name] = results.info
+        write
+      end
+      answer
+    end
+
+    def call_uri(path)
+      URI::HTTP.build(
+        host: @parsed_selenium.host,
+        port: @parsed_selenium.port,
+        path: "/wd/hub/session/#{@session}#{path}"
+      )
+    end
   end
 end

data/lib/locatine/version.rb

@@ -2,7 +2,7 @@
 
 module Locatine
   # constants here...
-  VERSION = '0.02878'
+  VERSION = '0.03050'
   NAME = 'locatine'
   HOME = if File.readable?("#{Dir.pwd}/lib/#{Locatine::NAME}")
            "#{Dir.pwd}/lib/#{Locatine::NAME}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: locatine
 version: !ruby/object:Gem::Version
-  version: '0.02878'
+  version: '0.03050'
 platform: ruby
 authors:
 - Sergei Seleznev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-08 00:00:00.000000000 Z
+date: 2020-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -145,6 +145,8 @@ files:
 - lib/locatine/logger.rb
 - lib/locatine/results.rb
 - lib/locatine/results_helpers/common.rb
+- lib/locatine/results_helpers/comparing.rb
+- lib/locatine/results_helpers/config.rb
 - lib/locatine/results_helpers/find_by_magic.rb
 - lib/locatine/results_helpers/guess.rb
 - lib/locatine/results_helpers/info_generator.rb