testa_appium_driver 0.1.0 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de964b80dabf1bc1507dcca4f28803c392f7b2da2cc6f8863479550ad55d49f2
-  data.tar.gz: 1555d6350706198af6a082cc0010295aabf07cebb7bc2527704c69fbbe96efd0
+  metadata.gz: ae8c1d10792a04508f11afa6d0b58380d60ba4f079eba2caed9707a5ae036e95
+  data.tar.gz: 47b0ca0facbc1cccaddc5a5efd4c2bcadd53f4ac4e8a66f6b4c2f89334cca8ee
 SHA512:
-  metadata.gz: f4a5426075f7a95d195e841f6b2043e0ac0401b4df7cefafab1c205f5fc5288c0cd56bdc5ab7cd64a55d1d7aa62b2b97467edc181c2c767ac8f01f0fa18161c0
-  data.tar.gz: 776de44ceaf20140dc3e414a6ee66b05bb7b74356196f9a644b4f88539c17fe8c68dcfce59bf2115bcda1e3424ee0aa54130f323a2d97c1ada405a2218027f59
+  metadata.gz: 62cf8d80a49626ffc88709afde4f408c535e53a25352058a36476c3b9791792b0f5cf17d45e3ac52c228b10909c4e67093c94d5dd6347147e3dce398b7cc18f4
+  data.tar.gz: 265b1b055eec368481790df7c50c78b9f803dbd64286d50b60e37fbe1b8bba6a004f9dadf0c07a6fa688f3ce19c0ba190b914aff97296c19214cbfa10b9be0c0

data/.gitignore

@@ -10,6 +10,7 @@
 # rspec failure tracking
 .rspec_status
 
+/.idea/deployment
 /.idea/workspace.xml
 /.idea/misc.xml
 Gemfile.lock

data/.idea/deployment.xml

@@ -1,21 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
-  <component name="PublishConfigData" autoUpload="On explicit save action" promptOnRemoteOverwrite="CHECK_CONTENT" serverName="supertesta.com" createEmptyFolders="true" remoteFilesAllowedToDisappearOnAutoupload="false" autoUploadExternalChanges="true">
+  <component name="PublishConfigData">
     <serverData>
       <paths name="supertesta.com">
         <serverdata>
           <mappings>
-            <mapping deploy="/testa_docker/path_data\testa_appium_driver" local="$PROJECT_DIR$" web="/" />
+            <mapping deploy="/testa_docker/path_data/testa_appium_driver" local="$PROJECT_DIR$" web="/" />
           </mappings>
-          <excludedPaths>
-            <excludedPath local="true" path="$PROJECT_DIR$/.idea" />
-            <excludedPath local="true" path="$PROJECT_DIR$/tmp" />
-            <excludedPath local="true" path="$PROJECT_DIR$/testa_appium_driver.iml" />
-            <excludedPath local="true" path="$PROJECT_DIR$/Gemfile.lock" />
-          </excludedPaths>
         </serverdata>
       </paths>
     </serverData>
-    <option name="myAutoUpload" value="ON_EXPLICIT_SAVE" />
   </component>
 </project>

data/.idea/webServers.xml

@@ -2,7 +2,7 @@
 <project version="4">
   <component name="WebServers">
     <option name="servers">
-      <webServer id="b1f6f214-0ed7-4869-998b-43dc6e5c154a" name="supertesta.com">
+      <webServer id="b1f6f214-0ed7-4869-998b-43dc6e5c154a" name="supertesta.com" url="http://something">
         <fileTransfer rootFolder="/ruby_apps" accessType="SFTP" host="supertesta.com" port="22" sshConfigId="ea45cb27-d516-4292-a1f7-430f02857685" sshConfig="Supertesta.com">
           <advancedOptions>
             <advancedOptions dataProtectionLevel="Private" keepAliveTimeout="0" passiveMode="true" shareSSLContext="true" />

data/README.md

