selenium_tor 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aeb8724ddcdf0d7260330ca616651d54b94ce33c6a635c71ef5c5f3577de220
-  data.tar.gz: 12b5d264f6a774dab990148feb15179d0b7873e42eb5b1c4bb99e8383f5e5577
+  metadata.gz: fcf1656f54ce23992e788e76b1d6342157b6ba3996ec95f04c955a2857e9b2be
+  data.tar.gz: a9ef924f85fdd1370638ff3c12f9009ec1b2ab1b65b5a872bb8bd3d3e3e6e4f5
 SHA512:
-  metadata.gz: deafbf4cbbc646e2fef5dc1800bc009edceb72906d65dc071942d0c742a49dd6aa17ac4fe2f88fc8d36f909445b31378996073f7d44b8cff473db2e9e3f5d403
-  data.tar.gz: 71c615ce16eb80f696aaa4dc26d73459df4ce8c4b7d994998580be1d93405baa5dc9ee94f321e7494f1567f3bed1f48481e53149829c2e1671268a6069d9d91f
+  metadata.gz: 68018127837d8e59dd60647d9a0d60da4af363da8fad7104ac6ed52bf15844d7ead4d4cbc81f1b2403e64ad2fdda55f488ce725ca71b23c618686fb3ed5dbde3
+  data.tar.gz: 3a6bd3db60f2a9de62e232774edabb11e4ccd7bb6e48158c4b6709339f8c964e56f4817f78d471d8ae57a970fec25b325a76a4c3779a3ee67aee8bdc2ad5250f

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## master (unreleased)
 
