onlyoffice_webdriver_wrapper 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf1d04d0d68408caeefbbbc278a3846e65eb13a48ff9a2f014c914688bda5989
-  data.tar.gz: fb5f54d8ba4cd4b948bb040e0bc8e735258d353df70b951445de5f4980d34a09
+  metadata.gz: 1ebf9c9735115888e5fbb9d4a696bb0c0fbaae159fd3d661b71ccc2e43bda1af
+  data.tar.gz: 0bd97159b92dff8cef5374cb6e26790b06781730c65ed3cd21df247c6df4593a
 SHA512:
-  metadata.gz: 5c9b65b7f3831919e103c38bac5536dc9962998f69c77dce6f2d2baec9927a57bdc20924806b56051df2c89161ffd02445c43f804d18d0f5adfd7555b92ae17d
-  data.tar.gz: 4e47f77df9c7f1b4310eb96c5359b63abf75302b2001ca480cd0506924293d9b4d79c986c673774ddcee6e3a43119c1be7c12304363916ed7dcca61c8a4a2d68
+  metadata.gz: b87aef54b209ef19aec2e69ac64cba31a1c82421aa8df9259626dc770aa8a09c6a2eb24b168cf6d7763f938da2f8f7e12a3ca640a5e0fb633d330eaebb782a05
+  data.tar.gz: d83bd8c45ffc17d4a8ca4554b6af2ed73b739c9b6c936ec94037343dbb5712b6f66de16799af39bbbb56325cd81073053e897217947d2568f2934ff4f9d453b6

data/lib/onlyoffice_webdriver_wrapper/dimensions.rb

@@ -15,6 +15,7 @@ module OnlyofficeWebdriverWrapper
     alias x left
     alias y top
 
+    # @return [String] String representation of Dimensions
     def to_s
       "Dimensions(left: #{@left}, top: #{@top})"
     end

data/lib/onlyoffice_webdriver_wrapper/helpers/chrome_helper.rb

@@ -7,6 +7,7 @@ module OnlyofficeWebdriverWrapper
   module ChromeHelper
     include ChromeVersionHelper
 
+    # @return [String] list of default Chrome command line switches
     DEFAULT_CHROME_SWITCHES = %w[--kiosk-printing
                                  --disable-gpu
                                  --disable-popup-blocking
@@ -14,6 +15,7 @@ module OnlyofficeWebdriverWrapper
                                  --no-sandbox
                                  test-type].freeze
 
+    # @return [Selenium::WebDriver::Chrome::Service] Instance of Chrome Service object
     def chrome_service
       @chrome_service ||= Selenium::WebDriver::Chrome::Service.new(path: chromedriver_path)
     end

data/lib/onlyoffice_webdriver_wrapper/helpers/firefox_helper.rb

@@ -3,6 +3,7 @@
 module OnlyofficeWebdriverWrapper
   # Module for working with firefox
   module FirefoxHelper
+    # @return [Selenium::WebDriver::Firefox::Service] Instance of Firefox Service object
     def firefox_service
       geckodriver = File.join(File.dirname(__FILE__), 'bin/geckodriver')
       @firefox_service ||= Selenium::WebDriver::Firefox::Service.new(path: geckodriver)

data/lib/onlyoffice_webdriver_wrapper/helpers/headless_helper/headless_screenshot_patch.rb

@@ -1,4 +1,9 @@
+# Monkey-patching class from `headless` gem
 class Headless
+  # Fix incorrect taking of screenshots
+  # @param [String] file_path Path to store screenshot
+  # @param [Hash] options Different options
+  # @return [void]
   def take_screenshot(file_path, options={})
     using = options.fetch(:using, :imagemagick)
     case using

data/lib/onlyoffice_webdriver_wrapper/helpers/headless_helper/headless_video_recorder.rb

@@ -22,7 +22,7 @@ module OnlyofficeWebdriverWrapper
       @record_video = false
     end
 
-    # @return [nil] stop catpure of file
+    # @return [nil] stop capture of file
     def stop_capture
       return unless record_video
 

data/lib/onlyoffice_webdriver_wrapper/helpers/headless_helper/real_display_tools.rb

@@ -3,12 +3,15 @@
 module OnlyofficeWebdriverWrapper
   # module for getting info about real display
   module RealDisplayTools
