async-webdriver 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10af3bfaf7f567c54aaa67fc66865b60e8797756762fb13b3e7f32701d234de5
-  data.tar.gz: 91a457bdbc9343cd41eb4c3ba9d63a9f81b571c1f91ffc5c315b81130c0c1d76
+  metadata.gz: ee23c04114676fa39b6838b560ad843f0d011e8c89ac1de1038c66c2f7bd5e26
+  data.tar.gz: aa95efc428c3cdfcb362c8a9f6fbc80aaa4cec6258630adb2f057479ba051537
 SHA512:
-  metadata.gz: 226ca38936a96df93d97b55ed583316a7651b528f70ac9a246e3af784959d6df1137e077903b92e94b0613a792a58ed80800f31c9cd7f4dbd518c211ff099adb
-  data.tar.gz: b1db3afdbaaaef09eb54c495a4d31bcb80a80dfe88bd25d12f6dfae68b4c3dffadc1d24f934f76dc5c643cb3b4d2e225962a91e34a2bfbd8a7eaef46fe3325fb
+  metadata.gz: bf32864d5c72d2529151f4de5f1f72d6e4a5a3731d0598e49df758d97371f176ec34504d9922d6f56499855c9d21726fb7fba641b08c19f2ae084960a35ec90f
+  data.tar.gz: 67f0fd5bdba22e79cba73c2db37e69da65ddc3dc22a8603584a59d1cae158902ac1ca501a7d80304683e56f831aa621ca852acd3b31079c4c7a2b19d2a36711c

