async-webdriver 0.1.1 → 0.2.0

data/lib/async/webdriver/element.rb

@@ -1,20 +1,273 @@
-require "selenium-webdriver"
-module Async
-  module Webdriver
-    class Element
-      def initialize(json:, connection:)
-        @id = json.fetch "ELEMENT"
-        @element_connection = ConnectionPath.new "element/#{@id}", connection: connection
-      end
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
 
-      def tag_name
-        @element_connection.call method: "get", path: "name"
-        value
-      end
+require_relative 'request_helper'
 
-      def text
-        @element_connection.call method: "get", path: "text"
-      end
-    end
-  end
+require_relative 'scope'
+
+module Async
+	module WebDriver
+		# An element represents a DOM element. This class is used to interact with the DOM.
+		#
+		# ``` ruby
+		# element = session.find_element(:css, "main#content")
+		# element.click
+		# ```
+		class Element
+			# Attributes associated with an element.
+			class Attributes
+				include Enumerable
+				
+				def initialize(element)
+					@element = element
+					@keys = nil
+				end
+				
+				# Get the value of an attribute.
+				# @parameter name [String] The name of the attribute.
+				# @returns [Object] The value of the attribute with the given name.
+				def [](name)
+					@element.attribute(name)
+				end
+				
+				# Set the value of an attribute.
+				# @parameter name [String] The name of the attribute.
+				# @parameter value [Object] The value of the attribute.
+				def []=(name, value)
+					@element.set_attribute(name, value)
+				end
+				
+				# Get the names of all attributes.
+				def keys
+					@element.execute("return this.getAttributeNames()")
+				end
+				
+				# Check if an attribute exists.
+				# @parameter name [String] The name of the attribute.
+				# @returns [Boolean] True if the attribute exists.
+				def key?(name)
+					@element.execute("return this.hasAttribute(...arguments)", name)
+				end
+				
+				# Iterate over all attributes.
+				# @yields {|name, value| ...} The name and value of each attribute.
+				# 	@parameter name [String] The name of the attribute.
+				# 	@parameter value [Object] The value of the attribute.
+				def each(&block)
+					return to_enum unless block_given?
+					
+					keys.each do |key|
+						yield key, self[key]
+					end
+				end
+			end
+			
+			# Initialize the element.
+			# @parameter session [Session] The session the element belongs to.
+			# @parameter id [String] The element identifier.
+			def initialize(session, id)
+				@session = session
+				@delegate = session.delegate
+				@id = id
+				
+				@attributes = nil
+				@properties = nil
+			end
+			
+			# @returns [Hash] The JSON representation of the element.
+			def as_json
+				{ELEMENT_KEY => @id}
+			end
+			
+			# @returns [String] The JSON representation of the element.
+			def to_json(...)
+				as_json.to_json(...)
+			end
+			
+			# @attribute [Session] The session the element belongs to.
+			attr :session
+			
+			# @attribute [Protocol::HTTP::Middleware] The underlying HTTP client (or wrapper).
+			attr :delegate
+			
+			# @attribute [String] The element identifier.
+			attr :id
+			
+			# 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
+					"/session/#{@session.id}/element/#{@id}/#{path}"
+				else
+					"/session/#{@session}/element/#{@id}"
+				end
+			end
+			
+			include RequestHelper
+			
+			# The current scope to use for making subsequent requests.
+			# @returns [Element] The element.
+			def current_scope
+				self
+			end
+			
+			include Scope::Alerts
+			include Scope::Cookies
+			include Scope::Elements
+			include Scope::Fields
+			include Scope::Printing
+			include Scope::ScreenCapture
+			
+			# Execute a script in the context of the element. `this` will be the element.
+			# @parameter script [String] The script to execute.
+			# @parameter arguments [Array] The arguments to pass to the script.
+			def execute(script, *arguments)
+				@session.execute("return (function(){#{script}}).call(...arguments)", self, *arguments)
+			end
+			
+			# Execute a script in the context of the element. `this` will be the element.
+			# @parameter script [String] The script to execute.
+			# @parameter arguments [Array] The arguments to pass to the script.
+			def execute_async(script, *arguments)
+				@session.execute_async("return (function(){#{script}}).call(...arguments)", self, *arguments)
+			end
+			
+			# Get the value of an attribute.
+			#
+			# Given an attribute name, e.g. `href`, this method will return the value of the attribute, as if you had executed the following JavaScript:
+			#
+			# ```js
+			# element.getAttribute("href")
+			# ```
+			#
+			# @parameter name [String] The name of the attribute.
+			# @returns [Object] The value of the attribute.
+			def attribute(name)
+				get("attribute/#{name}")
+			end
+			
+			# Set the value of an attribute.
+			# @parameter name [String] The name of the attribute.
+			# @parameter value [Object] The value of the attribute.
+			def set_attribute(name, value)
+				execute("this.setAttribute(...arguments)", name, value)
+			end
+			
+			# Get attributes associated with the element.
+			# @returns [Attributes] The attributes associated with the element.
+			def attributes
+				@attributes ||= Attributes.new(self)
+			end
+			
+			# Get the value of a property.
+			#
+			# Given a property name, e.g. `offsetWidth`, this method will return the value of the property, as if you had executed the following JavaScript:
+			#
+			# ```js
+			# element.offsetWidth
+			# ```
+			#
+			# @parameter name [String] The name of the property.
+			# @returns [Object] The value of the property.
+			def property(name)
+				get("property/#{name}")
+			end
+			
+			# Get the value of a CSS property.
+			#
+			# Given a CSS property name, e.g. `width`, this method will return the value of the property, as if you had executed the following JavaScript:
+			#
+			# ```js
+			# window.getComputedStyle(element).width
+			# ```
+			#
+			# @parameter name [String] The name of the CSS property.
+			# @returns [String] The value of the CSS property.
+			def css(name)
+				get("css/#{name}")
+			end
+			
+			# Get the text content of the element.
+			#
+			# This method will return the text content of the element, as if you had executed the following JavaScript:
+			#
+			# ```js
+			# element.textContent
+			# ```
+			#
+			# @returns [String] The text content of the element.
+			def text
+				get("text")
+			end
+			
+			# Get the element's tag name.
+			#
+			# This method will return the tag name of the element, as if you had executed the following JavaScript:
+			#
+			# ```js
+			# element.tagName
+			# ```
+			#
+			# @returns [String] The tag name of the element.
+			def tag_name
+				get("name")
+			end
+			
+			# A struct representing the size of an element.
+			Rectangle = Struct.new(:x, :y, :width, :height)
+			
+			# Get the element's bounding rectangle.
+			# @returns [Rectangle] The element's bounding rectangle.
+			def rectangle
+				get("rect").tap do |reply|
+					Rectangle.new(reply["x"], reply["y"], reply["width"], reply["height"])
+				end
+			end
+			
+			# Whether the element is selected OR checked.
+			# @returns [Boolean] True if the element is selected OR checked.
+			def selected?
+				get("selected")
+			end
+			
+			alias checked? selected?
+			
+			# Whether the element is enabled.
+			# @returns [Boolean] True if the element is enabled.
+			def enabled?
+				get("enabled")
+			end
+			
+			# Whether the element is displayed.
+			# @returns [Boolean] True if the element is displayed.
+			def displayed?
+				get("displayed")
+			end
+			
+			# Click the element.
+			def click
+				post("click")
+			end
+			
+			# Clear the element.
+			def clear
+				post("clear")
+			end
+			
+			# Send keys to the element. Simulates a user typing keys while the element is focused.
+			def send_keys(text)
+				post("value", {text: text})
+			end
+			
+			FRAME_TAGS = ["frame", "iframe"].freeze
+			
+			# Whether the element is a frame.
+			def frame?
+				FRAME_TAGS.include?(self.tag_name)
+			end
+		end
+	end
 end