+    # @return [String] result of `xrandr` command output
     def xrandr_result
       result = `xrandr 2>&1`
       OnlyofficeLoggerHelper.log("xrandr answer: #{result}".delete("\n"))
       result
     end
 
+    # Check if any real display connected to system
+    # @return [Boolean] result of this check
     def real_display_connected?
       return true if OSHelper.mac?
 

data/lib/onlyoffice_webdriver_wrapper/helpers/headless_helper/ruby_helper.rb

@@ -3,12 +3,13 @@
 module OnlyofficeWebdriverWrapper
   # Module for check ruby info
   module RubyHelper
+    # @return [Boolean] If current ruby instance run in debug mode
     def debug?
       ENV['RUBYLIB'].to_s.include?('ruby-debug')
     end
 
     # Check if current os is 64 bit
-    # @return [True, False] result of comparision
+    # @return [True, False] result of check
     def os_64_bit?
       RUBY_PLATFORM.include?('_64')
     end

data/lib/onlyoffice_webdriver_wrapper/helpers/headless_helper.rb

@@ -38,6 +38,8 @@ module OnlyofficeWebdriverWrapper
       true
     end
 
+    # Start headless session
+    # @return [void]
     def start
       create_session = if real_display_connected?
                          should_start?
@@ -64,6 +66,8 @@ module OnlyofficeWebdriverWrapper
       start_capture
     end
 
+    # Stop current headless session
+    # @return [void]
     def stop
       return unless running?
 
@@ -72,10 +76,15 @@ module OnlyofficeWebdriverWrapper
       headless_instance.destroy
     end
 
+    # Check if headless session currently running
+    # @return [Boolean] result of this check
     def running?
       !headless_instance.nil?
     end
 
+    # Take a screenshot of current headless session
+    # @param [String] scr_path Path to store screenshot
+    # @return [void]
     def take_screenshot(scr_path = '/tmp/screenshot.png')
       return unless running?
 

data/lib/onlyoffice_webdriver_wrapper/name.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module OnlyofficeWebdriverWrapper
+  # Module to store name of this gem
   module Name
+    # @return [String] name of this gem
     STRING = 'onlyoffice_webdriver_wrapper'
   end
 end

data/lib/onlyoffice_webdriver_wrapper/version.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module OnlyofficeWebdriverWrapper
+  # Module for storing version data
   module Version
-    STRING = '0.21.0'
+    # @return [String] Current stable version of gem
+    STRING = '0.22.0'
   end
 end

data/lib/onlyoffice_webdriver_wrapper/webdriver/wait_until_methods.rb

@@ -6,6 +6,11 @@ module OnlyofficeWebdriverWrapper
     # @return [Integer] default timeout for wait element
     TIMEOUT_WAIT_ELEMENT = 15
 
+    # Wait until something happens
+    # @param [String] timeout How much to wait
+    # @param [String] message which message show if something happens
+    # @param [Boolean] wait_js should we wait for JavaScript actions
+    # @return [void]
     def wait_until(timeout = ::PageObject.default_page_wait, message = nil, wait_js: true, &block)
       tries ||= 3
       wait = Object::Selenium::WebDriver::Wait.new(timeout: timeout, message: message)
@@ -22,6 +27,11 @@ module OnlyofficeWebdriverWrapper
       webdriver_error('Wait until: rescuing from Stale Element error failed after 3 tries')
     end
 
+    # Wait until element is visible
+    # @param [String] xpath_name to find object
+    # @param [Integer] timeout How much to wait
+    # @raise [StandardError] error if element not found for timeout
+    # @return [void]
     def wait_until_element_visible(xpath_name, timeout = 15)
       wait_until_element_present(xpath_name)
       time = 0

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_alert_helper.rb

@@ -3,12 +3,14 @@
 module OnlyofficeWebdriverWrapper
   # Methods for working with alerts
   module WebdriverAlertHelper
+    # Confirm current alert
+    # @return [void]
     def alert_confirm
       @driver.switch_to.alert.accept if alert_exists?
     end
 
     # Check if alert exists
-    # @return [True, false]
+    # @return [Boolean]
     def alert_exists?
       @driver.switch_to.alert.text
       true

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_attributes_helper.rb

@@ -3,9 +3,11 @@
 module OnlyofficeWebdriverWrapper
   # Module with methods to work with attributes
   module WebdriverAttributesHelper