data/lib/async/webdriver/bridge/chrome.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require_relative 'generic'
+require_relative 'process_group'
+
+module Async
+	module WebDriver
+		module Bridge
+			# A bridge to the Chrome browser using `chromedriver`.
+			#
+			# ``` ruby
+			# begin
+			# 	bridge = Async::WebDriver::Bridge::Chrome.start
+			# 	client = Async::WebDriver::Client.open(bridge.endpoint)
+			# ensure
+			# 	bridge&.close
+			# end
+			# ```
+			class Chrome < Generic
+				# Create a new bridge to Chrome.
+				# @parameter path [String] The path to the `chromedriver` executable.
+				def initialize(path: "chromedriver")
+					super()
+					
+					@path = path
+					@process = nil
+				end
+				
+				# @returns [String] The version of the `chromedriver` executable.
+				def version
+					::IO.popen([@path, "--version"]) do |io|
+						return io.read
+					end
+				rescue Errno::ENOENT
+					return nil
+				end
+				
+				# @returns [Array(String)] The arguments to pass to the `chromedriver` executable.
+				def arguments
+					[
+						"--port=#{self.port}",
+					].compact
+				end
+				
+				# Start the driver.
+				def start
+					@process ||= ProcessGroup.spawn(@path, *arguments)
+					
+					super
+				end
+				
+				# Close the driver.
+				def close
+					super
+					
+					if @process
+						@process.close
+						@process = nil
+					end
+				end
+				
+				# The default capabilities for the Chrome browser which need to be provided when requesting a new session.
+				# @parameter headless [Boolean] Whether to run the browser in headless mode.
+				# @returns [Hash] The default capabilities for the Chrome browser.
+				def default_capabilities(headless: true)
+					{
+						alwaysMatch: {
+							browserName: "chrome",
+							"goog:chromeOptions": {
+								args: [headless ? "--headless" : nil].compact,
+							}
+						},
+					}
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/bridge/firefox.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require_relative 'generic'
+require_relative 'process_group'
+
+module Async
+	module WebDriver
+		module Bridge
+			# A bridge to the Firefox browser using `geckodriver`.
+			#
+			# ``` ruby
+			# begin
+			# 	bridge = Async::WebDriver::Bridge::Firefox.start
+			# 	client = Async::WebDriver::Client.open(bridge.endpoint)
+			# ensure
+			# 	bridge&.close
+			# end
+			class Firefox < Generic
+				# Create a new bridge to Firefox.
+				# @parameter path [String] The path to the `geckodriver` executable.
+				def initialize(path: "geckodriver")
+					super()
+					
+					@path = path
+					@process = nil
+				end
+				
+				# @returns [String] The version of the `geckodriver` executable.
+				def version
+					::IO.popen([@path, "--version"]) do |io|
+						return io.read
+					end
+				rescue Errno::ENOENT
+					return nil
+				end
+				
+				# @returns [Array(String)] The arguments to pass to the `geckodriver` executable.
+				def arguments
+					[
+						"--port", self.port.to_s,
+					].compact
+				end
+				
+				# Start the driver.
+				def start
+					@process ||= ProcessGroup.spawn(@path, *arguments)
+					
+					super
+				end
+				
+				# Close the driver.
+				def close
+					super
+					
+					if @process
+						@process.close
+						@process = nil
+					end
+				end
+				
+				# The default capabilities for the Firefox browser which need to be provided when requesting a new session.
+				# @parameter headless [Boolean] Whether to run the browser in headless mode.
+				# @returns [Hash] The default capabilities for the Firefox browser.
+				def default_capabilities(headless: true)
+					{
+						alwaysMatch: {
+							browserName: "firefox",
+							"moz:firefoxOptions": {
+								"args": [headless ? "-headless" : nil].compact,
+							}
+						}
+					}
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/bridge/generic.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require 'socket'
+require 'async/http/endpoint'
+require 'async/http/client'
+
+module Async
+	module WebDriver
+		module Bridge
+			# Generic W3C WebDriver implementation.
+			class Generic
+				# Start the driver and return a new instance.
+				def self.start(**options)
+					self.new(**options).tap do |bridge|
+						bridge.start
+					end
+				end
+				
+				# Initialize the driver.
+				# @parameter port [Integer] The port to listen on.
+				def initialize(port: nil)
+					@port = port
+					@status = nil
+				end
+				
+				# @attribute [String] The status of the driver after a connection has been established.
+				attr :status
+				
+				# @returns [String | Nil] The version of the driver.
+				def version
+					nil
+				end
+				
+				# @returns [Boolean] Is the driver supported/working?
+				def supported?
+					version != nil
+				end
+				
+				# Start the driver.
+				# @parameter retries [Integer] The number of times to retry before giving up.
+				def start(retries: 100)
+					Console.debug(self, "Waiting for driver to start...")
+					count = 0
+					
+					Async::HTTP::Client.open(endpoint) do |client|
+						begin
+							response = client.get("/status")
+							@status = JSON.parse(response.read)["value"]
+							Console.debug(self, "Successfully connected to driver.", status: @status)
+						rescue Errno::ECONNREFUSED
+							if count < retries
+								count += 1
+								sleep(0.001 * count)
+								Console.debug(self, "Driver not ready, retrying...")
+								retry
+							else
+								raise
+							end
+						end
+					end
+				end
+				
+				# Close the driver and any associated resources.
+				def close
+				end
+				
+				# Generate a port number for the driver to listen on if it was not specified.
+				# @returns [Integer] The port the driver is listening on.
+				def port
+					unless @port
+						address = ::Addrinfo.tcp("localhost", 0)
+						address.bind do |socket|
+							# We assume that it's unlikely the port will be reused any time soon...
+							@port = socket.local_address.ip_port
+						end
+					end
+					
+					return @port
+				end
+				
+				# @returns [Async::HTTP::Endpoint] The endpoint the driver is listening on.
+				def endpoint
+					Async::HTTP::Endpoint.parse("http://localhost:#{port}")
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/bridge/pool.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Bridge
+			# A pool of sessions.
+			#
+			# ``` ruby
+			# begin
+			# 	bridge = Async::WebDriver::Bridge::Pool.start(Async::WebDriver::Bridge::Chrome.new)
+			# 	session = bridge.session
+			# ensure
+			# 	bridge&.close
+			# end
+			# ```
+			class Pool
+				# Create a new session pool and start it.
+				# @parameter bridge [Bridge] The bridge to use to create sessions.
+				# @parameter capabilities [Hash] The capabilities to use when creating sessions.
+				# @returns [Pool] The pool.
+				def self.start(bridge, **options)
+					self.new(bridge, **options).tap do |pool|
+						pool.start
+					end
+				end
+				
+				# Initialize the session pool.
+				# @parameter bridge [Bridge] The bridge to use to create sessions.
+				# @parameter capabilities [Hash] The capabilities to use when creating sessions.
+				# @parameter minimum [Integer] The minimum number of sessions to keep open.
+				def initialize(bridge, capabilities: bridge.default_capabilities, minimum: 2)
+					@bridge = bridge
+					@capabilities = capabilities
+					@minimum = minimum
+					
+					@thread = nil
+					
+					@waiting = Thread::Queue.new
+					@sessions = Thread::Queue.new
+				end
+				
+				# Close the session pool.
+				def close
+					if @waiting
+						@waiting.close
+					end
+					
+					if @thread
+						@thread.join
+						@thread = nil
+					end
+					
+					if @sessions
+						@sessions.close
+					end
+				end
+				
+				private def prepare_session(client)
+					client.post("session", {capabilities: @capabilities})
+				end
+				
+				# Start the session pool.
+				def start
+					@thread ||= Thread.new do
+						Sync do
+							@bridge.start
+							
+							client = Client.open(@bridge.endpoint)
+							
+							@minimum.times do
+								@waiting << true
+							end
+							
+							while @waiting.pop
+								session = prepare_session(client)
+								@sessions << session
+							end
+						ensure
+							client&.close
+							@bridge.close
+						end
+					end
+				end
+				
+				# Open a session.
+				def session(&block)
+					@waiting << true
+					
+					reply = @sessions.pop
+					
+					Session.open(@bridge.endpoint, reply["sessionId"], reply["capabilities"], &block)
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/bridge/process_group.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+module Async
+	module WebDriver
+		module Bridge
+			# A group of processes that are all killed when the group is closed.
+			class ProcessGroup
+				# Spawn a new process group with a given command.
+				# @parameter arguments [Array] The command to execute.
+				def self.spawn(*arguments)
+					# This might be problematic...
+					self.new(
+						::Process.spawn(*arguments, pgroup: true, out: File::NULL, err: File::NULL)
+					)
+				end
+				
+				# Create a new process group from an existing process id.
+				# @parameter pid [Integer] The process id.
+				def initialize(pid)
+					@pid = pid
+					
+					@status_task = Async(transient: true) do
+						@status = ::Process.wait(@pid)
+						
+						unless @status.success?
+							Console.error(self, "Process exited unexpectedly: #{@status}")
+						end
+					ensure
+						self.close
+					end
+				end
+				
+				# Close the process group.
+				def close
+					if @status_task
+						@status_task.stop
+						@status_task = nil
+					end
+					
+					if @pid
+						::Process.kill("INT", -@pid)
+						
+						Async do |task|
+							task.with_timeout(1) do
+								::Process.wait(@pid)
+							rescue Errno::ECHILD
+								# Done.
+							rescue Async::TimeoutError
+								Console.info(self, "Killing pid #{@pid}...")
+								::Process.kill("KILL", -@pid)
+							end
+						end.wait
+						
+						wait_all(-@pid)
+						@pid = nil
+					end
+				end
+				
+				protected
+				
+				# Wait for all processes in the group to exit.
+				def wait_all(pgid)
+					while true
+						pid, status = ::Process.wait2(pgid, ::Process::WNOHANG)
+						
+						break unless pid
+					end
+				rescue Errno::ECHILD
+					# Done.
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/bridge.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
+
+require_relative 'bridge/chrome'
+require_relative 'bridge/firefox'
+
+module Async
+	module WebDriver
+		# A bridge is a process that can be used to communicate with a browser.
+		# It is not needed in all cases, but is useful when you want to run integration tests without any external drivers/dependencies.
+		# As starting a bridge can be slow, it is recommended to use a shared bridge when possible.
+		module Bridge
+			ALL = [
+				Bridge::Chrome,
+				Bridge::Firefox,
+			]
+			
+			def self.each(&block)
+				return enum_for(:each) unless block_given?
+				
+				ALL.each do |klass|
+					next unless klass.new.supported?
+					yield klass
+				end
+			end
+		end
+	end
+end

