locatine 0.02542 → 0.02878

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: df3f8d995c895faf833681632462dcd884e73bce
-  data.tar.gz: 8885ecd8b1513df7cac86761a22e02acdb692f03
+SHA256:
+  metadata.gz: 457cb5d21eae999673da17f8c5c200181755f846946e81c81d9a23bbafa85528
+  data.tar.gz: f3ae98ffc268889f4781126b71106ffc99c29c73f9cd4e8321743388fb56bf70
 SHA512:
-  metadata.gz: 0234243bf852972ac60752c0be0232a2c427ce0f40f21fefaaa2cf8e7a32403e2c33f8761fcaa28712ffd8bd0960b1d2c46f5f3846e45c56e51edf5b5dc2831e
-  data.tar.gz: ec7071e6b671a03d6cf2fe034b510f914af84e403248ddcd6a3d230a9c8cf9ba4f2c291ffe9722a5a58436d3208754b5898d1a9dc94d00f9016772fcf2a6b117
+  metadata.gz: ed6f3ad8a5e29ea3b3e672b5a5cbd006571fa9536821dbc0b1467b005cf0998efc19425ba17f166a608cf84b5a884908c1d718275dbbebd0a56372a85f10d988
+  data.tar.gz: a7e5b86fe05b8710fd5bbd675733937dab017f8c27d8e27e4dbd5865da9313211775877c931a56c36414e0f1a3d94d3c66365a511f543daad4022fb00be91b14

data/README.md

@@ -1,22 +1,24 @@
 # Locatine
 
-Element location tool based on Watir.
+Locatine is a proxy between your code and selenium.
 
-You are asking Locatine to find element for you.
+It remembers element when you are finding it via selenium.
 
-It is asking you what element do you mean.
+It stores the findings to the json file for the future use.
 
-It is remembering your answer and collecting information about selected element.
+On the next search if element is lost Locatine will try to find it anyway using previously collected information.
 
-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.
+So your locator will be a little bit more stable than before.
 
 That's it.
 
 ## Stage of development:
 
-Version of Locatine is **0.02542** only. It means so far this is an alfa. You can use it in a real project if you are a risky person.
+Version of Locatine is **0.02878**. The 4th version since rewriting. 5-15 next versions is dedicated to bug fixing, tweaking.
+
+## Attention
+
+This version of Locatine is not compatible to previous.
 
 ## Installation
 
@@ -36,469 +38,440 @@ Or install it yourself as:
 
 ## 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