+    # Check if attribute of xpath is exists
+    # @param [String] xpath_name to find object
+    # @param [String] attribute name to check
+    # @return [Boolean] result of check
     def attribute_exist?(xpath_name, attribute)
-      exist = false
-
       element = xpath_name.is_a?(String) ? get_element(xpath_name) : xpath_name
       begin
         attribute_value = element.attribute(attribute)
@@ -16,6 +18,10 @@ module OnlyofficeWebdriverWrapper
       exist
     end
 
+    # Get attribute of element
+    # @param [String] xpath_name to find object
+    # @param [String] attribute to get
+    # @return [String] value of attribute
     def get_attribute(xpath_name, attribute)
       element = xpath_name.is_a?(Selenium::WebDriver::Element) ? xpath_name : get_element(xpath_name)
 
@@ -26,6 +32,10 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Get attributes of several elements
+    # @param [String] xpath_several_elements to find objects
+    # @param [String] attribute to get
+    # @return [Array<String>] list of attributes
     def get_attributes_of_several_elements(xpath_several_elements, attribute)
       elements = @driver.find_elements(:xpath, xpath_several_elements)
 
@@ -34,6 +44,12 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Get index of element from array with attribute value
+    # @param [String] xpath to find objects
+    # @param [String] attribute to check
+    # @param [String] value to compare
+    # @param [Boolean] only_visible ignore invisible elements unless only_visible
+    # @return [Integer] index of element or `0` if not found
     def get_index_of_elements_with_attribute(xpath, attribute, value, only_visible = true)
       get_elements(xpath, only_visible).each_with_index do |element, index|
         return (index + 1) if get_attribute(element, attribute).include?(value)

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_browser_log_helper.rb

@@ -3,6 +3,7 @@
 module OnlyofficeWebdriverWrapper
   # Methods for working with browser console logs
   module WebdriverBrowserLogHelper
+    # @return [Array] list of browser logs
     def browser_logs
       return [] if browser == :firefox # not implemented, see https://github.com/mozilla/geckodriver/issues/284
 

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_exceptions.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module OnlyofficeWebdriverWrapper
+  # Exception class if system is not supported
   class WebdriverSystemNotSupported < StandardError; end
 end

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_frame_methods.rb

@@ -14,11 +14,11 @@ module OnlyofficeWebdriverWrapper
       rescue Selenium::WebDriver::Error::NoSuchElementError
         OnlyofficeLoggerHelper.log('Raise NoSuchElementError in the select_frame method')
       rescue Exception => e
-        webdriver_error("Raise unkwnown exception: #{e}")
+        webdriver_error("Raise unknown exception: #{e}")
       end
     end
 
-    # Select top frame of browser (even if several subframes exists)
+    # Select top frame of browser (even if several sub-frames exists)
     # @return [nil]
     def select_top_frame
       @driver.switch_to.default_content

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_helper.rb

@@ -6,6 +6,10 @@ require 'tempfile'
 module OnlyofficeWebdriverWrapper
   # Some additional methods for webdriver
   module WebdriverHelper
+    # Make screenshot by system methods
+    # Works only on Linux
+    # @param [String] file_name to export screenshot
+    # @return [String] result of screenshot command execution
     def system_screenshot(file_name)
       `import -window root #{file_name}`
     end

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_js_methods.rb

@@ -29,6 +29,10 @@ module OnlyofficeWebdriverWrapper
       "document.evaluate(\"#{escaped_xpath}\", document, null, XPathResult.ANY_TYPE, null).iterateNext()"
     end
 
+    # Type to locator by javascript
+    # @param [String] xpath_name to find object where to type
+    # @param [String] text to type
+    # @return [void]
     def type_to_locator_by_javascript(xpath_name, text)
       escaped_text = text.gsub('\\', '\\\\\\\\').gsub('"', '\\"').gsub("\n", '\\n')
       execute_javascript("document.evaluate('#{xpath_name}', document, null, XPathResult.ANY_TYPE, null).iterateNext().value=\"#{escaped_text}\";")
@@ -52,7 +56,7 @@ module OnlyofficeWebdriverWrapper
       Dimensions.new(width, height)
     end
 
-    # Get object absolute postion from top left edge of screen
+    # Get object absolute position from top left edge of screen
     # @param xpath [Sting] xpath of object
     # @return [CursorPoint] position of element
     def object_absolute_position(xpath)
@@ -76,6 +80,7 @@ module OnlyofficeWebdriverWrapper
       execute_javascript('return window.jQuery.active;').zero?
     end
 
