locatine 0.01822 → 0.01839

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c42ba5ac7959a4ab71aa728327a9c28370feb16a
-  data.tar.gz: a36821ec021212fbf125680d449242efba9abd2e
+  metadata.gz: 6085cdba5bc5b209bf24330ded9e2458c045d3e3
+  data.tar.gz: '0678ca74613066d304d6d8408ec18ef2dc5575da'
 SHA512:
-  metadata.gz: cfa093835faa43a741931e8d012b3800774c959d4779c2541b73803fec067b233a2bc262d84779b9b5ddd0f950ad19d1852ef46ac88759eac364e980b60fbdab
-  data.tar.gz: a77d487a503ee587b9ad4ad1491d0cf046a64502d680f9ebcef07f22fe1172ae7cf97f67de0d568deef4e9e2b59438ab6a3a9044b731b9a81740efbd002ac28e
+  metadata.gz: 10b9daf2cdd2139ddaf3f3054957ff467ba607681c692c6c7f3ea12c04b9d77845ab4a216003ccacdd6a84a5de901675f2708b2a17df967889d2a808c7dfbcfd
+  data.tar.gz: dfb7c5746b8219d8c90215c239d8aab91de686959911cd087d442a23d92e8564a8ff917f339cf2c22303b5722542f8fd32d61fea292b06b8196426741c680609

data/README.md