@@ -1,52 +1,365 @@
-# TestaAppiumDriver
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library
-into a gem. Put your Ruby code in the file `lib/testa_appium_driver`. To experiment with that code, run `bin/console`
-for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'testa_appium_driver'
-```
-
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install testa_appium_driver
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
-also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
-version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/testa_appium_driver. This project
-is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to
-the [code of conduct](https://github.com/[USERNAME]/testa_appium_driver/blob/master/CODE_OF_CONDUCT.md).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the TestaAppiumDriver project's codebases, issue trackers, chat rooms and mailing lists is
-expected to follow
-the [code of conduct](https://github.com/[USERNAME]/testa_appium_driver/blob/master/CODE_OF_CONDUCT.md).
+# Testa Appium Driver
+
+Testa appium driver is a wrapper around the `ruby_lib_core` driver for appium. 
+It leverages all driver features and makes them simple and easy to use. 
+
+There are two key concepts in the testa driver
+#### 1. Elements are fetched only when needed
+It allows you to chain all the selectors and use the adjacent selectors without finding each element in the chain.
+For example `driver.linear_layout.list_view.view_group.button` will not execute any find element commands
+because element command is not given. If `click`, `send_keys` or any attribute method is added to the end of chain
+it will execute find_element before triggering the given element command.
+
+This concept allows you to store the selectors and reuse them later on. For example
+```ruby
+# element is not fetched yet
+my_fancy_progress_bar = driver.linear_layout.progress_bar
+
+puts my_fancy_progress_bar.text # will fetch the element and print the text (output: "You are on the first page")
+driver.button(text: "next page").click # go to the next page that has the same progress bar locator
+
+# will fetch the element again and print the text (output: "You are on the second page")
+# without TestaAppiumDriver, a Stale Object Exception would be thronw
+puts my_fancy_progress_bar.text 
+```
+
+
+#### 2. The Best element find / scroll strategy is automatically determined
+When given an element locator such as the progress_bar in the first concept, testa appium driver automatically determines
+the best find element strategy. The only thing to keep in mind is that you cannot mix strategy specific selectors. 
+Strategy specific selectors are `from_parent` for uiautomator or `parent`, `siblings` or `children` for xpath strategy.
+
+There are also multiple scroll strategies. Android supports both `uiautomator` and `w3c`, while iOS only supports `w3c` 
+scroll strategy. Uiautomator scroll strategy is more fluent and faster but it cannot be limited with single direction
+ element finding, and it does not have sufficient deadzone support.      
+
+
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'testa_appium_driver'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install testa_appium_driver
+    
+    
+For the android platform, make sure you are using the latest version of uiautomator server. Versions older than 4.21.2 have breaking issues.
+To get the latest server version execute:
+```shell script
+npm install appium-uiautomator2-server
+``` 
+And apks will be located in `./node_modules/appium-uiautomator2-server/apks`. Install both apks on the target device
+and make sure you have the `skipServerInstallation: true` capability when starting the driver.
+## Usage
+
+### Initialization
+```ruby
+opts = {
+    caps: {
+        platformName: "Android",
+        deviceName: "MyPhone",
+        app: "/path/to/your/apk",
+        udid: "your_phone_udid",
+        automationName: "uiautomator2",
+        skipServerInstallation: true, # if uiautomator server is manually installed
+        enableMultiWindows: true, # enables appium to see some otherwise "hidden" elements
+    }
+}
+driver = TestaAppiumDriver::Driver.new(opts)
+```
+
+#### Example 1 
+```ruby
+driver.linear_layout.button(id: "com.package.name:id/myElementId").click
+```
+Looks for the first linear layout and a button within the linear layout that has the provided id.
+Only 1 find element is executed with the resolved strategy (xpath or uiautomator):<br>
+underlying selectors:<br>
+xpath: `//android.widget.LinearLayout[1]//android.widget.Button[@resource-id="com.package.name:id/myElementId"]` <br>
+uiautomator: `new UiSelector().className("android.widget.LinearLayout").instance(0).childSelector(new UiSelector.className("android.widget.Button").resourceId("com.package.name:id/myElementId")));`<br>
+
+#### Example 2
+```ruby
+driver.linear_layout(id: "myShortIdExample").parent.text_view.wait_until_exists(10).text
+```
+Testa driver converts shorthand ids(that dont have :id/) to full ids
+by reading the current package under test and prepending it to the shorthand id. If you don't want to prepend the package
+name to the id, use = sign before the id, for example `id: "=idWithoutAPackageName"`.
+
+After adding the `parent` and `text_view` selectors and before retrieving the text value `wait_until_exists(10)` is used to
+wait up to 10 seconds for the element to appear in the page before exception is thrown.  
+
+underlying selectors:<br>
+xpath: `//android.widget.LinearLayout[@resource-id="com.package.name:id/myShortIdExample"][1]/../android.widget.TextView[1]` <br>
+uiautomator: `exception: parent selector cannot be used with uiautomator strategy`
+
+#### Example 3
+```ruby
+driver.list_view(top: 200).edit_text(text: "Looking for this text").scroll_to.align!(:bottom).enabled?
+```
+If the element cannot be found in the current view, `scroll_to` action will scroll to start of the scrollable container,
+and start scrolling to the end until the element is found or end is reached. Once found the `align!(:bottom)` command
+will align the element to the bottom of the scrollable container.
+Finally, once the element is scrolled into view and aligned, it will check if the edit_text is enabled.
+
+The scrollable container is resolved by looking the chain of selectors. 
+Selector can be a scrollable container if  `scrollable: true` or is one of the scrollable classes:
+- android.widget.ListView
+- android.widget.ScrollView
+- android.widget.HorizontalScrollView
+- androidx.recyclerview.widget.RecyclerView
+- XCUIElementTypeScrollView
+
+If the selector chain does not contain a scrollable container, a `driver.scrollabe` command will be executed to
+retrieve the first scrollable element in page.
+
+Scrollable selectors can accept the `top`, `right`, `bottom` and `left` parameters as deadzone to prevent that edge of the 
+container be used as scrollable surface.
+Custom views can also be used as scrollable containers with `as_scrollable` command. 
+The command marks the last selector as scrollable container.
+`driver.view(id: "myCustomScrollableView").as_scrollable(top: 200).page_down`
+
+
+
+
+
+#### Example 4
+```ruby
+driver.buttons.each do |element|
+  puts element.text
+end
+```
+The `each` method is one of the scrollable actions. It will start from the beginning of the scrollable container,
+in this case `driver.scrollable`, and find every button in the screen. It will scroll the page until the end of scrollable 
+container is reached and all buttons are found.
+
+
+
+#### Example 5 (Invalid combination)
+```ruby
+driver.frame_layout.from_parent.button(text: "My Cool text").siblings
+```
+This example demonstrates a invalid selector because it cannot be resolved with xpath nor uiautomator strategy.
+It will raise StrategyMixException because from_parent selector can only be used with uiautomator strategy and
+siblings selector can only be used with xpath strategy.
+
+
+# Methods 
+
+## Android
+### Class Selectors
+- element
+- elements
+- scrollable
+- scrollables
+- image_view
+- image_views
+- frame_layout
+- frame_layouts
+- linear_layout
+- linear_layouts
+- view
+- views
+- edit_text
+- edit_texts
+- view_group
+- view_groups
+- relative_layout
+- relative_layouts
+- recycler_view
+- recycler_views
+- button
+- buttons
+- image_button
+- image_buttons
+- horizontal_scroll_view
+- horizontal_scroll_views
+- scroll_view
+- scroll_views
+- view_pager
+- view_pagers
+- check_box
+- check_boxes
+- list_view
+- list_views
+- progress_bar
+- progress_bars
+- radio_button
+- radio_buttons
+- radio_group
+- radio_groups
+- search_view
+- search_views
+- spinner
+- spinners
+- toast
+- toasts
+- toolbar
+- toolbars
+- text_view
+- text_views
+
+Adjacent selectors
+- from_parent
+- parent
+- child
+- children
+- siblings
+- preceding_sibling
+- preceding_siblings
+- following_sibling
+- following_siblings
+
+
+Class Selector arguments
+- id
+- long_clickable
+- desc
+- class
+- text
+- package
+- checkable
+- checked
+- clickable
+- enabled
+- focusable
+- focused
+- index
+- selected
+- scrollable
+
+### Attributes
+- text
+- package
+- class_name
+- checkable?
+- checked?
+- clickable?
+- desc
+- enabled?
+- focusable?
+- focused?
+- long_clickable?
+- password?
+- id
+- scrollable?
+- selected?
+- displayed?
+- selection_start
+- selection_end
+- bounds
+- index
+
+# iOS
+## Type Selectors 
+- element
+- elements
+- window
+- windows
+- other
+- others
+- navigation_bar
+- navigation_bars
+- button
+- buttons
+- image
+- images
+- static_text
+- static_texts
+- scrollable
+- scrollables
+- scroll_view
+- scroll_views
+- table
+- tables
+- cell
+- cells
+
+Adjacent selectors
+- parent
+- child
+- children
+- siblings
+- preceding_sibling
+- preceding_siblings
+- following_sibling
+- following_siblings
+
+Type Selector arguments
+- enabled
+- type, class
+- label
+- width
+- height
+- visible
+- name, id
+- value
+
+
+## Attributes
+- accessibility_container
+- accessible?
+- class_name
+- enabled?
+- frame
+- index
+- label, text
+- name
+- rect, bounds
+- selected?
+- type
+- value
+- visible?
+
+# Scroll actions
+- each
+- align!
+- align_top!
+- align_bottom!
+- align_left!
+- align_right!
+- align
+- align_top
+- align_bottom
+- align_left
+- align_right
+- scroll_to
+- scroll_down_to
+- scroll_up_to
+- scroll_right_to
+- scroll_left_to
+- scroll_to_start
+- scroll_to_end
+- page_down
+- page_up
+- page_left
+- page_right
+- fling_down
+- fling_up
+- fling_left
+- fling_right
+- drag_to
+- drag_by
+
+# Helpers
+- as_scrollable
+- wait_until_exists
+- wait_while_exists
+- exists?
+- long_tap
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+