+    # @return [Boolean] Is document is ready, finished to be loading
     def document_ready?
       execute_javascript('return document.readyState;') == 'complete'
     end

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_navigation_methods.rb

@@ -8,6 +8,7 @@ module OnlyofficeWebdriverWrapper
     # @return [nil]
     def open(url)
       url = "http://#{url}" unless url.include?('http') || url.include?('file://')
+      ensure_url_available(url)
       @driver.navigate.to url
       sleep(1) # Correct wait for Page to init focus
       OnlyofficeLoggerHelper.log("Opened page: #{url}")
@@ -59,5 +60,22 @@ module OnlyofficeWebdriverWrapper
       cleanup_download_folder
       @browser_running = false
     end
+
+    private
+
+    # Fast check if url available
+    # @param [String] url to check
+    # @param [Integer] timeout for wait for page to load
+    # @raise [Net::ReadTimeout] exception if timeout happened
+    # @return [nil]
+    def ensure_url_available(url, timeout: 5)
+      return true unless url.start_with?('http://')
+
+      URI.parse(url).open(read_timeout: timeout,
+                          open_timeout: timeout).read
+    rescue StandardError => e
+      OnlyofficeLoggerHelper.log("Url: #{url} is not available with error `#{e}`")
+      raise Net::ReadTimeout, e
+    end
   end
 end

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_screenshot_helper.rb

@@ -18,6 +18,9 @@ module OnlyofficeWebdriverWrapper
       '/tmp/screenshot/WebdriverError'
     end
 
+    # Get screenshot of current windows and upload it to cloud storage
+    # @param [String] path_to_screenshot place to store local screenshot
+    # @return [String] url of public screenshot
     def get_screenshot_and_upload(path_to_screenshot = "#{screenshot_folder}/#{StringHelper.generate_random_string}.png")
       begin
         get_screenshot(path_to_screenshot)
@@ -37,6 +40,9 @@ module OnlyofficeWebdriverWrapper
       path_to_screenshot
     end
 
+    # Get screenshot of current window
+    # @param [String] path_to_screenshot place to store local screenshot
+    # @return [void]
     def get_screenshot(path_to_screenshot = "#{screenshot_folder}/#{StringHelper.generate_random_string}.png")
       screenshot_folder = File.dirname(path_to_screenshot)
       FileUtils.mkdir_p(screenshot_folder) unless File.directory?(screenshot_folder)
@@ -44,6 +50,9 @@ module OnlyofficeWebdriverWrapper
       OnlyofficeLoggerHelper.log("get_screenshot(#{path_to_screenshot})")
     end
 
+    # Make a screenshot by webdriver methods
+    # @param [String] screenshot_name random name for file
+    # @return [String] text string with screenshot file location
     def webdriver_screenshot(screenshot_name = SecureRandom.uuid)
       begin
         link = get_screenshot_and_upload("#{screenshot_folder}/#{screenshot_name}.png")
@@ -72,7 +81,7 @@ module OnlyofficeWebdriverWrapper
 
     # Publish screenshot
     # @param [String] path to file