@@ -0,0 +1,323 @@
+# Locatine
+
+Element location tool based on Watir.
+
+You are asking Locatine to find element for you.
+
+It is asking you what element do you mean.
+
+It is remembering your answer and collecting information about selected element.
+
+After that it is finding element by itself.
+
+If your element will be lost (due to id change for example) locatine will locate the most similar element.
+
+That's it.
+
+## Stage of development:
+
+Version of Locatine is **0.01839** only. It means so far this is an early alfa. You can use it in a real project if you are really risky person.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'locatine'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install locatine
+
+## Usage
+
+1. Be sure that you have [Chrome browser](https://www.google.com/chrome/browser/desktop/) installed. It should work with any browser but something you can do in Chrome only
+2. Write the code
+```ruby
+require 'locatine'
+s = Locatine::Search.new
+s.browser.goto("yourpage.com.com")
+s.find(name: "element", scope: "Main").click
+```
+3. Run it in terminal with parameter LEARN=1 approximately like:
+
+    $ LEARN=1 ruby path_to_your_test.rb
+
+4. It will open the browser and transfer you to the yourpage.com.com
+5. Select element to represent *element* in the *Main* scope (you can click on it or select it in devtools)
+6. Click Locatine application icon at the browser panel
+7. And confirm the selection
+
+![Steps 4-5-6](readme/567.png)
+
+8. Now you can run the test without LEARN parameter and it will work.
+
+## Locatine app window
+
+### Element name
+
+You can ask the app to save element with any name. This name should be used for element finding later.
+
+### Waiting for click
+
+If you need to do some actions on page for debug purposes before defining the element you can turn off waiting for click. If Locatine is waiting for click every click is gonna be counted as element selection.
+
+### Single\\Collection mode
+
+If you need to find a collection of elements. Turn collection mode on. And click two elements of the kind. Locatine will automatically select all the elements that are similar to selected
+
+### Clear selection
+
+Click it to start element selection process from the very beginning.
+
+### Abort selection
+
+Will forcedly stop the selection process. Use with care since ruby methods will return nils and errors since element is not selected properly. Use it when you finish to define a scope.
+
+### Confirm selection
+
+When you've selected a correct element - confirm it in order to save.
+
+## Locatine::Search options
+
+```ruby
+Locatine::Search.new(json: "./Locatine_files/default.json",
+                     depth: 3,
+                     browser: nil,
+                     learn: ENV['LEARN'].nil? ? false : true,
+                     stability_limit: 1000,
+                     scope: "Default",
+                     tolerance: 33,
+                     visual_search: false)
+```
+
+### json
+
+the file where data collected about elements will be stored
+
+### depth
+
+shows how many info will be stored about each element
+
+- 0 = everything about the element
+- 1 = everything about the element and the parent of it
+- 2 = everything about the element and the parent of it + one more parent
+
+### browser
+
+if not provided new Watir::Browser will be started. Do not provide browser if you are going to use learn mode
+
+### learn
+
+mode is used to train locatine to search your elements. By default is false. But if you are starting your test like:
+
+    $ LEARN=true ruby path_to_your_test.rb
+
+it will turn learn to true by default.
+
+### scope
+
+is a setting that is representing default scope (group) where elements will be stored by default
+
+### stability_limit
+
+shows how much times attribute should be present to be considered a trusted one. The extremely large value means that locatine will hardly trust your code. Extremely low means that locatine will always believe that nothing in the code gonna be changed.
+
+### tolerance
+
+If stored metrics of element (including attributes, text, css values and tags) were changed Locatine will find and suggest the most similar one. Tolerance is showing how different in per cent new element may be to the old one. If 0 (zero tolerance) - locatine will find nothing if element lost. If 50 it is enough for element to have only half of parameters of old element we are looking for to be returned. If 100 - at least something is found - it goes. Default if 67 (means only 33% of element should stay in element to be found and returned).
+
+### visual_search
+
+locatine will count css values and position of element only if true. In that case locatine will not only read html code (attributes, tags, texts) but it will get css stylesheet for element, its position and size. In the most common case locatine is using attributes+tag+text to find the element. It is starting to use css styles of element and position only if element is lost in order to provide a better result and to mesure the similarity of the lost element and one that is found.
+
+Position and size for element will be stored for the current resolution only. Start with new browser resolution will lead to deletion of all previous location\\size data.
+
+Be careful! Set true only if appearance of your page is pretty stable.
+
+## Changing options on fly
+
+You can get or set these values on fly. Like:
+
+```ruby
+s = Locatine::Search.new(learn: true)
+s.learn #=> true
+s.learn = false
+```
+
+## Locatine::Search find options
+
+```ruby
+s.find(name: "some name",
+       scope: "Default",
+       exact: false,
+       locator: {},
+       vars: {},
+       look_in: nil,
+       iframe: nil,
+       return_locator: false,
+       collection: false,
+       tolerance: nil)
+```
+### name
+
+should be always provided. Name of element to look for. Must be uniq one per scope. Ideally name should be made of 2-4 words separated by spaces describing its nature ("pay bill button", "search input", etc.) It will help Locatine to find them.
+
+### scope
+
+group of elements. Must be uniq per file. This is to help to store elements with same names from different pages in one file
+
+### exact
+
+unless it is true locatine will always try to find lost element using all the power it has. Use exact: true if you want element to be lost in case of any significant change. If it is impossible to find element when exact: true locatine will return nil.
+
+Be carefull: exact is working only when element is stable (has at least one parameter persistent for stability_limit times == well known by locatine). If element is not stable yet locatine will search for it anyway and maybe it will find something. So if you want to ensure that element does not exist you should use locator and exact at the same time. You may also set zero tolerance. Check it:
+
+```ruby
+# Will return nil if there is no element id = 'not welcome'
+s.find(name: "unexpected element", locator:{id: "not welcome"}, exact: true)
+
+# Will return nil if well known element "unexpected element" is not present
+# Will try to find and return at least something if "unexpected element" is not stable (well known)
+# If there is nothing similar to "unexpected element" returns nil
+s.find(name: "unexpected something", exact: true)
+
+# Will return element only if the same element is present
+# Changing of any attribute which is trusted by locatine will produce nil
+s.find(name: "unexpected something", exact: true, tolerance: 0)
+```
+
+### locator
+
+you may provide your own locator to use. Same syntax as in Watir:
+
+```ruby
+find(name: "element with custom locator", locator: {xpath: "//custom"})
+```
+
+### vars
+
+are used to pass dynamic attributes.
+
+For example you have created an account on your site with
+
+```ruby
+name == "stablePart_qljcrt24jh"
+```
+
+where
+
+```ruby
+random_string == "qljcrt24jh"
+```
+
+was generated by random. Now you need to find the element with this part on the page. You can do
+
+```ruby
+random_string #=> "qljcrt24jh"
+find(name: "account name", vars: {text: random_string})
+```
+
+Next time when your test will generate another random_string it will use new value.
+
+```ruby
+vars = {text: random_substring} # If you want the text of element to be dynamic
+vars = {tag: random_tag} # The tag
+vars = {attribute_name: random_attr} # If attribute is dynamic (use name of the attribute)
+# And two lines work with visual_search == true only
+vars = {css_option: random_value} # If your css is dynamic
+vars = {x: random_x} # x, y, width, height for element size and position
+```
+
+And if you do not like it you can do:
+
+```ruby
+random_string #=> "qljcrt24jh"
+find(name: "account name", locator:{text: "stablePart_#{random_string}")
+```
+
+### look_in
+
+is for method name taken from Watir::Browser item. It should be a method that returns collection of elements like (text_fields, divs, links, etc.). If this option is stated locatine will look for your element only among elements of that kind. Be careful with it in a learn mode. If your look_in setting and real element are from different types. Locatine will be unable to find it.
+
+### iframe
+
+that is in order to find element inside of an iframe
+
+### return_locator
+
+true is returning the locator of the element instead of element. Use with care if attributes of your elements are dynamic and you are in a learning mode.
+
+### collection
+
+if true array of elements will be returned. If false only the one element (the first one found) will be returned.
+
+### tolerance
+
+You can state custom tolerance for the element.
+
+## Scope
+
+If you want to define a whole bunch of elements at once you can do:
+
+```ruby
+search = Locatine::Search.new(learn: true)
+search.get_scope(name: "Name of scope") # Will ask you about all the elements in scope
+# or
+scope = Locatine::Scope.new('Name of scope', search)
+scope.define
+```
+
+You will be able to select all the elements and collections for scope one by one. When it is finished click "Abort Selection" button to exit the loop.
+
+```ruby
+# You can force use dynamic variables on define where is possible (same rules as for find)
+vars = {text: "dynamic text",
+        tag: "span",
+        attrName: "part of dynamic attr-value"}
+scope.define(vars) # Will ask you about all the elements in scope
+# Same
+search.get_scope(name: "Name of scope", vars: vars) # Will ask you...
+# Finally when scope is defined
+search.find(scope: "Name of scope",
+            name: "Name of element in scope",
+            vars: vars # Necessary if elements were defined with vars)
+```
+
+Scope itself is not very useful now. But we are looking forward.
+
+## Other ways to use find
+
+If the scope is set and you do not want to provide any additional options you can do:
+
+```ruby
+s = Locatine::Search.new
+s.find("just name of element")
+```
+
+Also you can do:
+
+```ruby
+s = Locatine::Search.new
+s.browser.button(s.lctr("name of the button"))
+# or
+s.browser.button(s.lctr(name: "name of the button", scope: "Some form"))
+# or
+s.browser.button(s.lctr("name of the button", scope: "Some form"))
+```
+
+That may be helpful in case of migration from plain watir to watir + locatine
+
+If you want to find collection of elements you can use:
+
+```ruby
+s = Locatine::Search.new
+s.collect("group of elements") # Will return an array
+# or
+s.collect(name: "group of elements")
+```

data/lib/locatine/app/content.js

@@ -14,7 +14,8 @@ async function creatingDiv(){
     "id":"locatine_magic_div",
     "locatinestyle": await get_value('magic_div') || "false",
     "locatinetitle": "ok",
-    "locatinehint": "ok"
+    "locatinehint": "ok",
+    "locatine_name": ""
   };
   locatine_create_element(document.body, "div", options, "");
   const magic_cover = document.getElementById('locatine_magic_div');
@@ -53,13 +54,27 @@ async function setConfirm(magicDiv) {
   magicDiv.setAttribute("locatineconfirmed", confirmed);
 }
 
+async function setName(magicDiv) {
+  const selectionName = magicDiv.getAttribute("locatine_name");
+  const nameMark = magicDiv.getAttribute("locatine_name_mark");
+  if (nameMark != "true") {
+    magicDiv.setAttribute("locatine_name", await get_value("locatineName"));
+  }
+  if ((selectionName != "") && (nameMark == "true")){
+    await set_value("locatineName", selectionName);
+    magicDiv.setAttribute("locatine_name_mark", "");
+  }
+}
+
 async function refreshData(){
   const magicDiv = document.getElementById("locatine_magic_div");
   if (!document.getElementById("locatine_magic_div")){
     creatingDiv();
+    set_value("locatineName", "");
   } else {
     setStyle(magicDiv.getAttribute("locatinestyle"), magicDiv);
     setTitleHint(magicDiv);
+    setName(magicDiv);
     magicDiv.setAttribute("locatinecollection", await get_value("locatine_collection"));
     setConfirm(magicDiv);
   };

data/lib/locatine/app/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "Locatine app",
-  "version": "0.01822",
+  "version": "0.01839",
   "description": "Messaging from browser to main app",
   "devtools_page": "devtools.html",
   "permissions": ["activeTab", "storage", "contextMenus", "tabs"],

data/lib/locatine/app/popup.css

@@ -10,6 +10,12 @@
   font-size: 16px;
 }
 
+.field {
+  width: 100%;
+  height: 30px;
+  display: block;
+}
+
 .green {
   background-color: #4CAF50
 }

data/lib/locatine/app/popup.html

@@ -7,10 +7,12 @@
     <h2 class="header" id="mainTitle">Right now you are defining nothing. So no button will work</h2>
     <h3 class="hint" id="hint">But you can click it anyway :)</h3>
     <div class="block">