+## [1.3.0] - 2024-08-05
+
+### Bug fixes
+
+* [#14](https://gitlab.com/matzfan/selenium-tor/-/issues/14)
+
+### New features
+
+* add ability to get and set driver preferences dynamically
+* add Tor Browser alpha release to CI tests ([#12](https://gitlab.com/matzfan/selenium-tor/-/issues/12))
+
 ## [1.2.0] - 2024-07-31
 
 ### Bug fixes

data/README.md

@@ -45,7 +45,8 @@ options = Selenium::WebDriver::Tor::Options.new
 @driver = Selenium::WebDriver.for :tor, options: options
 
 @driver.get 'https://check.torproject.org'
-@driver.title # => Congratulations. This browser is configured to use Tor.
+@driver.title
+# => Congratulations. This browser is configured to use Tor.
 @driver.quit
 ```
 If the network is inaccessible for any reason a `TorNetworkError` will result.
@@ -56,49 +57,49 @@ Running multiple `tor` processes requires that each uses different ports for Soc
 ```ruby
 require 'parallel'
 
-socks_port = 9150
-control_port = 9151
+@socks_port = 9150
+@control_port = 9151
 
-def driver(socks_p, control_p)
-  options = Selenium::WebDriver::Tor::Options.new tor_opts: { socks_port: socks_p, control_port: control_p }
-  Selenium::WebDriver.for :tor, options: options # new tor process started with tor_opts
+def driver
+  @socks_port += 2
+  @control_port += 2
+  options = Selenium::WebDriver::Tor::Options.new tor_opts: { socks_port: @socks_port, control_port: @control_port }
+  Selenium::WebDriver.for :tor, options: options
 end
 
-driver1 = driver(socks_port, control_port)
-driver2 = driver(socks_port += 2, control_port += 2)
+@drivers = [driver, driver]
 
-title = 'Congratulations. This browser is configured to use Tor.'
-
-Parallel.all?([driver1, driver2], in_threads: 2) do |driver|
+Parallel.all?(@drivers, in_threads: @drivers.size) do |driver|
   driver.get 'https://check.torproject.org'
-  driver.title == title
 end
-# => true
 
-driver1&.quit
-driver2&.quit
+@drivers.each(&:quit)
 ```
 ### Tor Browser specific functionality
 
 You can get and set the secuirty level (shield icon in TB) as follows. 4 is 'Standard', 2 is 'Safer', 1 is 'Safest'.
 ```ruby
-@driver = Selenium::WebDriver.for :tor
 @driver.security_level
 # => 4 - the default value
-@driver.security_level = 1
+@driver.security_level = 2
 @driver.security_level
-# => 1
-@driver.quit
+# => 2
 ```
 You can get a new circuit for the current page ('New Tor circuit for this site' on TB's application menu):
 ```ruby
-@driver = Selenium::WebDriver.for :tor
-@driver.get 'https://example.com'
-@driver.new_circuit_for_page # new circuit for the current page only
-@driver.quit
+@driver.new_circuit_for_site # new circuit for the current page domain
 ```
 ### Miscellaneous
 
+You can get and set Driver preferences dynamically like this. Caveat emptor.
+```ruby
+@driver.pref['browser.download.dir']
+# => ""
+@driver.pref['browser.download.dir'] = 'home/user/Downloads'
+@driver.pref['browser.download.dir']
+# => "home/user/Downloads"
+```
+
 The `Selenium::WebDriver::Tor` namespace is used for `Driver`, `Options`, `Profile` and all tor-specific classes. Otherwise Selenium's `Selenium::WebDriver::Firefox` namespace is used.
 
 Remote functionality is not tested, but may be if a suitable Tor Browser Docker container becomes available.
@@ -117,6 +118,8 @@ Tor::TBB_VERSION # the version installed, e.g. "13.0.1", note: driver.capabiliti
 
 [Tor Browser](https://www.torproject.org/download).
 
+The shared libraries Tor Bowser requires will be available if you have Firefox or Firefox ESR installed on your system. If not, do `sudo apt install firefox-esr` or similar.
+
 As with Firefox browser, `geckodriver` needs to be installed and in your PATH.
 
 The gem needs to know the location of the Tor Browser Bundle (TBB). The Tor Browser download package archive must be extracted and the root TBB directory (named "tor-browser") placed somewhere on your system. By default it is assumed to be in the current user's HOME directory. An alternative location can be set via the env var `TOR_BROWSER_ROOT_DIR` - e.g. `export TOR_BROWSER_ROOT_DIR=/home/<user>/Downloads`. The Tor Browser binary location is *automatically set* by reference to this directory, so there is no need to do this:

data/lib/firefox_js_helpers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+module Selenium
+  module WebDriver
+    # namespace
+    module Firefox
+      # js helpers
+      module FirefoxJsHelpers
+        def execute_script_in_chrome_context(...)
+          in_chrome_context { execute_script(...) }
+        end
+
+        def es6_const_call(es6:, const:)
+          es6_import(es6) << "return m.#{const}"
+        end
+
+        def es6_function_call(es6:, func:, args:)
+          es6_import(es6) << "return m.#{es6}.#{func}('#{args}')"
+        end
+
+        private
+
+        def es6_import(es6)
+          "let m = ChromeUtils.importESModule('resource://gre/modules/#{es6}.sys.mjs');"
+        end
+
+        def in_chrome_context
+          raise(ArgumentError, "##{__method__} takes a block arg") unless block_given?
+
+          old_context = context
+          self.context = 'chrome'
+          yield
+        ensure
+          self.context = old_context if old_context
+        end
+      end
+      Firefox::Driver.prepend FirefoxJsHelpers
+    end
+  end
+end

data/lib/firefox_prefs.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative '../lib/firefox_js_helpers'
+
+module Selenium
+  module WebDriver
+    module Firefox
+      # representation of a firefox pref
+      class Preference
+        PREF_TYPES = { 'PREF_BOOL' => 128, 'PREF_INT' => 64, 'PREF_INVALID' => 0, 'PREF_STRING' => 32 }.freeze
+        GET_METHODS = { 0 => 'getStringPref', 32 => 'getStringPref', 64 => 'getIntPref', 128 => 'getBoolPref' }.freeze
+        SET_METHODS = { 32 => 'setStringPref', 64 => 'setIntPref', 128 => 'setBoolPref' }.freeze
+
+        def initialize(driver)
+          @driver = driver
+        end
+
+        def [](str)
+          @driver.execute_script_in_chrome_context script_string(str)
+        end
+
+        def []=(str, val)
+          @driver.execute_script_in_chrome_context script_string(str, val)
+        end
+
+        private
+
+        def script_string(str, val = nil)
+          val ? setter_script(str, val) : getter_script(str)
+        end
+
+        def getter_script(str)
+          type = pref_type(str)
+          "return Services.prefs.#{GET_METHODS[type]}('#{str}'#{default(type)})"
+        end
+
+        def default(type)
+          type.zero? ? ", ''" : '' # empty string default arg if pref not found, otherwise no default arg
+        end
+
+        def setter_script(str, val)
+          "Services.prefs.#{set_method(str, val)}('#{str}', #{quote_str(val)})"
+        end
+
+        def set_method(str, val)
+          type = pref_type(str)
+          return SET_METHODS[type] unless type.zero?
+          return 'setBoolPref' if val.instance_of?(TrueClass) || val.instance_of?(FalseClass)
+          return 'setIntPref' if val.is_a? Integer
+
+          'setStringPref' # everthing else gets set as a string
+        end
+
+        def pref_type(string)
+          @driver.execute_script_in_chrome_context("return Services.prefs.getPrefType('#{string}')")
+        end
+
+        def quote_str(value)
+          value.is_a?(String) ? "'#{value}'" : value
+        end
+      end
+
+      # adds Driver#pref method and [] and []= methods on that object
+      module FirefoxPrefs
+        def pref
+          Preference.new self
+        end
+      end
+
+      class Driver
+        prepend FirefoxPrefs
+      end
+    end
+  end
+end

data/lib/tor/driver.rb

@@ -3,6 +3,7 @@
 require 'open-uri'
 require_relative '../service'
 require_relative '../options'
+require_relative '../firefox_prefs'
 require_relative 'profile'
 require_relative 'tor_process'
 
@@ -14,9 +15,12 @@ module Selenium
 
       # tor driver
       class Driver < DelegateClass(DriverDelegate)
-        class TorNetworkError < StandardError; end
-
-        TB_SECURITY_LEVELS = [4, 2, 1].freeze
+        TORRC_PATH_PREF = 'extensions.torlauncher.torrc_path'
+        TORRC = 'torrc'
+        BROWSER_SECURITY_LEVEL_PREF = 'browser.security_level.security_slider'
+        DOMAIN_ISOLATOR = 'TorDomainIsolator' # ES6 module
+        NEW_CIRCUIT = 'newCircuitForDomain' # js function
+        TB_SEC_LEVELS = { 'standard' => 4, 'safer' => 2, 'safest' => 1 }.freeze
 
         def initialize(options: nil, **)
           @data_dir = Dir.mktmpdir
@@ -39,36 +43,25 @@ module Selenium
         end
 
         def security_level
-          old_context = context
-          self.context = 'chrome'
-          execute_script("return Services.prefs.getIntPref('browser.security_level.security_slider')")
-        ensure
-          self.context = old_context
+          pref[BROWSER_SECURITY_LEVEL_PREF]
         end
 
         def security_level=(int)
-          old_context = context
-          self.context = 'chrome'
-          raise(ArgumentError, 'Security level can be set to 4, 2 or 1') unless TB_SECURITY_LEVELS.include?(int)
+          raise(ArgumentError, "Valid security levels are: #{TB_SEC_LEVELS.values}") unless TB_SEC_LEVELS.value?(int)
 
-          execute_script("return Services.prefs.setIntPref('browser.security_level.security_slider', #{int})")
-        ensure
-          self.context = old_context if old_context
+          pref[BROWSER_SECURITY_LEVEL_PREF] = int
         end
 
-        def new_circuit_for_page
-          old_context = context
-          self.context = 'chrome'
-          execute_script "ChromeUtils.importESModule('resource://gre/modules/TorDomainIsolator.sys.mjs');
-                          TorDomainIsolator.newCircuitForDomain('#{current_url}')"
-        ensure
-          self.context = old_context
+        def new_circuit_for_site
+          execute_script_in_chrome_context es6_function_call(es6: DOMAIN_ISOLATOR, func: NEW_CIRCUIT, args: domain)
         end
 
+        alias new_circuit_for_page new_circuit_for_site
+
         private
 
         def add_torrc_path_to_options
-          @options.prefs['extensions.torlauncher.torrc_path'] = File.join(@data_dir, 'torrc')
+          @options.prefs[TORRC_PATH_PREF] = File.join(@data_dir, TORRC)
         end
 
         def install_extensions(instance)
@@ -78,6 +71,12 @@ module Selenium
         def create_tor_process_and_start_tor(opts)
           @tor_process = TorProcess.new(@data_dir, opts || {})
           @tor_process.start_tor
+        rescue Tor::TorProcess::TorProcessError => e
+          raise Error::WebDriverError, e
+        end
+
+        def domain
+          URI(current_url).host&.match(/[^\.]+\.\w+$/)
         end
       end
     end

data/lib/tor/tor_process.rb

@@ -14,8 +14,7 @@ module Selenium
         class TorProcessError < StandardError; end
 
         BOOTSTRAP_SUCCESS_REGEX = /Bootstrapped 100% \(done\): Done$/
-        BOOTSTRAP_FAIL_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
-        # BOOTSTRAP_TIMEOUT_REGEX = /^[A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
+        BOOTSTRAP_FAIL_REGEX = /^[A-Z][a-z]{2} \d{2} \d{2}:\d{2}:\d{2}\.\d{3} \[err\] .*/
 
         attr_reader :pid, :config
 
@@ -69,7 +68,6 @@ module Selenium
             lines << line
             break lines.join if line.match BOOTSTRAP_FAIL_REGEX
             break '' if line.match BOOTSTRAP_SUCCESS_REGEX
-            # break false if line.match BOOTSTRAP_TIMEOUT_REGEX
           end
         end
       end

data/lib/tor/version.rb

@@ -3,7 +3,7 @@
 module Selenium
   module WebDriver
     module Tor
-      VERSION = '1.2.0'
+      VERSION = '1.3.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: selenium_tor
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - MatzFan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-31 00:00:00.000000000 Z
+date: 2024-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -41,6 +41,8 @@ files:
 - Rakefile
 - fonts/000_README.txt
 - lib/driver.rb
+- lib/firefox_js_helpers.rb
+- lib/firefox_prefs.rb
 - lib/options.rb
 - lib/selenium_tor.rb
 - lib/service.rb
@@ -78,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: Selenium extension for Tor Browser