-    # @return [String] publis internet link to file
+    # @return [String] public internet link to file
     def publish_screenshot(path)
       amazon_s3_wrapper.upload_file_and_make_public(path,
                                                     nil,

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_style_helper.rb

@@ -3,6 +3,10 @@
 module OnlyofficeWebdriverWrapper
   # Webdriver style helper
   module WebdriverStyleHelper
+    # Get style parameter of object
+    # @param [String] xpath to find object
+    # @param [String] parameter_name which parameter to get
+    # @return [String, nil] nil if there is no such param
     def get_style_parameter(xpath, parameter_name)
       get_attribute(xpath, 'style').split(';').each do |current_param|
         return /:\s(.*);?$/.match(current_param)[1] if current_param.include?(parameter_name)
@@ -21,6 +25,10 @@ module OnlyofficeWebdriverWrapper
 
     alias set_style_parameter set_style_attribute
 
+    # Show element by changing it css style
+    # @param [String] xpath to find object
+    # @param [Boolean] move_to_center should object be moved to center of screen
+    # @return [void]
     def set_style_show_by_xpath(xpath, move_to_center = false)
       execute_javascript("#{dom_element_by_xpath(xpath)}.style.display = 'block';")
       return unless move_to_center

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_tab_helper.rb

@@ -3,19 +3,28 @@
 module OnlyofficeWebdriverWrapper
   # Module for work with tabs
   module WebdriverTabHelper
+    # @return [Integer] Default timeout for waiting for element
     TIMEOUT_WAIT_ELEMENT = 15
 
+    # Create new tab
+    # @return [void]
     def new_tab
       execute_javascript('window.open()')
     end
 
+    # Resize current tab to specific size
+    # @param [Integer] width to set
+    # @param [Integer] height to set
+    # @return [void]
     def resize_tab(width, height)
       @driver.manage.window.resize_to(width, height)
       OnlyofficeLoggerHelper.log("Resize current window to #{width}x#{height}")
     end
 
+    # Switch to popup window
     # @param after_switch_timeout [Integer] wait after switch to window
     # non-zero to workaround bug with page load hanging up after switch
+    # @return [void]
     def switch_to_popup(after_switch_timeout: 3)
       counter = 0
       while tab_count < 2 && counter < 30
@@ -37,32 +46,44 @@ module OnlyofficeWebdriverWrapper
       tab_count
     end
 
-    def choose_tab(tab_number)
+    # Choose tab by it's number
+    # @param [Integer] tab_number to choose
+    # @param [Integer] timeout how much for this tab
+    # @raise [RuntimeError] error if tab not found
+    # @return [void]
+    def choose_tab(tab_number, timeout: TIMEOUT_WAIT_ELEMENT)
       counter = 0
-      while tab_count < 2 && counter < TIMEOUT_WAIT_ELEMENT
+      while tab_count < tab_number && counter < timeout
         sleep 1
         counter += 1
       end
-      webdriver_error("choose_tab: Tab number = #{tab_number} not found") if counter >= TIMEOUT_WAIT_ELEMENT
+      webdriver_error("choose_tab: Tab number = #{tab_number} not found") if counter >= timeout
       @driver.switch_to.window(@driver.window_handles[tab_number - 1])
     end
 
+    # Switch to first tab of chrome
+    # @return [void]
     def switch_to_main_tab
       @driver.switch_to.window(@driver.window_handles.first)
     end
 
+    # Close current active tab and switch to first one
+    # @return [void]
     def close_tab
       @driver.close
       sleep 1
       switch_to_main_tab
     end
 
+    # Wait for popup window, close it and return to first tab
+    # @return [void]
     def close_popup_and_switch_to_main_tab
       switch_to_popup
       close_tab
       switch_to_main_tab
     end
 
+    # @return [String] title of current tab
     def get_title_of_current_tab
       @driver.title
     end

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_type_helper.rb

@@ -3,17 +3,35 @@
 module OnlyofficeWebdriverWrapper
   # Class for helping with type stuff
   module WebdriverTypeHelper
+    # Type text to element
+    # @param [String] element to find object
+    # @param [String] text_to_send text to type
+    # @param [Boolean] clear_area should area be cleared
+    # @return [void]
     def type_text(element, text_to_send, clear_area = false)
       element = get_element(element)
       element.clear if clear_area
       element.send_keys(text_to_send)
     end
 
+    # Type text to element and select it
+    # @param [String] element to find object
+    # @param [String] text_to_send text to type
+    # @param [Boolean] clear_area should area be cleared
+    # @return [void]
     def type_text_and_select_it(element, text_to_send, clear_area = false)
       type_text(element, text_to_send, clear_area)
       text_to_send.length.times { element.send_keys %i[shift left] }
     end
 
+    # Type text to object
+    # @param [String] xpath_name to find object
+    # @param [String] text_to_send text to type
+    # @param [Boolean] clear_content should content be cleared
+    # @param [Boolean] click_on_it should object be clicked
+    # @param [Boolean] by_action type by `@driver.action` if true
+    # @param [Boolean] by_element_send_key use `element.send_keys` if true
+    # @return [void]
     def type_to_locator(xpath_name, text_to_send, clear_content = true, click_on_it = false, by_action = false, by_element_send_key = false)
       element = get_element(xpath_name)
       if clear_content
@@ -45,6 +63,12 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Type text to input
+    # @param [String] xpath_name to find object
+    # @param [String] text_to_send text to type
+    # @param [Boolean] clear_content should content be cleared
+    # @param [Boolean] click_on_it should object be clicked
+    # @return [void]
     def type_to_input(xpath_name, text_to_send, clear_content = false, click_on_it = true)
       element = get_element(xpath_name)
       if element.nil?
@@ -65,6 +89,11 @@ module OnlyofficeWebdriverWrapper
       element.send_keys text_to_send
     end
 
+    # Send keys to object
+    # @param [String] xpath_name to find object
+    # @param [String] text_to_send text to type
+    # @param [Boolean] by_action type by `@driver.action` if true
+    # @return [void]
     def send_keys(xpath_name, text_to_send, by_action = true)
       element = get_element(xpath_name)
       @driver.action.click(element).perform if @browser == :firefox
@@ -75,21 +104,36 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Type text to currently focused element
+    # @param [Array<String, Symbol>, String, Symbol] keys to send
+    # @param [Integer] count_of_times how much times to repeat
+    # @return [void]
     def send_keys_to_focused_elements(keys, count_of_times = 1)
       command = @driver.action.send_keys(keys)
       (count_of_times - 1).times { command = command.send_keys(keys) }
       command.perform
     end
 
+    # Press some specific key
+    # @param [String, Symbol] key to press
+    # @return [void]
     def press_key(key)
       @driver.action.send_keys(key).perform
     end
 
+    # Simulate pressed down key on object
+    # @param [String] xpath to find object
+    # @param [String, Symbol] key to press
+    # @return [void]
     def key_down(xpath, key)
       @driver.action.key_down(get_element(xpath), key).perform
       sleep(1) # for some reason quick key_down select text in control
     end
 
+    # Release pressed key from object
+    # @param [String] xpath to find object
+    # @param [String, Symbol] key to release
+    # @return [void]
     def key_up(xpath, key)
       @driver.action.key_up(get_element(xpath), key).perform
     end
@@ -99,6 +143,8 @@ module OnlyofficeWebdriverWrapper
     # Workaround for bug with typing with :control
     # See https://github.com/SeleniumHQ/selenium/issues/8179
     # for more details
+    # @param [String] text_to_send text to type
+    # @return [void]
     def webdriver_bug_8179_workaround(text_to_send)
       text_to_send = [text_to_send].flatten
 

data/lib/onlyoffice_webdriver_wrapper/webdriver/webdriver_user_agent_helper.rb

@@ -1,22 +1,26 @@
 # frozen_string_literal: true
 
 module OnlyofficeWebdriverWrapper
-  # Module for wokring with webdriver useragent
+  # Module for working with webdriver useragent
   module WebdriverUserAgentHelper
+    # @return [String] useragent for Android phone browser
     USERAGENT_ANDROID_PHONE = 'Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MDB08M) '\
                               'AppleWebKit/537.36 (KHTML, like Gecko) '\
                               'Chrome/51.0.2704.81 Mobile Safari/537.36'
+    # @return [String] useragent for iPhone browser
     USERAGENT_IPHONE = 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_3_2 like Mac OS X) '\
                        'AppleWebKit/601.1.46 (KHTML, like Gecko) '\
                        'Version/9.0 Mobile/13F69 Safari/601.1'