+1. Be sure that you have [Chrome browser](https://www.google.com/chrome/browser/desktop/) installed.
+2. Be sure that you have [chromedriver](https://chromedriver.chromium.org/) installed.
+3. Write the code (using your language - ruby is an example)
 
 ```ruby
-require 'locatine'
-s = Locatine::Search.new
-s.browser.goto("yourpage.com.com")
-s.find(name: "element", scope: "Main").click
+driver = Selenium::WebDriver.for :remote, url: "http://localhost:7733/wd/hub", desired_capabilities: :chrome
+driver.navigate.to("yourpage.com.com")
+driver.find_element(xpath: "//*[@id = 'element']")
+driver.quit
 ```
 
-3. Run it in terminal with parameter LEARN=1 approximately like:
+4. Run the locatine daemon
 
-    $ LEARN=1 ruby path_to_your_test.rb
+```
+    $ SELENIUM=http://localhost:4444 locatine-daemon.rb --port=7733
+```
 
-4. It will open the browser and transfer you to the yourpage.com.com
-5. Click Locatine application icon at the browser panel
-6. Select element to represent *element* in the *Main* scope (you can click on it or select it in devtools)
-7. And confirm the selection
+5. SELENIUM - is for url where selenium hub is started, port is the port for your code to connect. 4444 and 7733 are defaults.
+6. Run your code
+7. Data of element will be stored to ./default.json file.
+8. Now if id of your element is changed on the page Locatine will show a warning and gonna try to retrieve it.
+9. See [example](https://github.com/sseleznevqa/locatine/tree/master/examples) to see how it really works.
 
-![U can see an image here. On github)](readme/567.png)
+## Session
 
-8. Now you can run the test without LEARN parameter and it will work.
+Each time when you initializing new selenium session, locatine session is created as well.
 
-## Locatine app window
+It is used to store default options for search.
 
-### Element name
+There are two ways to set options of the session:
 
-You can ask the app to save element with any name. This name should be used for element finding later.
+The most simple is to send it via desired capabilities like (ruby example again)
 
-### Waiting for click
+```ruby
+caps = Selenium::WebDriver::Remote::Capabilities.
+                 chrome('locatine' => {'json' => '/your/path/elements.json'})
+driver = Selenium::WebDriver.
+   for :remote, url: "http://localhost:7733/wd/hub", desired_capabilities: caps
+```
 
-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.
+This way is recommended because of the simplicity.
 
-### Single\\Collection mode
+Another way is to set options after the session was created by making [POST request to '/locatine/session/%session_id%'](https://github.com/sseleznevqa/locatine#post-to-wdhubsession)
 
-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
+## Settings to pass
 
-### Clear selection
+### json
 
-Click it to start element selection process from the very beginning.
+Provide a string here.
 
-### Abort selection
+Default is 'locatine-working-dir/locatine_files/default.json'
 
-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.
+**json** is the path of the file that will be used to store data collected about elements by locatine-daemon.
 
-### Confirm selection
+It is recommended to use a different json for every test (or test group) in order to have lots of small and easily readable files and not the giant one.
 
-When you've selected a correct element - confirm it in order to save.
+**NOTE! Only unix filesystems are supported so far.**
 
-## Locatine::Search options
+### depth
 
-```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,
-                     no_fail: false,
-                     trusted: [],
-                     untrusted: [],
-                     autolearn: nil)
-```
+Provide a non negative integer here.
 
-### json
+Default is 3
 
-the file where data collected about elements will be stored
+**depth** value shows how deeply locatine will research the element.
 
-### depth
+0 - means that only the retrieved element will be remembered.
 
-shows how many info will be stored about each element
+```html
+<div id="element to find"></div>
+```
 
-- 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
+1 - means that the retrieved element and its ancestor will be examined:
 
-### browser
+```html
+<div id="ancestor">
+  <div id="element to find"></div>
+</div>
+```
 
-if not provided new Watir::Browser will be started. Do not provide browser if you are going to use learn mode
+2 - means that two ancestors will be remembered.
 
-### learn
+And so on and so forth.
 
-mode is used to train locatine to search your elements. By default is false. But if you are starting your test like:
+The higher depth the more easily locatine-daemon will find the element including the case when the element is lost (attributes are changed).
 
-    $ LEARN=true ruby path_to_your_test.rb
+On the other side large depth is making internal locator more unstable since it is requires stability of all the ancestors as well.
 
-it will turn learn to true by default.
+Read more about [finding elements](https://github.com/sseleznevqa/locatine#finding-elements)
 
-### scope
+**NOTE! Taking additional information (larger depth) costs an additional time while retrieving element and when looking for the lost one**
 
-is a setting that is representing default scope (group) where elements will be stored by default
+### trusted
 
-### stability_limit
+Provide an array of strings here.
 
-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.
+Default is []
 
-### tolerance
+Usually if some attribute or tag or text is changing locatine is marking it as untrusted data and not using it in search till it appears enough times to be considered stable again.
 
-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).
+But locatine will always use for search for element something that is listed as trusted here.
 
-### visual_search
+Use attribute name (like ['id']) for id attribute, use ['text'] for text and ['tag'] to trust the tag of element.
 
-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.
+**NOTE! ['text'] will affect both - text of element and attribute of element that is named 'text'**
 
-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.
+### untrusted
 
-Be careful! Set true only if appearance of your page is pretty stable.
+Provide an array of strings here.
 
-### no_fail
+Default is []
 
-When element is lost and no_fail is true you will get nil for single element and [] for collection. If no_fail is false (which is default) and locatine cannot find something you will face an error.
+Working completely opposite to [trusted](https://github.com/sseleznevqa/locatine#trusted)
 
-### trusted/untrusted
+Locatine will never consider reliable attributes or text or tag if it is listed as untrusted. It will be never used to search elements.
 
-If you are sure that some attribute (or something) is not good(generated by random, not uniq, etc.) you can forbid to use it in search. You can write attribute name, "text", "tag", or css attribute name (if you are using visual_search)
+Use attribute name (like ['id']) for id attribute, use ['text'] for text and ['tag'] to untrust the tag of element.
 
-On the other hand you can force locatine to always trust something with trusted.
+**NOTE! ['text'] will affect both - text of element and attribute of element that is named 'text'**
 
-### autolearn
+### stability
 
-Determines wether Locatine will study elements by default or not.
+Provide a positive integer here.
 
-If true Locatine will always check element for changes even if it is found properly (to catch for example adding of a new attribute). This is slow.
+Default is 10
 
-If false Locatine will study element only in case when it is lost.
+At first locatine trusts everything except [untrusted](https://github.com/sseleznevqa/locatine#untrusted). But sometimes attribute value, text or tag changes. In that case those new values will be not used in search anymore.
 
-If not stated Locatine will use false until it is not facing any lost element. After the first lost element it will be studying everything (true).
+**stability** shows how much times new attribute or text or tag should be found without changes to be considered reliable to be used for search once again.
 
-Notice that if autolearn is false Locatine is not bumping the stability values of attributes for elements which were found normally.
+### tolerance
 
-## Changing options on fly
+Provide an integer in a range from 0 to 100
 
-You can get or set these values on fly. Like:
+Default is 50
 
-```ruby
-s = Locatine::Search.new(learn: true)
-s.learn #=> true
-s.learn = false
-```
+If your element is changed locatine is trying to find it anyway. Tolerance shows how similar the new element should be to the ild one to be returned.
 
-## Locatine::Search find options
+Example:
 
-```ruby
-s.find(name: "some name",
-       scope: "Default",
-       exact: false,
-       locator: {},
-       vars: {},
-       look_in: nil,
-       iframe: nil,
-       return_locator: false,
-       collection: false,
-       tolerance: nil,
-       no_fail: nil,
-       trusted: [],
-       untrusted: [])
+```html
+<!--Old element-->
+<div id="too" class="old one">element</div>
+<!--New element-->
+<div id="too" class="new one">element</div>
 ```
-### 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
+5 pieces of information will be collected about an old element (tag == div, id == too, class == old, class ==one, text == element)
 
-group of elements. Must be uniq per file. This is to help to store elements with same names from different pages in one file
+4 parts are staying the same after changes. So similarity will be counted like (4*100/5 == 80)
 
-### locator
+Since similarity(80)>=100-tolerance(50) the new element will be returned.
 
-you may provide your own locator to use. Same syntax as in Watir:
+But for the case:
 
-```ruby
-find(name: "element with custom locator", locator: {xpath: "//custom"})
+```html
+<!--Old element-->
+<div id="too" class="old one">element</div>
+<!--New element-->
+<div id="lost" class="new two">element</div>
 ```
 
-### vars
+Similarity will be only 40 which is less than 100-50. It means that no element will be returned.
 
-are used to pass dynamic attributes.
+So default tolerance == 50 means that at least 50% of element data should be equal to stored data for element to be found.
 
-For example you have created an account on your site with
+Only data of the element itself is counted here.
 
-```ruby
-name == "stablePart_qljcrt24jh"
-```
+**NOTE! 0 (zero tolerance) means that locatine will not even try to find the lost element. 100 tolerance is too opportunistic**
 
-where
+### timeout
 
-```ruby
-random_string == "qljcrt24jh"
-```
+Provide an positive integer here (up to 25 is recommended)
 
-was generated by random. Now you need to find the element with this part on the page. You can do
+Default is 25
 
-```ruby
-random_string #=> "qljcrt24jh"
-find(name: "account name", vars: {text: random_string})
-```
+**timeout** shows the maximum amount of seconds locatine will try to find something.
 
-Next time when your test will generate another random_string it will use new value.
+Since default net timeout for most selenium implementations is 30 seconds, 25 is a good idea.
 
-```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 for element position
-```
+**NOTE! It's not an exact time. When timeout is reached it means for locatine that it is time to finish the party. But it cannot be finished instantly and the speed of the process may slightly vary.**
+
+## Finding elements
 
-And if you do not like it you can do:
+All the requests that are retrieving elements are wrapped by locatine-daemon.
 
 ```ruby
-random_string #=> "qljcrt24jh"
-find(name: "account name", locator:{text: "stablePart_#{random_string}")
+caps = Selenium::WebDriver::Remote::Capabilities.chrome('locatine' =>
+                                         {'json' => "#{Dir.pwd}/elements.json"})
+driver = Selenium::WebDriver.for :remote,
+                                 url: "http://localhost:7733/wd/hub",
+                                 desired_capabilities: caps
+# Page that has <div id='element' class='1 2 3'>Text</div>
+driver.navigate.to page 1
+# Getting element for the first ешьу
+element = driver.find_element(xpath: "//*[@id='element']")
+# We are changing id of the element
+driver.execute_script("arguments[0].setAttribute('id', 'lost')", element)
+# Element is gonna be found. Even with locator that is broken
+expect(driver.find_element(xpath: "//*[@id='element']").text).to eq "Text"
+driver.quit
 ```
 
-### 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
+When locatine sees some locator for the first time it is not only returning the element& It is collecting some info about it. As the result if locator will suddenly become broken locatine will make an attempt to find the element using the data collected.
 
-### return_locator
+### Magic comments
 
-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.
+If the usual locator only is provided locatine will treat it like a name for element. But if you want you can force locatine to remember it by name defined by you.
 
-### collection
+Just add name at the end of xpath like ['*name*'] or like /\**name*\*/ after css selector. For example:
 
-if true array of elements will be returned. If false only the one element (the first one found) will be returned.
+```ruby
+element = driver.find_element(xpath: "//*[@id='element']['test element']")
+element = driver.find_element(css: "#element/*test element*/")
+```
 
-### tolerance
+**NOTE! Those locators are valid.  If you will switch back to selenium-webdriver it will work normally. The 'test element' text will be treated like a comment that is not affecting the locator body.**
 
-You can state custom tolerance for the element.
+Once defined with name it can be called without locator part at all:
 
-### exact
+```ruby
+element = driver.find_element(xpath: "['test element']")
+element = driver.find_element(css: "/*test element*/")
+```
 
-It is disabling attempts to find element by advanced algorithms. If locator is provided find method will use only locator. If there is no locator only the basic search will be performed.
+**NOTE! Locators above will work only with locatine!**
 
-### no_fail
+### Dynamic locators
 
-no_fail option that will work for that search only.
+Always add names to dynamic locators. For example if you have some account_id which is new for every test and goes to an id attribute do
 
-### trusted//untrusted
+```ruby
+account_id #=> 1234567890
+element = driver.find_element(xpath: "//*[@id='#{account_id}']['test element']")
+element = driver.find_element(css: "##{account_id}/*test element*/")
+```
 
-You can set trusted elements just for search
+**NOTE! If there will be no name for the element that is changing locator for each run locatine will treat it like a new element each time. That will lead to overcrowding of your json file**
 
-## Scope
+### Zero tolerance shortcut
 
-If you want to define a whole bunch of elements at once you can do:
+If you need to check that element exists or not most probably you do not want locatine to look for the similar one. You can set zero tolerance (return only 100% same element) by adding word 'exactly' to the name.
 
 ```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
+element = driver.
+              find_element(xpath: "//*[@id='element']['exactly test element']")
+element = driver.find_element(css: "#element/*exactly test element*/")
 ```
 
-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.
+**NOTE! Zero tolerance will be used for that particular search only. Other searches will use session values**
 
-You can force use dynamic variables on define where is possible (same rules as for find):
+### Other ways to pass data to locatine
+
+There is another way to pass data to locatine. You can provide a json string as a comment.
 
 ```ruby
-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)
+require 'json' # That is to make everything a little bit simpler
+params = {name: "test element", tolerance: 0}.to_json
+#=> {\"name\":\"test element\",\"tolerance\":0}
+element = driver.find_element(xpath: "//*[@id='element'][#{params}']")
+element = driver.find_element(css: "#element/*#{params}*/")
 ```
 
-### Methods of scope
+**NOTE! Those requests will provide same results as previous because they have identical meaning**
 
-If you want to get a hash with all elements that are defined in scope:
+Like that you can set for each search any custom options (except json)
 
-```ruby
-# Lost elements will be found if possible!
-search.get_scope(name: "Name of scope").all
-# => {"element name": {
-#      elements: Array of Watir::Element,
-#      locator: valid xpath locator
-#      },
-#     "next element name":...
-#    }
-```
+For more information about possible options read [here](https://github.com/sseleznevqa/locatine#session)
+
+Additionally you can provide a custom locator inside of the comment json string.
 
-If you want to check presence of all elements:
+We are using 'json' library to make json string here.
 
 ```ruby
-# Will raise an error if something lost!
-search.get_scope(name: "Name of scope").check
+require 'json'
+xpath_params = {name: "test element",
+                tolerance: 0,
+                locator: {using: "xpath", value: "//*[@id='element']"}}.to_json
+css_params = {name: "test element",
+              tolerance: 0,
+              locator: {using: "css selector", value: "#element"}}.to_json
+element = driver.find_element(xpath: "['#{xpath_params}']")
+element = driver.find_element(css: "/*#{css_params}*/")
 ```
 
-## Other ways to use find
+For more information about locators read about [locator strategies](https://www.w3.org/TR/webdriver/#locator-strategies)
 
-If the scope is set and you do not want to provide any additional options you can do:
+### locatine locator strategy
 
-```ruby
-s = Locatine::Search.new
-s.find("just name of element")
-```
+Locatine also provides its own locator strategy == 'locatine'. In order to use it you need to inject it to the code of selenium-webdriver implementation.
+
+See it's done for ruby [here](https://github.com/sseleznevqa/locatine/tree/master/spec/e2e_spec.rb#L5-L11)
 
-Also you can do:
+When it's done you can use:
 
 ```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"))
+require 'json'
+xpath_params = {name: "test element",
+                tolerance: 0,
+                locator: {using: "xpath", value: "//*[@id='element']"}}.to_json
+css_params = {name: "test element",
+              tolerance: 0,
+              locator: {using: "css selector", value: "#element"}}.to_json
+element = driver.find_element(locatine: xpath_params)
+element = driver.find_element(locatine: css_params)
+# As well as
+element = driver.find_element(locatine: "test element")
+# And also
+element = driver.find_element(locatine: "exactly test element")
 ```
 
-That may be helpful in case of migration from plain watir to watir + locatine
+### Locatine locators
 
-If you want to find collection of elements you can use:
+In some cases you can even forget about classic locators
 
-```ruby
-s = Locatine::Search.new
-s.collect("group of elements") # Will return an array
-# or
-s.collect(name: "group of elements")
+For example have element
+
+```html
+<input id="important" type="button" value="click me"></input>
 ```
 
-Also:
+Let's pretend that id == important is a uniq attribute for the page (it should be so). In that case you can do:
 
 ```ruby
-s.exact_collection(name: "something") == s.collect(exact: true, name: "something")
-s.exact(name: "something") == s.find(name: "something", exact: true)
-s.check(name: "something") == s.find(name: "something", tolerance: 0)
-s.check_collection(name: "something") == s.collect(name: "something", tolerance: 0)
+element = driver.find_element(css: "/*important input*/")
 ```
 
-## Using as a daemon
+Locatine will try to find it by those two words. If the id is really uniq it will return the desired element.
 
-Locatine daemon is a web server based on sinatra. You can run it from your code like:
+There is a [Locatine Name Helper chrome extension](https://chrome.google.com/webstore/detail/locatine-locator-helper/heeoaalghiamfjphdlieoblmodpcficg). This app is for creating good locatine locators (it is creating a pair - most uniq attribute value + tag for selected element, elements). Note that the app is an early draft. It's gonne be better with time.
 
-```ruby
-require 'locatine'
-Locatine::Daemon.set :port, 7733 #Your port goes here
-Locatine::Daemon.run!
-```
+**NOTE! Locatine locators case insensitive.**
 
-Also you can do it with terminal:
+**NOTE! Locatine does not count text while looking for element.**
 
-```bash
-locatine-daemon.rb -port=7733
-```
+**NOTE! Locatine tends to think that the last word of your locator is a tag**
 
-You can see a python3 example in the [example](https://github.com/sseleznevqa/locatine/tree/master/example) folder. Main idea is
+## Locatine daemon API
 
-1. Run daemon
-2. Ask daemon for the app path
-3. Run your browser with the app as extension
-4. Turn on the learn
-5. Provide data to the daemon for connect (browser name, session_id, connect url, proxy)
-6. Use API calls to teach daemon how to find elements
-7. After that you can start browser without the app
-8. Provide data for connect
-9. Now you can ask daemon to find your element via API call. And it will answer with a valid xpath you can use.
+When locatine-daemon is started it is reacting to several requests:
+Almost all post data should be transfered as a valid json.
 
-### API
+### GET to '/'
 
-#### GET call to /app
+Redirect to this page.
 
-returns path to locatine application in order to start chrome with it.
+### GET to '/locatine/stop'
 
-Example of response:
+Stops locatine-daemon
+
+Returns
 
 ```
-{"app": "/some/path/to/app"}
+{"result": "dead"}
 ```
 
-#### GET call to /stop
+### POST to '/locatine/session/%session_id%'
 
-stops Locatine daemon.
-
-Returns:
+Data to post (example):
 
 ```
-{"result": "dead"}
+"{\"json\":\"./daemon.json\"}"
 ```
 
-#### POST call to /connect
+That will force session with *%session_id%* number to read\write data using ./daemon.json file.
 
-allows Locatine Daemon to connect existing browser instance
+For more information about possible options read [here](https://github.com/sseleznevqa/locatine#session)
 
-POST data:
+Response:
 
 ```
-{'browser': 'chrome', 'session_id': session_id, 'url': 'http://whatever_is_browser_ip:port_opened_by_browser_for_selenium', 'proxy': 'optionally' }
+{ \"results\": {\"json\":\"./daemon.json\"} }
 ```
 
-Answer:
+### POST to '/wd/hub/session'
+
+Just the same rules as for [usual selenium session](https://www.w3.org/TR/webdriver/#new-session-0)
+
+The only change that you can set locatine defaults via providing it in desired capabilities like:
 
 ```
-{"result": "true"}
+{...
+"desiredCapabilities": {
+  ...
+  "locatine": {"json": "./daemon.json"},
+  ...
+  }
+}
 ```
 
-#### POST call to /set
+That will force new session to read\write data using ./daemon.json file.
 
-is to control options of locatine search. Sending to set data ==
+For more information about possible options read [here](https://github.com/sseleznevqa/locatine#session)
 
-```
-{"learn": "true"}
-```
+### POST to '/wd/hub/session/%session_id%/element'
 
-Answer:
+That will try to return element using %session_id%.
 
-```
-{"result": "true"}
-```
+Rules are the same as for [usual selenium call](https://www.w3.org/TR/webdriver/#find-element)
 
-is the same as
+But you can provide magic locator comments for xpath and css. Or use 'locatine' element retrieve strategy.
 
-```ruby
-search.learn = true
-```
+More information is [here](https://github.com/sseleznevqa/locatine#finding-elements)
 
-#### POST call to /lctr
+### POST to '/wd/hub/session/%session_id%/element/%element_id%/element'
 
-is to find and return locator of an element found by locatine
+That will try to return element under %element_id% using %session_id%.
 
-POST data just the same as for find or lctr method. It's like:
+Rules are the same as for [usual selenium call](https://www.w3.org/TR/webdriver/#find-element-from-element)
 
-```
-{"name": "some name", "scope": "Default", "exact": "false" ...}
-```
+But you can provide magic locator comments for xpath and css. Or use 'locatine' element retrieve strategy.
 
-Answer:
+More information is [here](https://github.com/sseleznevqa/locatine#finding-elements)
 
-```
-{"xpath": "//YOUR[@xpath='goes here']"}
-```
+### POST to '/wd/hub/session/%session_id%/elements'
 
-### GET /chromedriver || /geckodriver || /iedriver
+That will try to return element using %session_id%.
 
-returns path to the binary retrieved by locatine (using webdrivers gem)
+Rules are the same as for [usual selenium call](https://www.w3.org/TR/webdriver/#find-elements)
 
-Answer:
+But you can provide magic locator comments for xpath and css. Or use 'locatine' element retrieve strategy.
 
-```
-{"path": "path/to/the/binary"}
-```
+More information is [here](https://github.com/sseleznevqa/locatine#finding-elements)
 
-### POST call to /chromedriver || /geckodriver || /iedriver
+### POST to '/wd/hub/session/%session_id%/element/%element_id%/elements'
 
-is to force locatine to use your webdriver (for example for using old version of browser)
+That will try to return element under %element_id% using %session_id%.
 
-POST data:
+Rules are the same as for [usual selenium call](https://www.w3.org/TR/webdriver/#find-elements-from-element)
 
-```
-{"version": "2.46"}
-```
+But you can provide magic locator comments for xpath and css. Or use 'locatine' element retrieve strategy.
 
-Answer:
+More information is [here](https://github.com/sseleznevqa/locatine#finding-elements)
 
-```
-{"version": "2.46"}
-```
+### Other calls to /wd/hub...
+
+Any other call will be simply redirected to selenium webdriver hub.