data/lib/async/webdriver/client.rb

@@ -1,30 +1,75 @@
-require "async/queue"
+# frozen_string_literal: true
 
-module Async
-  module Webdriver
-    class Client
-      def initialize(endpoint:, desired_capabilities: {})
-        @connection = Connection.new endpoint: endpoint
-        @desired_capabilities = desired_capabilities
-      end
-
-      def session
-        SessionCreator.new connection: @connection, desired_capabilities: @desired_capabilities
-      end
+# Released under the MIT License.
+# Copyright, 2023, by Samuel Williams.
 
-      def status
-        @connection.call method: :get, path: "status"
-      end
+require_relative 'request_helper'
+require_relative 'session'
 
-      def sessions
-        value = @connection.call method: :get, path: "sessions"
-        list = []
-        for json in value do
-          list << Session.new(json: json, connection: @connection)
-        end
-        list
-      end
-
-    end
-  end
+module Async
+	module WebDriver
+		# A client for the WebDriver protocol.
+		#
+		# If you have a running web driver server, you can connect to it like so (assuming it is running on port 4444):
+		#
+		# ``` ruby
+		# begin
+		# 	client = Async::WebDriver::Client.open(Async::HTTP::Endpoint.parse("http://localhost:4444"))
+		# 	session = client.session
+		# ensure
+		# 	client&.close
+		# end
+		# ```
+		class Client
+			include RequestHelper
+			
+			# Open a new session.
+			# @parameter endpoint [Async::HTTP::Endpoint] The endpoint to connect to.
+			# @yields {|client| ...} The client will be closed automatically if you provide a block.
+			# 	@parameter client [Client] The client.
+			# @returns [Client] The client if no block is given.
+			def self.open(endpoint, **options)
+				client = self.new(
+					Async::HTTP::Client.open(endpoint, **options)
+				)
+				
+				return client unless block_given?
+				
+				begin
+					yield client
+				ensure
+					client.close
+				end
+			end
+			
+			# Initialize the client.
+			# @parameter delegate [Protocol::HTTP::Middleware] The underlying HTTP client (or wrapper).
+			def initialize(delegate)
+				@delegate = delegate
+			end
+			
+			# Close the client.
+			def close
+				@delegate.close
+			end
+			
+			# Request a new session.
+			# @returns [Session] The session if no block is given.
+			# @yields {|session| ...} The session will be closed automatically if you provide a block.
+			# 	@parameter session [Session] The session.
+			def session(capabilities, &block)
+				reply = post("session", {capabilities: capabilities})
+				
+				session = Session.new(@delegate, reply["sessionId"], reply["value"])
+				
+				return session unless block_given?
+				
+				begin
+					yield session
+				ensure
+					session.close
+				end
+			end
+		end
+	end
 end