+    # @return [String] useragent for iPad Air 2 Safari browser
     USERAGENT_IPAD_AIR_2_SAFARI = 'Mozilla/5.0 (iPad; CPU OS 10_0 like Mac OS X) '\
                                   'AppleWebKit/602.1.50 (KHTML, like Gecko) '\
                                   'Version/10.0 Mobile/14A5346a Safari/602.1'
+    # @return [String] useragent for Nexus 10 Chrome browser
     USERAGENT_NEXUS_10_CHROME = 'Mozilla/5.0 (Linux; Android 4.3; Nexus 10 Build/JSS15Q) '\
                                 'AppleWebKit/537.36 (KHTML, like Gecko) '\
                                 'Chrome/48.0.2564.23 Safari/537.36'
 
-    # @return [String] user agent string for current device
+    # @return [String, nil] user agent string for current device
     def user_agent_for_device
       case @device
       when :desktop_linux

data/lib/onlyoffice_webdriver_wrapper/webdriver.rb

@@ -25,6 +25,7 @@ require_relative 'webdriver/webdriver_tab_helper'
 require_relative 'webdriver/webdriver_user_agent_helper'
 require_relative 'webdriver/webdriver_browser_log_helper'
 
+# Namespace of this gem
 module OnlyofficeWebdriverWrapper
   # noinspection RubyTooManyMethodsInspection, RubyInstanceMethodNamingConvention, RubyParameterNamingConvention
   class WebDriver
