async-webdriver 0.1.1 → 0.2.0

data/lib/async/webdriver/request_helper.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require_relative 'version'
+require_relative 'error'
+
+module Async
+	module WebDriver
+		# Wraps the HTTP client to provide a consistent interface.
+		module RequestHelper
+			# The web element identifier is the string constant "element-6066-11e4-a52e-4f735466cecf".
+			ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf"
+			
+			# The content type for requests and responses.
+			CONTENT_TYPE = "application/json"
+			
+			# Headers to send with GET requests.
+			GET_HEADERS = [
+				["user-agent", "Async::WebDriver/#{VERSION}"],
+				["accept", CONTENT_TYPE],
+			].freeze
+			
+			# Headers to send with POST requests.
+			POST_HEADERS = GET_HEADERS + [
+				["content-type", "#{CONTENT_TYPE}; charset=UTF-8"],
+			].freeze
+			
+			# The path used for making requests to the web driver bridge.
+			# @parameter path [String | Nil] The path to append to the request path.
+			# @returns [String] The path used for making requests to the web driver bridge.
+			def request_path(path = nil)
+				if path
+					"/#{path}"
+				else
+					"/"
+				end
+			end
+			
+			# Unwrap JSON objects into their corresponding Ruby objects.
+			#
+			# If the value is a Hash and represents an element, then it will be unwrapped into an {ruby Element}.
+			#
+			# @parameter value [Hash | Array | Object] The value to unwrap.
+			# @returns [Object] The unwrapped value.
+			def unwrap_object(value)
+				if value.is_a?(Hash) and value.key?(ELEMENT_KEY)
+					Element.new(self.session, value[ELEMENT_KEY])
+				else
+					value
+				end
+			end
+			
+			# Used by `JSON.load` to unwrap objects.
+			def unwrap_objects(value)
+				case value
+				when Hash
+					value.transform_values!(&method(:unwrap_object))
+				when Array
+					value.map!(&method(:unwrap_object))
+				end
+			end
+			
+			# Extract the value from the reply.
+			#
+			# If the value is a Hash and represents an error, then it will be raised as an appropriate subclass of {ruby Error}.
+			#
+			# @parameter reply [Hash] The reply from the server.
+			# @returns [Object] The value of the reply.
+			def extract_value(reply)
+				value = reply["value"]
+				
+				if value.is_a?(Hash) and error = value["error"]
+					raise ERROR_CODES.fetch(error, Error), value["message"]
+				end
+				
+				if block_given?
+					return yield(reply)
+				else
+					return value
+				end
+			end
+			
+			# Make a GET request to the bridge and extract the value.
+			# @parameter path [String | Nil] The path to append to the request path.
+			# @returns [Object | Nil] The value of the reply.
+			def get(path)
+				Console.debug(self, "GET #{request_path(path)}")
+				response = @delegate.get(request_path(path), GET_HEADERS)
+				reply = JSON.load(response.read, self.method(:unwrap_objects))
+				
+				return extract_value(reply)
+			end
+			
+			# Make a POST request to the bridge and extract the value.
+			# @parameter path [String | Nil] The path to append to the request path.
+			# @parameter arguments [Hash | Nil] The arguments to send with the request.
+			# @returns [Object | Nil] The value of the reply.
+			def post(path, arguments = {}, &block)
+				Console.debug(self, "POST #{request_path(path)}", arguments: arguments)
+				response = @delegate.post(request_path(path), POST_HEADERS, arguments ? JSON.dump(arguments) : nil)
+				reply = JSON.load(response.read, self.method(:unwrap_objects))
+				
+				return extract_value(reply, &block)
+			end
+			
+			# Make a DELETE request to the bridge and extract the value.
+			# @parameter path [String | Nil] The path to append to the request path.
+			# @returns [Object | Nil] The value of the reply, if any.
+			def delete(path = nil)
+				Console.debug(self, "DELETE #{request_path(path)}")
+				response = @delegate.delete(request_path(path), POST_HEADERS)
+				reply = JSON.load(response.read, self.method(:unwrap_objects))
+				
+				return extract_value(reply)
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/alerts.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with alerts.
+			#
+			# ``` ruby
+			# session.dismiss_alert
+			# session.accept_alert
+			# session.alert_text
+			# session.set_alert_text("Hello, World!")
+			# ```
+			module Alerts
+				# Dismiss the current alert.
+				def dismiss_alert
+					session.post("alert/dismiss")
+				end
+				
+				# Accept the current alert.
+				def accept_alert
+					session.post("alert/accept")
+				end
+				
+				# Get the text of the current alert.
+				def alert_text
+					session.get("alert/text")
+				end
+				
+				# Set the text input of the current alert.
+				def set_alert_text(text)
+					session.post("alert/text", {text: text})
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/cookies.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with cookies.
+			module Cookies
+				# Get all cookies.
+				def cookies
+					session.get("cookie")
+				end
+				
+				# Get a cookie by name.
+				# @parameter name [String] The name of the cookie.
+				def cookie(name)
+					session.get("cookie/#{name}")
+				end
+				
+				# Add a cookie.
+				# @parameter name [String] The name of the cookie.
+				# @parameter value [String] The value of the cookie.
+				# @parameter options [Hash] Additional options.
+				def add_cookie(name, value, **options)
+					session.post("cookie", {name: name, value: value}.merge(options))
+				end
+				
+				# Delete a cookie by name.
+				# @parameter name [String] The name of the cookie.
+				def delete_cookie(name)
+					session.delete("cookie/#{name}")
+				end
+				
+				# Delete all cookies.
+				def delete_all_cookies
+					session.delete("cookie")
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/document.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with the document.
+			module Document
+				# Get the current document title.
+				# @returns [String] The document title.
+				def title
+					get("title")
+				end
+				
+				# Get the current document source.
+				# @returns [String] The document source.
+				def source
+					get("source")
+				end
+				
+				# Execute a script in the current document.
+				# @parameter script [String] The script to execute.
+				# @parameter arguments [Array] The arguments to pass to the script.
+				# @returns [Object] The result of the script.
+				def execute(script, *arguments)
+					post("execute/sync", {script: script, args: arguments})
+				end
+				
+				# Execute a script in the current document asynchronously.
+				# @parameter script [String] The script to execute.
+				# @parameter arguments [Array] The arguments to pass to the script.
+				# @returns [Object] The result of the script.
+				def execute_async(script, *arguments)
+					post("execute/async", {script: script, args: arguments})
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/elements.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'base64'
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for finding elements.
+			module Elements
+				# Find an element using the given locator. If no element is found, an exception is raised.
+				# @parameter locator [Locator] The locator to use.
+				# @returns [Element] The element.
+				# @raises [NoSuchElementError] If the element does not exist.
+				def find_element(locator)
+					current_scope.post("element", locator)
+				end
+				
+				# Find an element using the given CSS selector.
+				# @parameter css [String] The CSS selector to use.
+				# @returns [Element] The element.
+				# @raises [NoSuchElementError] If the element does not exist.
+				def find_element_by_css(css)
+					find_element({using: "css selector", value: css})
+				end
+				
+				# Find an element using the given link text.
+				# @parameter text [String] The link text to use.
+				# @returns [Element] The element.
+				# @raises [NoSuchElementError] If the element does not exist.
+				def find_element_by_link_text(text)
+					find_element({using: "link text", value: text})
+				end
+				
+				# Find an element using the given partial link text.
+				# @parameter text [String] The partial link text to use.
+				# @returns [Element] The element.
+				# @raises [NoSuchElementError] If the element does not exist.
+				def find_element_by_partial_link_text(text)
+					find_element({using: "partial link text", value: text})
+				end
+				
+				# Find an element using the given tag name.
+				# @parameter name [String] The tag name to use.
+				# @returns [Element] The element.
+				# @raises [NoSuchElementError] If the element does not exist.
+				def find_element_by_tag_name(name)
+					find_element({using: "tag name", value: name})
+				end
+				
+				# Find an element using the given XPath expression.
+				# @parameter xpath [String] The XPath expression to use.
+				# @returns [Element] The element.
+				# @raises [NoSuchElementError] If the element does not exist.
+				def find_element_by_xpath(xpath)
+					find_element({using: "xpath", value: xpath})
+				end
+				
+				# Find all elements using the given locator. If no elements are found, an empty array is returned.
+				# @parameter locator [Locator] The locator to use.
+				# @returns [Array(Element)] The elements.
+				def find_elements(locator)
+					current_scope.post("elements", locator)
+				end
+				
+				# Find all elements using the given CSS selector.
+				# @parameter css [String] The CSS selector to use.
+				# @returns [Array(Element)] The elements.
+				def find_elements_by_css(css)
+					find_elements({using: "css selector", value: css})
+				end
+				
+				# Find all elements using the given link text.
+				# @parameter text [String] The link text to use.
+				# @returns [Array(Element)] The elements.
+				def find_elements_by_link_text(text)
+					find_elements({using: "link text", value: text})
+				end
+				
+				# Find all elements using the given partial link text.
+				# @parameter text [String] The partial link text to use.
+				# @returns [Array(Element)] The elements.
+				def find_elements_by_partial_link_text(text)
+					find_elements({using: "partial link text", value: text})
+				end
+				
+				# Find all elements using the given tag name.
+				# @parameter name [String] The tag name to use.
+				# @returns [Array(Element)] The elements.
+				def find_elements_by_tag_name(name)
+					find_elements({using: "tag name", value: name})
+				end
+				
+				# Find all elements using the given XPath expression.
+				# @parameter xpath [String] The XPath expression to use.
+				# @returns [Array(Element)] The elements.
+				def find_elements_by_xpath(xpath)
+					find_elements({using: "xpath", value: xpath})
+				end
+				
+				# Find all children of the current element.
+				# @returns [Array(Element)] The children of the current element.
+				def children
+					find_elements_by_xpath("./child::*")
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/fields.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'base64'
+
+require_relative '../xpath'
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with forms and form fields.
+			module Fields
+				# Find a field with the given name.
+				# @parameter name [String] The name of the field.
+				# @returns [Element] The field.
+				# @raises [NoSuchElementError] If the field does not exist.
+				def find_field(name)
+					current_scope.find_element_by_xpath("//*[@name=#{XPath::escape(name)}]")
+				end
+				
+				# Fill in a field with the given name.
+				#
+				# Clears the field before filling it in.
+				#
+				# @parameter name [String] The name of the field.
+				# @parameter value [String] The value to fill in.
+				# @raises [NoSuchElementError] If the field does not exist.
+				def fill_in(name, value)
+					element = find_field(name)
+					
+					if element.tag_name == "input" || element.tag_name == "textarea"
+						element.clear
+					end
+					
+					element.send_keys(value)
+				end
+				
+				# Click a button with the given label.
+				# @parameter label [String] The label of the button.
+				# @raises [NoSuchElementError] If the button does not exist.
+				def click_button(label)
+					element = current_scope.find_element_by_xpath("//button[text()=#{XPath::escape(label)}] | //input[@type='submit' and @value=#{XPath::escape(label)}] | //input[@type='button' and @value=#{XPath::escape(label)}]")
+					
+					element.click
+				end
+				
+				# Check a checkbox with the given name.
+				#
+				# Does not modify the checkbox if it is already in the desired state.
+				#
+				# @parameter field_name [String] The name of the checkbox.
+				# @parameter value [Boolean] The value to set the checkbox to.
+				# @raises [NoSuchElementError] If the checkbox does not exist.
+				def check(field_name, value = true)
+					element = current_scope.find_element(xpath: "//input[@type='checkbox' and @name='#{field_name}']")
+					
+					if element.checked? != value
+						element.click
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/frames.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with frames.
+			#
+			# ``` ruby
+			# session.switch_to_frame(frame)
+			# session.switch_to_parent_frame
+			# ```
+			module Frames
+				# Switch to the given frame.
+				#
+				# @parameter frame [Element] The frame to switch to.
+				# @raises [NoSuchFrameError] If the frame does not exist.
+				def switch_to_frame(frame)
+					session.post("frame", {id: frame})
+				end
+				
+				# Switch back to the parent frame.
+				#
+				# You should use this method to switch back to the parent frame after switching to a child frame.
+				def switch_to_parent_frame
+					session.post("frame/parent")
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/navigation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'uri'
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for navigating the browser.
+			module Navigation
+				# Navigate to the given URL.
+				# @parameter url [String] The URL to navigate to.
+				def navigate_to(url)
+					session.post("url", {url: url})
+				end
+				
+				alias visit navigate_to
+				
+				# Get the current URL.
+				# @returns [String] The current URL.
+				def current_url
+					session.get("url")
+				end
+				
+				# Get the path component of the current URL.
+				# @returns [String] The current path.
+				def current_path
+					URI.parse(current_url).path
+				end
+				
+				# Navigate back in the browser history.
+				def navigate_back
+					session.post("back")
+				end
+				
+				# Navigate forward in the browser history.
+				def navigate_forward
+					session.post("forward")
+				end
+				
+				# Refresh the current page.
+				def refresh
+					session.post("refresh")
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/printing.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'base64'
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with printing.
+			module Printing
+				# Print the current page and return the result as a Base64 encoded string containing a PDF representation of the paginated document.
+				def print(page_ranges: nil, total_pages: nil)
+					reply = session.post("print", {pageRanges: page_ranges, totalPages: total_pages}.compact)
+					
+					return Base64.decode64(reply["value"])
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/screen_capture.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'base64'
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with screen capture.
+			module ScreenCapture
+				# Take a screenshot of the current page or element.
+				# @returns [String] The screenshot as a Base64 encoded string.
+				def screenshot
+					reply = current_scope.post("screenshot")
+					
+					return Base64.decode64(reply)
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope/timeouts.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Scope
+			# Helpers for working with timeouts.
+			#
+			# If your tests are failing because the page is not loading fast enough, you can increase the page load timeout:
+			#
+			# ``` ruby
+			# session.script_timeout = 1000 # 1 second
+			# session.implicit_wait_timeout = 10_000 # 10 seconds
+			# session.page_load_timeout = 60_000 # 60 seconds
+			# ```
+			module Timeouts
+				# Get the current timeouts.
+				# @returns [Hash] The timeouts.
+				def timeouts
+					session.get("timeouts")
+				end
+				
+				# The script timeout is the amount of time the driver should wait when executing JavaScript asynchronously.
+				# @returns [Integer] The timeout in milliseconds.
+				def script_timeout
+					timeouts["script"]
+				end
+				
+				# Set the script timeout.
+				# @parameter value [Integer] The timeout in milliseconds.
+				def script_timeout=(value)
+					session.post("timeouts", {script: value})
+				end
+				
+				# The implicit wait timeout is the amount of time the driver should wait when searching for elements.
+				# @returns [Integer] The timeout in milliseconds.
+				def implicit_wait_timeout
+					timeouts["implicit"]
+				end
+				
+				# Set the implicit wait timeout.
+				# @parameter value [Integer] The timeout in milliseconds.
+				def implicit_wait_timeout=(value)
+					session.post("timeouts", {implicit: value})
+				end
+				
+				# The page load timeout is the amount of time the driver should wait when loading a page.
+				# @returns [Integer] The timeout in milliseconds.
+				def page_load_timeout
+					timeouts["pageLoad"]
+				end
+				
+				# Set the page load timeout.
+				# @parameter value [Integer] The timeout in milliseconds.
+				def page_load_timeout=(value)
+					session.post("timeouts", {pageLoad: value})
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/scope.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require_relative 'scope/alerts'
+require_relative 'scope/cookies'
+require_relative 'scope/document'
+require_relative 'scope/elements'
+require_relative 'scope/fields'
+require_relative 'scope/frames'
+require_relative 'scope/navigation'
+require_relative 'scope/printing'
+require_relative 'scope/screen_capture'
+require_relative 'scope/timeouts'