-      <input class="blue button" id="watchSwitch" type="button" value="Do not watch"/>
-      <input class="blue button" id="mode" type="button" value="Adding mode is enabled"/>
-      <input class="red button" id="clearMark" type="button" value="Clear selection"/>
-      <input class="green button" id="confirm" type="button" value="Confirm selection"/>
+      <input title="You can set your own element name here. Do not forget to use it in your code!" class="usual field" id="nameHandler" type="text" placeholder="Element name" value=""/>
+      <input title="If you need to do some actions on page for debug purposes before defining the element you can turn off waiting for click. If Locatine is waiting for click every click is gonna be counted as element selection." class="blue button" id="watchSwitch" type="button" value="Do not watch"/>
+      <input title="If you need to find a collection of elements. Turn collection mode on. And click two elements of the kind. Locatine will automatically select all the elements that are similar to selected" class="blue button" id="mode" type="button" value="Adding mode is enabled"/>
+      <input title="Click it to start element selection process from the very beginning." class="red button" id="clearMark" type="button" value="Clear selection"/>
+      <input title="Will forcedly stop the selection process. Use with care since ruby methods will return nils and errors since element is not selected properly. Use it when you finish to define a scope." class="red button" id="abort" type="button" value="Abort selection"/>
+      <input title="When you've selected a correct element - confirm it in order to save." class="green button" id="confirm" type="button" value="Confirm selection"/>
     </div>
     <script src="popup.js"></script>
   </body>