@@ -47,6 +48,7 @@ module OnlyofficeWebdriverWrapper
     include WebdriverTabHelper
     include WebdriverUserAgentHelper
     include WebdriverBrowserLogHelper
+    # @return [Integer] Default timeout for waiting to file to download
     TIMEOUT_FILE_DOWNLOAD = 100
     # @return [Array, String] default switches for chrome
     attr_accessor :driver
@@ -89,6 +91,9 @@ module OnlyofficeWebdriverWrapper
       @browser_running = true
     end
 
+    # Get element by it's xpath
+    # @param [String] object_identification xpath of object to find
+    # @return [Object, nil] nil if nothing found
     def get_element(object_identification)
       return object_identification unless object_identification.is_a?(String)
 
@@ -104,11 +109,19 @@ module OnlyofficeWebdriverWrapper
       get_elements(array_elements).map { |current_element| get_text(current_element) }
     end
 
+    # Select from list elements
+    # @param [String] value value to find object
+    # @param [Array<Object>] elements_value elements to check
+    # @return [void]
     def select_from_list_elements(value, elements_value)
       index = get_element_index(value, elements_value)
       elements_value[index].click
     end
 
+    # Get index of element by it's text
+    # @param [String] title to compare text
+    # @param [Array<Objects>] list_elements to find in which
+    # @return [Object, nil] nil if nothing found
     def get_element_index(title, list_elements)
       list_elements.each_with_index do |current, i|
         return i if get_text(current) == title
@@ -116,22 +129,36 @@ module OnlyofficeWebdriverWrapper
       nil
     end
 
+    # Get all options for combo box
+    # @param [String] xpath_name to find combobox
+    # @return [Array<String>] values
     def get_all_combo_box_values(xpath_name)
       @driver.find_element(:xpath, xpath_name).find_elements(tag_name: 'option').map { |el| el.attribute('value') }
     end
 
+    # Scroll list to specific element
+    # @param [String] list_xpath how to find this list
+    # @param [String] element_xpath to which we should scrolled
+    # @return [void]
     def scroll_list_to_element(list_xpath, element_xpath)
       execute_javascript("$(document.evaluate(\"#{list_xpath}\", document, null, XPathResult.ANY_TYPE, null).
           iterateNext()).jScrollPane().data('jsp').scrollToElement(document.evaluate(\"#{element_xpath}\",
           document, null, XPathResult.ANY_TYPE, null).iterateNext());")
     end
 
+    # Scroll list by pixel count
+    # @param [String] list_xpath how to detect this list
+    # @param [Integer] pixels how much to scroll
+    # @return [void]
     def scroll_list_by_pixels(list_xpath, pixels)
       execute_javascript("$(document.evaluate(\"#{list_xpath.tr('"', "'")}\", document, null, XPathResult.ANY_TYPE, null).iterateNext()).scrollTop(#{pixels})")
     end
 
     # Open dropdown selector, like 'Color Selector', which has no element id
     # @param [String] xpath_name name of dropdown list
+    # @param [Integer] horizontal_shift x value
+    # @param [Integer] vertical_shift y value
+    # @return [void]
     def open_dropdown_selector(xpath_name, horizontal_shift = 30, vertical_shift = 0)
       element = get_element(xpath_name)
       if @browser == :firefox || @browser == :safari
@@ -145,12 +172,22 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Perform an action on coordinate
+    # @param [String] xpath_name to find element
+    # @param [Integer] right_by x coordinate
+    # @param [Integer] down_by y coordinate
+    # @param [Symbol] action to perform
+    # @param [Integer] times how much times to repeat
+    # @return [void]
     def action_on_locator_coordinates(xpath_name, right_by, down_by, action = :click, times = 1)
       wait_until_element_visible(xpath_name)
       element = @driver.find_element(:xpath, xpath_name)
       (0...times).inject(@driver.action.move_to(element, right_by.to_i, down_by.to_i)) { |acc, _elem| acc.send(action) }.perform
     end
 
+    # Check if element present on page
+    # @param [String] xpath_name to find element
+    # @return [Boolean] result of check
     def element_present?(xpath_name)
       case xpath_name
       when PageObject::Elements::Element
@@ -165,6 +202,9 @@ module OnlyofficeWebdriverWrapper
       false
     end
 