data/lib/async/webdriver/error.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require_relative 'version'
+
+module Async
+	module WebDriver
+		# Error Code	HTTP Status	JSON Error Code	Description
+		# element click intercepted	400	element click intercepted	The Element Click command could not be completed because the element receiving the events is obscuring the element that was requested clicked.
+		# element not interactable	400	element not interactable	A command could not be completed because the element is not pointer- or keyboard interactable.
+		# insecure certificate	400	insecure certificate	Navigation caused the user agent to hit a certificate warning, which is usually the result of an expired or invalid TLS certificate.
+		# invalid argument	400	invalid argument	The arguments passed to a command are either invalid or malformed.
+		# invalid cookie domain	400	invalid cookie domain	An illegal attempt was made to set a cookie under a different domain than the current page.
+		# invalid element state	400	invalid element state	A command could not be completed because the element is in an invalid state, e.g. attempting to clear an element that isn’t both editable and resettable.
+		# invalid selector	400	invalid selector	Argument was an invalid selector.
+		# invalid session id	404	invalid session id	Occurs if the given session id is not in the list of active sessions, meaning the session either does not exist or that it’s not active.
+		# javascript error	500	javascript error	An error occurred while executing JavaScript supplied by the user.
+		# move target out of bounds	500	move target out of bounds	The target for mouse interaction is not in the browser’s viewport and cannot be brought into that viewport.
+		# no such alert	404	no such alert	An attempt was made to operate on a modal dialog when one was not open.
+		# no such cookie	404	no such cookie	No cookie matching the given path name was found amongst the associated cookies of the current browsing context’s active document.
+		# no such element	404	no such element	An element could not be located on the page using the given search parameters.
+		# no such frame	404	no such frame	A command to switch to a frame could not be satisfied because the frame could not be found.
+		# no such window	404	no such window	A command to switch to a window could not be satisfied because the window could not be found.
+		# no such shadow root	404	no such shadow root	The element does not have a shadow root.
+		# script timeout error	500	script timeout	A script did not complete before its timeout expired.
+		# session not created	500	session not created	A new session could not be created.
+		# stale element reference	404	stale element reference	A command failed because the referenced element is no longer attached to the DOM.
+		# detached shadow root	404	detached shadow root	A command failed because the referenced shadow root is no longer attached to the DOM.
+		# timeout	500	timeout	An operation did not complete before its timeout expired.
+		# unable to set cookie	500	unable to set cookie	A command to set a cookie’s value could not be satisfied.
+		# unable to capture screen	500	unable to capture screen	A screen capture was made impossible.
+		# unexpected alert open	500	unexpected alert open	A modal dialog was open, blocking this operation.
+		# unknown command	404	unknown command	A command could not be executed because the remote end is not aware of it.
+		# unknown error	500	unknown error	An unknown error occurred in the remote end while processing the command.
+		# unknown method	405	unknown method	The requested command matched a known URL but did not match any method for that URL.
+		# unsupported operation	500	unsupported operation	Indicates that a command that should have executed properly cannot be supported for some reason.
+
+		class Error < StandardError
+		end
+
+		# The Element Click command could not be completed because the element receiving the events is obscuring the element that was requested clicked.
+		class ElementClickInterceptedError < Error
+			CODE = "element click intercepted"
+		end
+
+		# A command could not be completed because the element is not pointer- or keyboard interactable.
+		class ElementNotInteractableError < Error
+			CODE = "element not interactable"
+		end
+
+		# Navigation caused the user agent to hit a certificate warning, which is usually the result of an expired or invalid TLS certificate.
+		class InsecureCertificateError < Error
+			CODE = "insecure certificate"
+		end
+
+		# The arguments passed to a command are either invalid or malformed.
+		class InvalidArgumentError < Error
+			CODE = "invalid argument"
+		end
+
+		# An illegal attempt was made to set a cookie under a different domain than the current page.
+		class InvalidCookieDomainError < Error
+			CODE = "invalid cookie domain"
+		end
+
+		# A command could not be completed because the element is in an invalid state, e.g. attempting to clear an element that isn’t both editable and resettable.
+		class InvalidElementStateError < Error
+			CODE = "invalid element state"
+		end
+
+		# Argument was an invalid selector.
+		class InvalidSelectorError < Error
+			CODE = "invalid selector"
+		end
+
+		# Occurs if the given session id is not in the list of active sessions, meaning the session either does not exist or that it’s not active.
+		class InvalidSessionIdError < Error
+			CODE = "invalid session id"
+		end
+
+		# An error occurred while executing JavaScript supplied by the user.
+		class JavaScriptError < Error
+			CODE = "javascript error"
+		end
+
+		# The target for mouse interaction is not in the browser’s viewport and cannot be brought into that viewport.
+		class MoveTargetOutOfBoundsError < Error
+			CODE = "move target out of bounds"
+		end
+
+		# An attempt was made to operate on a modal dialog when one was not open.
+		class NoSuchAlertError < Error
+			CODE = "no such alert"
+		end
+
+		# No cookie matching the given path name was found amongst the associated cookies of the current browsing context’s active document.
+		class NoSuchCookieError < Error
+			CODE = "no such cookie"
+		end
+
+		# An element could not be located on the page using the given search parameters.
+		class NoSuchElementError < Error
+			CODE = "no such element"
+		end
+
+		# A command to switch to a frame could not be satisfied because the frame could not be found.
+		class NoSuchFrameError < Error
+			CODE = "no such frame"
+		end
+
+		# A command to switch to a window could not be satisfied because the window could not be found.
+		class NoSuchWindowError < Error
+			CODE = "no such window"
+		end
+
+		# The element does not have a shadow root.
+		class NoSuchShadowRootError < Error
+			CODE = "no such shadow root"
+		end
+
+		# A script did not complete before its timeout expired.
+		class ScriptTimeoutError < Error
+			CODE = "script timeout error"
+		end
+
+		# A new session could not be created.
+		class SessionNotCreatedError < Error
+			CODE = "session not created"
+		end
+
+		# A command failed because the referenced element is no longer attached to the DOM.
+		class StaleElementReferenceError < Error
+			CODE = "stale element reference"
+		end
+
+		# A command failed because the referenced shadow root is no longer attached to the DOM.
+		class DetachedShadowRootError < Error
+			CODE = "detached shadow root"
+		end
+
+		# An operation did not complete before its timeout expired.
+		class TimeoutError < Error
+			CODE = "timeout"
+		end
+
+		# A command to set a cookie’s value could not be satisfied.
+		class UnableToSetCookieError < Error
+			CODE = "unable to set cookie"
+		end
+
+		# A screen capture was made impossible.
+		class UnableToCaptureScreenError < Error
+			CODE = "unable to capture screen"
+		end
+
+		# A modal dialog was open, blocking this operation.
+		class UnexpectedAlertOpenError < Error
+			CODE = "unexpected alert open"
+		end
+
+		# A command could not be executed because the remote end is not aware of it.
+		class UnknownCommandError < Error
+			CODE = "unknown command"
+		end
+
+		# An unknown error occurred in the remote end while processing the command.
+		class UnknownError < Error
+			CODE = "unknown error"
+		end
+
+		# The requested command matched a known URL but did not match any method for that URL.
+		class UnknownMethodError < Error
+			CODE = "unknown method"
+		end
+
+		# Indicates that a command that should have executed properly cannot be supported for some reason.
+		class UnsupportedOperationError < Error
+			CODE = "unsupported operation"
+		end
+
+		ERROR_CODES = {
+			ElementClickInterceptedError::CODE => ElementClickInterceptedError,
+			ElementNotInteractableError::CODE => ElementNotInteractableError,
+			InsecureCertificateError::CODE => InsecureCertificateError,
+			InvalidArgumentError::CODE => InvalidArgumentError,
+			InvalidCookieDomainError::CODE => InvalidCookieDomainError,
+			InvalidElementStateError::CODE => InvalidElementStateError,
+			InvalidSelectorError::CODE => InvalidSelectorError,
+			InvalidSessionIdError::CODE => InvalidSessionIdError,
+			JavaScriptError::CODE => JavaScriptError,
+			MoveTargetOutOfBoundsError::CODE => MoveTargetOutOfBoundsError,
+			NoSuchAlertError::CODE => NoSuchAlertError,
+			NoSuchCookieError::CODE => NoSuchCookieError,
+			NoSuchElementError::CODE => NoSuchElementError,
+			NoSuchFrameError::CODE => NoSuchFrameError,
+			NoSuchWindowError::CODE => NoSuchWindowError,
+			NoSuchShadowRootError::CODE => NoSuchShadowRootError,
+			ScriptTimeoutError::CODE => ScriptTimeoutError,
+			SessionNotCreatedError::CODE => SessionNotCreatedError,
+			StaleElementReferenceError::CODE => StaleElementReferenceError,
+			DetachedShadowRootError::CODE => DetachedShadowRootError,
+			TimeoutError::CODE => TimeoutError,
+			UnableToSetCookieError::CODE => UnableToSetCookieError,
+			UnableToCaptureScreenError::CODE => UnableToCaptureScreenError,
+			UnexpectedAlertOpenError::CODE => UnexpectedAlertOpenError,
+			UnknownCommandError::CODE => UnknownCommandError,
+			UnknownError::CODE => UnknownError,
+			UnknownMethodError::CODE => UnknownMethodError,
+			UnsupportedOperationError::CODE => UnsupportedOperationError,
+		}
+	end
+end