data/lib/locatine/app/popup.js

@@ -22,6 +22,9 @@ async function correct_buttons() {
   };
   document.getElementById("mainTitle").innerText = await get_value("locatine_title");
   document.getElementById("hint").innerText = await get_value("locatine_hint");
+  if ((document.getElementById("nameHandler").value != await get_value("locatineName")) && (!document.hasFocus())){
+    document.getElementById("nameHandler").value = (await get_value("locatineName") || "");
+  }
 }
 
 async function watch() {
@@ -36,14 +39,24 @@ function confirm() {
   set_value("locatine_confirm", true);
 }
 
+function abort() {
+  set_value("locatine_confirm", 'abort');
+}
+
 async function mode() {
   await set_value("locatine_collection", !(await get_value("locatine_collection")));
 }
 
+async function doName() {
+  await set_value("locatineName", document.getElementById("nameHandler").value);
+}
+
 document.getElementById("watchSwitch").onclick = function() {watch()};
 document.getElementById("clearMark").onclick = function() {clear()};
 document.getElementById("confirm").onclick = function() {confirm()};
 document.getElementById("mode").onclick = function() {mode()};
+document.getElementById("abort").onclick = function() {abort()};
+document.getElementById("nameHandler").oninput = function() {doName()};
 
 setInterval(function(){
   correct_buttons();

data/lib/locatine/for_search/data_logic.rb

@@ -37,12 +37,12 @@ module Locatine
       end
 
       def equal_elements?(one, another)
-        good = true
+        good = true unless one == {}
         one.each_pair do |depth, array|
           trusted = get_trusted(array).map do |i|
             i.reject { |k| k == 'stability' }
           end
-          good &&= (trusted - another[depth] == [])
+          good &&= ((trusted - another[depth] == []) && !trusted.empty?)
         end
         good
       end

data/lib/locatine/for_search/dialog_logic.rb

@@ -48,7 +48,7 @@ module Locatine
       end
 
       def return_old_selection(attrs, vars)
-        return find_by_data(attrs, vars).to_a, attrss.to_h if attrs.to_h != {}
+        return find_by_data(attrs, vars).to_a, attrs.to_h if attrs.to_h != {}
 
         return nil, {}
       end
@@ -62,12 +62,11 @@ module Locatine
         return element, new_attributes
       end
 
-      def what_was_selected(element, attributes, vars, name, scope)
+      def what_was_selected(element, attributes, vars)
         tag, index = tag_index
         send_to_app('locatineconfirmed', 'ok')
         mass_highlight_turn(element, false) if element
         element, attributes = working_on_selected(tag, index, vars, attributes)
-        show_element(element, attributes, name, scope) if element
         return element, attributes
       end
 
@@ -88,7 +87,9 @@ module Locatine
       def user_selection(els, attrs, vars, name, scope)
         case get_from_app('locatineconfirmed')
         when 'selected'
-          els, attrs = what_was_selected(els, attrs, vars, name, scope)
+          els, attrs = what_was_selected(els, attrs, vars)
+          name = suggest_name(name, attrs, vars)
+          show_element(els, attrs, name, scope) if els
         when 'declined'
           els, attrs = decline(els, name, scope)
         end
@@ -96,13 +97,16 @@ module Locatine
       end
 
       def listening(els, attrs, vars, name, scope)
-        until get_from_app('locatineconfirmed') == 'true'
+        until %w[true abort].include?(get_from_app('locatineconfirmed'))
           sleep(0.1)
           els, attrs = user_selection(els, attrs, vars, name, scope)
         end
-        return els, attrs if els
+        result = get_from_app('locatineconfirmed')
+        return els, attrs if els && result != 'abort'
+
+        els, attrs = decline(els, name, scope)
+        return els, attrs if result == 'abort'
 
-        decline(els, name, scope)
         listening(els, attrs, vars, name, scope)
       end
 
@@ -114,8 +118,10 @@ module Locatine
         @cold_time = 0
         element, attributes = listening(element, attributes, vars, name, scope)
         @cold_time = nil
+        name_from_app = get_from_app('locatine_name')
+        name = name_from_app unless name_from_app.to_s.empty?
         response_action(element)
-        return element, attributes
+        { element: element, attributes: attributes, name: name }
       end
     end
   end

data/lib/locatine/for_search/find_by_locator.rb

@@ -20,6 +20,11 @@ module Locatine
       # Getting all the elements matching a locator
       def find_by_locator(locator)
         method = @type.nil? ? :elements : @type
+        begin
+          engine.element(locator).wait_until(timeout: @cold_time, &:exists?)
+        rescue StandardError
+          return nil
+        end
         results = engine.send(method, locator)
         return correct_method_detected(results) if collection?(results.class)
 
@@ -27,15 +32,12 @@ module Locatine
       end
 
       def correct_method_detected(results)
-        all = []
-        begin
-          results[0].wait_until(timeout: @cold_time, &:present?)
-        rescue StandardError
-          nil
-        end
-        results.each { |item| all.push item if item.present? }
+        return nil if results.empty?
+
+        all = results.reject(&:stale?)
         return all unless all.empty?
-        return nil if all.empty?
+
+        nil
       end
 
       def acceptable_method_detected(results, method, locator)

data/lib/locatine/for_search/find_logic.rb

@@ -47,7 +47,11 @@ module Locatine
         result, attributes = locator_search(locator, vars)
         ok = result || ((locator != {}) && exact)
         result, attributes = core_search(name, scope, vars, exact) unless ok
-        result, attributes = ask(scope, name, result, vars) if @learn
+        if @learn
+          answer = ask(scope, name, result, vars)
+          result = answer[:element]
+          attributes = answer[:attributes]
+        end
         return result, attributes
       end
 

data/lib/locatine/for_search/highlight.rb

@@ -9,8 +9,7 @@ module Locatine
       # We can highlight an element
       def highlight(element)
         script = "arguments[0].setAttribute('locatineclass','foundbylocatine')"
-        ok = !element.stale? && element.exists?
-        engine.execute_script(script, element) if ok
+        engine.execute_script(script, element)
       rescue StandardError
         warn_cannot_highlight(element.selector)
       end
@@ -19,8 +18,7 @@ module Locatine
       # We can unhighlight an element
       def unhighlight(element)
         script = "arguments[0].removeAttribute('locatineclass')"
-        ok = !element.stale? && element.exists?
-        engine.execute_script(script, element) if ok
+        engine.execute_script(script, element)
       rescue StandardError
         false
         # watir is not allowing to play with attributes of some elements
@@ -29,7 +27,8 @@ module Locatine
       ##
       # We can highlight\unhighlight tons of elements at once
       def mass_highlight_turn(mass, turn_on = true)
-        mass.each do |element|
+        warn_much_highlight if turn_on && mass.length > 50
+        mass[0..49].each do |element|
           if turn_on
             highlight element
           else

data/lib/locatine/for_search/listening.rb

@@ -37,7 +37,7 @@ module Locatine
       def response_action(element)
         send_to_app('locatineconfirmed', 'ok')
         send_has_response
-        mass_highlight_turn(element, false)
+        mass_highlight_turn(element, false) if element
         send_to_app('locatinestyle', 'set_false')
         send_to_app('locatinestyle', 'ok', @browser) if @iframe
         sleep 1

data/lib/locatine/for_search/name_helper.rb

@@ -0,0 +1,51 @@
+module Locatine
+  module ForSearch
+    ##
+    # We have a module that helps name elements
+    module NameHelper
+      private
+
+      def good_name(main, vars)
+        good = %w[name title id role text]
+        tmp = main.select { |i| good.any? { |k| i['name'].include?(k) } }
+        words = (tmp.map { |i| process_string(i['value'], vars) }).uniq
+        words.sample
+      end
+
+      def so_so_name(main, vars)
+        all = main.select { |i| i['type'] == 'attribute' }
+        words = all.map { |i| process_string(i['value'], vars) }
+        words.sample
+      end
+
+      def some_name(main, vars)
+        result = good_name(main, vars)
+        result = so_so_name(main, vars) if result.nil?
+        result = "undescribed #{generate_word}" if result.nil?
+        result
+      end
+
+      def suggest_name(name, attrs, vars)
+        if name.to_s.empty?
+          tag = attrs['0'].select { |i| i['type'] == 'tag' }
+          tag = process_string(tag[0]['value'], vars)
+          name = "#{some_name(attrs['0'], vars)} #{tag}"
+        end
+        suggest = name
+        send_to_app('locatine_name', suggest)
+        send_to_app('locatine_name_mark', 'true')
+        suggest
+      end
+
+      def generate_word(pairs = 3)
+        ss = 'qwrtpsdfghjklzxcvbnm'.split('')
+        sa = 'eyuioa'.split('')
+        str = ''
+        pairs.times do
+          str += ss.sample + sa.sample
+        end
+        str
+      end
+    end
+  end
+end

data/lib/locatine/for_search/public.rb

@@ -7,6 +7,7 @@ module Locatine
       # Creates a new instance of Search
       #
       # Params:
+      #
       # +json+ is the name of file to store//read data. Default =>
       # "./Locatine_files/default.json"
       #
@@ -24,7 +25,7 @@ module Locatine
       # +scope+ will be used in search (if not provided) defaulkt is "Default"
       #
       # +tolerance+ Shows how similar must be an element found as alternative
-      # to the lost one. Default is 33 which means that if less than 33% of
+      # to the lost one. Default is 67 which means that if less than 33% of
       # metrics of alternative elements are the same as of the lost element
       # will not be returned
       def initialize(json: './Locatine_files/default.json',
@@ -74,6 +75,9 @@ module Locatine
       #
       # +collection+ when true an array will be returned. When false - a
       # single element
+      #
+      # +tolerance+ It is possible to set a custom tolerance for every find. See
+      # examples in README
       def find(simple_name = nil,
                name: nil,
                scope: nil,
@@ -113,6 +117,12 @@ module Locatine
       def browser=(value)
         import_browser(value)
       end
+
+      def get_scope(name: 'Default', vars: {})
+        answer = Scope.new(name, self)
+        answer.define(vars) if @learn
+        answer
+      end
     end
   end
 end

data/lib/locatine/for_search/saying.rb

@@ -60,6 +60,7 @@ module Locatine
       end
 
       def send_clear(name, scope)
+        name = 'some element' if name.to_s.empty?
         push_title "Now nothing is selected as #{name} in #{scope}"
       end
 
@@ -72,6 +73,7 @@ module Locatine
       end
 
       def send_selecting(name, scope)
+        name = 'some element' if name.to_s.empty?
         push_title "You are selecting #{name} in #{scope}"
         send_to_app('locatinehint', 'Toggle single//collection mode button if '\
           'you need. If you want to do some actions on the page toggle'\
@@ -120,6 +122,10 @@ module Locatine
         send_warn "Something was found as #{data} but we cannot highlight it"
       end
 
+      def warn_much_highlight(size)
+        send_warn "Only the first 50 elements of #{size} were highlighted."
+      end
+
       def warn_lost_found(name, scope)
         send_warn "Something was found as #{name} in #{scope}."
       end

data/lib/locatine/scope.rb

@@ -0,0 +1,20 @@
+module Locatine
+  ##
+  # Scope is the class representing group of elements
+  #
+  # Locatine has scopes
+  class Scope
+    def initialize(scope, search)
+      @search = search
+      @scope = scope
+    end
+
+    def define(vars = {})
+      item = @search.send(:ask, @scope, '', nil, vars)
+      return if item[:element].nil?
+
+      @search.send(:store, item[:attributes], @scope, item[:name])
+      define(vars)
+    end
+  end
+end

data/lib/locatine/search.rb

@@ -9,15 +9,16 @@ require 'locatine/for_search/public'
 require 'locatine/for_search/saying'
 require 'locatine/for_search/helpers'
 require 'locatine/for_search/file_work'
+require 'locatine/for_search/listening'
 require 'locatine/for_search/highlight'
 require 'locatine/for_search/data_logic'
 require 'locatine/for_search/find_logic'
 require 'locatine/for_search/find_by_css'
+require 'locatine/for_search/name_helper'
 require 'locatine/for_search/dialog_logic'
 require 'locatine/for_search/find_by_magic'
 require 'locatine/for_search/find_by_guess'
 require 'locatine/for_search/data_generate'
-require 'locatine/for_search/listening'
 require 'locatine/for_search/xpath_generator'
 require 'locatine/for_search/find_by_locator'
 
@@ -37,6 +38,7 @@ module Locatine
     include Locatine::ForSearch::FindLogic
     include Locatine::ForSearch::Highlight
     include Locatine::ForSearch::FindByCss
+    include Locatine::ForSearch::NameHelper
     include Locatine::ForSearch::FindByMagic
     include Locatine::ForSearch::DialogLogic
     include Locatine::ForSearch::FindByGuess

data/lib/locatine/version.rb

@@ -1,6 +1,6 @@
 module Locatine
   # constants here...
-  VERSION = '0.01822'.freeze
+  VERSION = '0.01839'.freeze
   NAME = 'locatine'.freeze
   HOME = if File.readable?("#{Dir.pwd}/lib/#{Locatine::NAME}")
            "#{Dir.pwd}/lib/#{Locatine::NAME}"

data/lib/locatine.rb

@@ -1,2 +1,3 @@
 require 'locatine/search'
+require 'locatine/scope'
 require 'locatine/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: locatine
 version: !ruby/object:Gem::Version
-  version: '0.01822'
+  version: '0.01839'
 platform: ruby
 authors:
 - Sergei Seleznev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-28 00:00:00.000000000 Z
+date: 2019-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,6 +114,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/locatine.rb
 - lib/locatine/app/background.js
 - lib/locatine/app/content.css
@@ -138,13 +139,16 @@ files:
 - lib/locatine/for_search/highlight.rb
 - lib/locatine/for_search/listening.rb
 - lib/locatine/for_search/merge.rb
+- lib/locatine/for_search/name_helper.rb
 - lib/locatine/for_search/public.rb
 - lib/locatine/for_search/saying.rb
 - lib/locatine/for_search/xpath_generator.rb
 - lib/locatine/large_scripts/css.js
 - lib/locatine/large_scripts/dimensions.js
+- lib/locatine/scope.rb
 - lib/locatine/search.rb
 - lib/locatine/version.rb
+- readme/567.png
 homepage: https://github.com/sseleznevqa/locatine
 licenses:
 - MIT