+    # Get first visible element from several
+    # @param [String] xpath_name to find several objects
+    # @return [Object] first visible element
     def get_element_by_display(xpath_name)
       @driver.find_elements(:xpath, xpath_name).each do |element|
         return element if element.displayed?
@@ -186,6 +226,10 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Get array of webdriver object by xpath
+    # @param [String] objects_identification object to find
+    # @param [Boolean] only_visible return invisible if true
+    # @return [Array, Object] list of objects
     def get_elements(objects_identification, only_visible = true)
       return objects_identification if objects_identification.is_a?(Array)
 
@@ -198,6 +242,9 @@ module OnlyofficeWebdriverWrapper
       elements
     end
 
+    # Check if element visible on page
+    # @param [String] xpath_name element to find
+    # @return [Boolean] result of check
     def element_visible?(xpath_name)
       if xpath_name.is_a?(PageObject::Elements::Element) # PageObject always visible
         true
@@ -225,12 +272,13 @@ module OnlyofficeWebdriverWrapper
       end
       false
     rescue Exception => e
-      webdriver_error("Raise unkwnown exception: #{e}")
+      webdriver_error("Raise unknown exception: #{e}")
     end
 
     # Get text of current element
     # @param [String] xpath_name name of xpath
-    # @param [true, false] wait_until_visible wait until element visible [@default = true]
+    # @param [Boolean] wait_until_visible wait until element visible
+    # @return [String] result string
     def get_text(xpath_name, wait_until_visible = true)
       wait_until_element_visible(xpath_name) if wait_until_visible
 
@@ -243,10 +291,18 @@ module OnlyofficeWebdriverWrapper
       end
     end
 
+    # Get text from several elements
+    # @param [String] xpath_several_elements to find objects
+    # @return [Array<String>] text of those elements
     def get_text_of_several_elements(xpath_several_elements)
       @driver.find_elements(:xpath, xpath_several_elements).map { |element| element.text unless element.text == '' }.compact
     end
 
+    # Select value of combo box
+    # @param [String] xpath_name to find combobox
+    # @param [String] select_value to select
+    # @param [Symbol] select_by select type
+    # @return [void]
     def select_combo_box(xpath_name, select_value, select_by = :value)
       wait_until_element_visible(xpath_name)
       option = Selenium::WebDriver::Support::Select.new(get_element(xpath_name))
@@ -263,6 +319,11 @@ module OnlyofficeWebdriverWrapper
       @driver.execute_script('return document.documentElement.innerHTML;')
     end
 
+    # Raise an error, making a screenshot before it
+    # @param [String, Object] exception class to raise
+    # @param [String] error_message to raise
+    # @raise [Object] specified exception
+    # @return [void]
     def webdriver_error(exception, error_message = nil)
       if exception.is_a?(String) # If there is no error_message
         error_message = exception
@@ -273,6 +334,11 @@ module OnlyofficeWebdriverWrapper
       raise exception, "#{error_message}\n\nPage address: #{current_url}\n\nError #{webdriver_screenshot}"
     end
 
+    # Wait for file to be downloaded
+    # @param [String] file_name to wait for download
+    # @param [Integer] timeout to wait for file to download
+    # @raise [StandardError] error if something happened and file not downloaded
+    # @return [String] full file name of downloaded file
     def wait_file_for_download(file_name, timeout = TIMEOUT_FILE_DOWNLOAD)
       full_file_name = "#{@download_directory}/#{file_name}"
       full_file_name = file_name if file_name[0] == '/'
@@ -291,7 +357,7 @@ module OnlyofficeWebdriverWrapper
     def self.clean_up(forced = false)
       return unless OnlyofficeFileHelper::LinuxHelper.user_name.include?('nct-at') ||
                     OnlyofficeFileHelper::LinuxHelper.user_name.include?('ubuntu') ||
-                    forced == true
+                    forced
 
       OnlyofficeFileHelper::LinuxHelper.kill_all('chromedriver')
       OnlyofficeFileHelper::LinuxHelper.kill_all('geckodriver')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: onlyoffice_webdriver_wrapper
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - ONLYOFFICE
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-10 00:00:00.000000000 Z
+date: 2021-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: headless
@@ -243,6 +243,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.20
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.20
 description: ONLYOFFICE Webdriver Wrapper Gem. Used in QA
 email:
 - shockwavenn@gmail.com