data/lib/async/webdriver/locator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'base64'
+
+module Async
+	module WebDriver
+		# A locator is used to find elements in the DOM.
+		#
+		# You can use the following convenience methods to create locators:
+		#
+		# ``` ruby
+		# Locator.css("main#content")
+		# Locator.xpath("//main[@id='content']")
+		# Locator.link_text("Home")
+		# Locator.partial_link_text("Ho")
+		# Locator.tag_name("main")
+		# ```
+		#
+		# You can also use the `Locator.wrap` method to create locators from a hash:
+		#
+		# ``` ruby
+		# Locator.wrap(css: "main#content")
+		# Locator.wrap(xpath: "//main[@id='content']")
+		# Locator.wrap(link_text: "Home")
+		# Locator.wrap(partial_link_text: "Ho")
+		# Locator.wrap(tag_name: "main")
+		# ```
+		#
+		# For more information, see: <https://w3c.github.io/webdriver/#locator-strategies>.
+		class Locator
+			# A convenience wrapper for specifying locators.
+			#
+			# You may provide either:
+			# 1. A locator instance, or
+			# 2. A single option `css:`, `xpath:`, `link_text:`, `partial_link_text:` or `tag_name:`, or 
+			# 3. A `using:` and `value:` option which will be used directly.
+			#
+			# @parameter locator [Locator] A locator to use directly.
+			# @option css [String] A CSS selector.
+			# @option xpath [String] An XPath expression.
+			# @option link_text [String] The exact text of a link.
+			# @option partial_link_text [String] A partial match for the text of a link.
+			# @option tag_name [String] The name of a tag.
+			# @option using [String] The locator strategy to use.
+			# @option value [String] The value to use with the locator strategy.
+			def self.wrap(locator = nil, **options)
+				if locator.is_a?(Locator)
+					locator
+				elsif css = options[:css]
+					css(css)
+				elsif xpath = options[:xpath]
+					xpath(xpath)
+				elsif link_text = options[:link_text]
+					link_text(link_text)
+				elsif partial_link_text = options[:partial_link_text]
+					partial_link_text(partial_link_text)
+				elsif tag_name = options[:tag_name]
+					tag_name(tag_name)
+				elsif using = options[:using]
+					new(using, options[:value])
+				else
+					raise ArgumentError, "Unable to interpret #{locator.inspect} with #{options.inspect}!"
+				end
+			end
+			
+			# A convenience wrapper for specifying CSS locators.
+			def self.css(css)
+				new("css selector", css)
+			end
+			
+			# A convenience wrapper for specifying link text locators.
+			def self.link_text(text)
+				new("link text", text)
+			end
+			
+			# A convenience wrapper for specifying partial link text locators.
+			def self.partial_link_text(text)
+				new("partial link text", text)
+			end
+			
+			# A convenience wrapper for specifying tag name locators.
+			def self.tag_name(name)
+				new("tag name", name)
+			end
+			
+			# A convenience wrapper for specifying XPath locators.
+			def self.xpath(xpath)
+				new("xpath", xpath)
+			end
+			
+			# Initialize the locator.
+			#
+			# A locator strategy must usually be one of the following:
+			# - `css selector`: Used to find elements via CSS selectors.
+			# - `link text`: Used to find anchor elements by their link text.
+			# - `partial link text`: Used to find anchor elements by their partial link text.
+			# - `tag name`: Used to find elements by their tag name.
+			# - `xpath`: Used to find elements via XPath expressions. 
+			#
+			# @parameter using [String] The locator strategy to use.
+			# @parameter value [String] The value to use with the locator strategy.
+			def initialize(using, value)
+				@using = using
+				@value = value
+			end
+			
+			# @attribute [String] The locator strategy to use.
+			attr :using
+			
+			# @attribute [String] The value to use with the locator strategy.
+			attr :value
+			
+			# @returns [Hash] A JSON representation of the locator.
+			def as_json
+				{using: @using, value: @value}
+			end
+			
+			# @returns [String] A JSON representation of the locator.
+			def to_json(...)
+				as_json.to_json(...)
+			end
+		end
+	end
+end