webaccount 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f2306cf382f2ebbba8b93e9746e12c92d298ead4ba4f154fc71c223d844e2e0
-  data.tar.gz: c1b04987b7f1812c549fd8f0203457e515aab18e716f2885c29494c07688baf8
+  metadata.gz: 219aecddbc5a0e05b1463300ade4350d9afd789de19f1a43fe34e492d5ad9296
+  data.tar.gz: 6cbc7db55da4afc34b164f3a8a163da4e4e716b313e09b266d2453c98af0c115
 SHA512:
-  metadata.gz: 2f488ddda68db8c4807e5ad7ada9c8f85f48219a97e24be6f1ea6d1033395993a9bf6a74de615b539bdab6c749e7a11c3c4a1d04256dd94cfba743a2aadb0f8d
-  data.tar.gz: 86b9e301db625c6e236da7290d916a1fa629d3cdabf74cc4cb8f61f0b25d837a8b6bd5e5cec6b357b5f3baea0ff6d4d71739ddc7ac463089ee1a4a06df5e73bc
+  metadata.gz: fdb4db1ec12daf5e307f0df3212f51f1eb4da9b1ca505a68a1008e626598d30214f7d235e330b9f856d215efb816c276eb4525a4578937eb7329dedf064d0581
+  data.tar.gz: b4515525fce7cb22a90b15f7a05ddc3da14cb870c02d4e95d31959a2ff3c3753d74ad96adfb0bd96deb64937f466c20a0ec7ae3395b9d4d43eb59b72b4881dff

data/CHANGELOG

@@ -0,0 +1,93 @@
+# CHANGELOG
+
+## 20260717
+
+0.4.0: Selenium 4 compatibility, achieved mostly by deletion, since Selenium 4 has absorbed most of what these extensions were written for.
+
+Breaking:
+a. - WebAccount#user_agent_alias, #user_agent_alias=: Replaced by the browser: argument to new(). A sub-class which set or over-rode user_agent_alias must now pass browser: or over-ride #browser().
+b. ~ webaccount.gemspec: Require selenium-webdriver >= 4.0 and Ruby >= 3.3. This release depends on Selenium 4 behaviour and will not work on Selenium 3.
+c. ~ Thoran::Selenium::WebDriver::Driver::ElementPresentQ#element_present?(): No longer waits. The implicit wait removed in 16 below gave it up to 5s for an element to appear; it is now an instantaneous check, so a sub-class which relied on it as a wait will now silently get false rather than true. Wrap it in a Selenium::WebDriver::Wait, as login() does.
+d. /lib/WebAccount.rb/lib/webaccount.rb/: require 'webaccount', which is what the README has always documented and what the gem name implies, raised a LoadError on a case-sensitive file system. It now works, and it is require 'WebAccount' which raises instead. require 'web_account' is unaffected.
+
+1. - Thoran::Selenium::WebDriver::Remote::W3C::Bridge::ConvertLocators: The namespace no longer exists in Selenium 4, which raised a NameError on require, and locator conversion is now native.
+2. - Thoran::Selenium::WebDriver::SearchContext::ElementsPresentQ: find_elements_by() returns an empty array rather than raising, so elements_present?() was unconditionally true.
+3. - Thoran::Selenium::WebDriver::Setup: Firefox::Binary is gone from Selenium 4 and there was never a Chrome or Safari equivalent, so only the browser name branch remained, which is Selenium::WebDriver.for().
+4. - Thoran::String::ToConst: Only ever used by Setup, and Object.const_get() has handled nested constants since Ruby 2.0.
+5. - Thoran::Array::AllButFirst: Only ever used by ToConst.
+6. - Thoran::Array::FirstX: Only ever used by AllButFirst.
+7. ~ Thoran::Selenium: - the three deleted requires.
+8. ~ Thoran::Selenium::WebDriver::Driver::Attempt#attempt(): Yield self, so the documented block argument is the driver rather than nil; use retry rather than loop/break; re-raise rather than calling quit on @driver, which was never assigned, and exiting the process.
+9. ~ Thoran::Selenium::WebDriver::Driver::Attempt#attempt(): - Timeout::Error, which nothing in Selenium 4 raises, so the rescue was dead. Selenium's own timeouts, and those of Selenium::WebDriver::Wait, are Selenium::WebDriver::Error::TimeoutError. Timeout::Error also only resolved at all because selenium-webdriver happens to require 'timeout' for Firefox.
+10. + Thoran::Selenium::WebDriver::Driver::Attempt::TRANSIENT_ERRORS: The errors a flaky page actually raises: ElementClickInterceptedError, ElementNotInteractableError, NoSuchElementError, StaleElementReferenceError, TimeoutError, UnexpectedAlertOpenError, and UnknownError. Only the last two were caught before. InvalidSelectorError and NoSuchDriverError are deliberately excluded, being programming and environment errors respectively, so retrying only delays the report.
+11. ~ Thoran::Selenium::WebDriver::Driver::ElementPresentQ#element_present?(): Use the public find_elements() rather than the private bridge.
+12. /Thoran::Selenium::WebDriver::SearchContext::ElementPresentQ/Thoran::Selenium::WebDriver::Driver::ElementPresentQ/: It patches Driver, as Driver::Attempt does, so it now sits alongside it. Selenium::WebDriver::SearchContext is the find_element()/find_elements() contract which Driver, Element, and ShadowRoot implement, rather than a home for conveniences built on top of it, and Selenium itself has no presence predicate to follow.
+13. + WebAccount#default_browser(), #default_driver_options(): Return :chrome and nil, for over-riding in a sub-class.
+14. + WebAccount#browser(), #driver_options(): Fall back to the defaults. browser() also normalises a String or a capitalised Symbol, since Selenium::WebDriver.for() matches on a lowercase Symbol.
+15. ~ WebAccount#driver(): Construct the driver directly, with browser() and driver_options(), rather than via the deleted Selenium::WebDriver.setup().
+16. ~ WebAccount#driver(): - the implicit wait, since mixing implicit and explicit waits made driver_wait() poll every 5s rather than every 0.2s. See c above.
+17. + WebAccount#find(): Extracted from the four finder methods.
+18. + WebAccount#find_wait(), #default_find_timeout(): A Wait of its own for find(), at 5s. Sharing driver_wait() would have given a missing element 180s to not appear, where the implicit wait removed in 16 raised at 5s. Selenium::WebDriver::Wait ignores NoSuchElementError by default, so find() polls rather than raising, and 5s restores the previous contract.
+19. ~ WebAccount#driver_wait(): /180/30/, via the new #default_wait_timeout(). 180s was tolerable only because the implicit wait removed in 16 made each poll cost 5s, so it bought 36 polls; at the 0.2s interval it now buys 900 polls of the same page. 30s covers a submit, the authentication behind it, and the redirect, and is 90s worst case through attempt()'s three tries rather than 9 minutes.
+20. + WebAccount#username_field_selector(), #password_field_selector(), #login_page_submit_button_selector(), #logout_button_selector(): Fall back to the defaults in one place.
+21. ~ WebAccount#username_field(), #password_field(), #login_page_submit_button(), #logout_button(): Use find() and the selector methods.
+22. ~ WebAccount#logout_button(): Fix @logout_page_submit_button_selector, which was never assigned, so a supplied logout button selector was always ignored in favour of the default.
+23. ~ WebAccount#login(): Use logout_button_selector(), which no longer raises when no selector was supplied.
+24. ~ WebAccount#login(): - attempts = 0, which was unused.
+25. /WebAccount#default_username_field/WebAccount#default_username_field_selector/
+26. /WebAccount#default_password_field/WebAccount#default_password_field_selector/
+27. ~ lib/web_account.rb: /require_relative './WebAccount'/require_relative './webaccount'/, per d above.
+28. ~ WebAccount::VERSION: /0.3.1/0.4.0/
+29. + lib/webaccount.rb: require_relative './WebAccount/VERSION', so that WebAccount::VERSION is defined by requiring the library. It was previously loaded only by the gemspec.
+30. ~ lib/webaccount.rb: /require 'Thoran/Selenium'/require_relative './Thoran/Selenium'/. Thoran/Selenium ships in this gem, so requiring it by $LOAD_PATH meant it only loaded when lib was on the path, and left it to path order in a namespace which several other gems here also ship. require './lib/webaccount' now works.
+31. ~ lib/webaccount.rb: /# WebAccount.rb/# webaccount.rb/ in the header, per d above.
+32. ~ webaccount.gemspec: /spec.license = 'Ruby'/spec.license = 'MIT'/, per the more recent gems.
+33. + test/Thoran/Selenium/WebDriver/Driver/Attempt_test.rb: Cover attempt() against a dummy including the module: the value and receiver yielded, which errors are retried and which are not, the attempt count, and the warning. The transient and non-transient errors are listed in the test rather than read from TRANSIENT_ERRORS, so that the test states the intent rather than agreeing with the implementation. Nothing else in WebAccount is reachable to test: browser(), driver_options(), and the four selector methods are all private, and login(), find(), and logout() need a browser and a settled timeout.
+34. + Rakefile: rake test, per the other gems.
+35. ~ .gitignore (*.lock): Running bundle writes a Gemfile.lock, which is not committed for a gem.
+36. ~ webaccount.gemspec: + minitest, minitest-spec-context, and rake as development dependencies, and + Rakefile and test/ to spec.files.
+37. ~ webaccount.gemspec: Match the layout of the more recent gemspecs: + the dependencies=/development_dependencies= sugar; + spec.require_paths, which was missing; list spec.files explicitly, so that CHANGELOG, Gemfile, and README.md are packaged rather than lib alone; and - spec.date, which Rubygems sets itself and which was stale in every release so far.
+38. ~ README.md: + Choosing a browser, Driver options, and Timeouts; note that logged_out_xpath is required by logout() and shutdown(); prefer find() to driver.find_element() in the sub-classing example, since that example was relying on the implicit wait removed in 16; and fix a stray quotation mark, a missing comma, and a fork URL pointing at month.rb.
+
+Known: These are all one question, which is what login(), logout(), and logged_out?() should do
+when the page does not do what was expected: raise, or report. They want one answer between
+them rather than three, they are not compatibility problems, and 0.5's fixtures and
+integration tests are what would pin them, so they are left alone here.
+
+i. WebAccount#logged_out?() returns truthy or raises: Wait#until does not return false, so
+  the `if logged_out?` in logout() is dead code and logout() always either raises or logs out.
+ii. WebAccount#login() raises Selenium::WebDriver::Error::TimeoutError rather than returning
+  false when the logout button never appears, so a wrong password is an exception rather than
+  a return value. As in 0.3.1.
+iii. WebAccount#logged_out?() with no logged_out_xpath raises
+  Selenium::WebDriver::Error::InvalidSelectorError, from find_elements(:xpath, nil) reaching
+  the bridge, which sends nil.to_s. shutdown() calls logout(), so this is reachable from the
+  README's implicit-defaults usage.
+iv. Thoran::Selenium::WebDriver::Driver::ElementPresentQ#element_present?() rests on
+  find_elements() returning an empty array rather than raising, which is what the deleted
+  ElementsPresentQ in 2 above got wrong. Only a driver can confirm it, so it is untested until
+  0.5.
+
+
+## 20240407
+
+0.3.1: ./lib/README.md --> ./README.md
+
+
+## 20240407
+
+0.3.0: Can now use all of Selenium's page selectors (:css, :id, :name:, :xpath) instead of just :id and/or overriding methods in the sub-class.
+1. + WebAccount#default_username_field(): For use in username_field if username_field_selector is nil.
+2. ~ WebAccount#username_field(): Will optionally use the default_username_field if nothing is supplied.
+3. + WebAccount#default_password_field():  For use in password_field if username_field_selector is nil.
+4. ~ WebAccount#password_field(): Will optionally use the default_username_field if nothing is supplied.
+5. + WebAccount#default_login_page_submit_button_selector(): For use in login_page_submit_button if login_page_submit_button is nil.
+6. ~ WebAccount#login_page_submit_button(): Will optionally use the default_login_page_submit_button_selector if nothing is supplied.
+7. + WebAccount#default_logout_button_selector():  For use in logout_button if logout_button is nil.
+8. + WebAccount#logout_button(): Consistent with other elements having a method and will also optionally use the default_logout_button_selector if nothing is supplied.
+9. ~ WebAccount#login(): Use new generic selector for detecting logged-in state.
+10. ~ WebAccount#logout(): Use new logout_button() method instead of in-lining Selenium.
+11. ~ WebAccount::VERSION: /0.2.5/0.3.0/
+12. ~ webaccount.gemspec: Change the date, fix the summary, and the description.
+13. + CHANGELOG.txt
+14. + README.md

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://www.rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,181 @@
+# WebAccount
+
+## Description
+
+Easily log into web accounts by supplying just a username and password, the URL of the login page, and a few selectors for page elements to a sub-class of WebAccount.
+
+## Installation
+
+Add this line to your application's Gemfile:
+```ruby
+gem 'webaccount'
+```
+And then execute:
+```shell
+$ bundle
+```
+Or install it yourself as:
+```shell
+$ gem install webaccount
+```
+
+## Usage
+
+### Instantiation
+
+#### 1. With implicit defaults
+```ruby
+  require 'webaccount'
+
+  class MyAccount < WebAccount; end
+
+  MyAccount.new(username: username, password: password)
+  # => #<MyAccount @username=username, @password=password, @login_page_url=nil,
+  # @login_page_password_field_selector=nil, @login_page_username_field_selector=nil,
+  # @login_page_submit_button_selector=nil,
+  # @logout_button_selector=nil, @logged_out_xpath=nil>
+```
+
+#### 2. With explicit defaults, then in the comment the ultimate defaults if those values remain nil
+```ruby
+  require 'webaccount'
+
+  class MyAccount < WebAccount
+    PAGE_SELECTORS = {
+      login_page_url: nil, # There are no defaults, so something like 'https://mysite.com/login' is required.
+      login_page_username_field_selector: nil, # Will default to: {name: 'username'}
+      login_page_password_field_selector: nil, # Will default to: {name: 'password'}
+      login_page_submit_button_selector: nil, # Will default to: {xpath: '//input[@type="submit" and @value="Login"]'}
+      logout_button_selector: nil, # Will default to: {xpath: '//input[@type="submit" and @value="Logout"]'}
+      logged_out_xpath: nil, # No default value for this, and logout and shutdown require it.
+    }
+  end
+
+  MyAccount.new(
+    **{username: username, password: password}\
+      .merge(MyAccount::PAGE_SELECTORS)
+  )
+  # => #<MyAccount @username=username, @password=password...>
+```
+
+#### 3. With supplied values
+```ruby
+  require 'webaccount'
+
+  class MyAccount < WebAccount
+    PAGE_SELECTORS = {
+      login_page_url: 'https://mysite.com/login',
+      login_page_username_field_selector: {id: 'username'},
+      login_page_password_field_selector: {id: 'password'},
+      login_page_submit_button_selector: {xpath: '//button[@type="submit" and @value="Login"]'},
+      logout_button_selector: {css: '#button-logout'},
+      logged_out_xpath: '//div[@class="logged-out"]',
+    }
+  end
+
+  MyAccount.new(
+    **{username: username, password: password}
+      .merge(MyAccount::PAGE_SELECTORS)
+  )
+  # => #<MyAccount @username=username, @password=password...>
+```
+
+### Choosing a browser
+
+`browser` is passed to `Selenium::WebDriver.for`, so it accepts whatever Selenium does: `:chrome`, `:firefox`, `:safari`, `:edge`, `:ie`. It defaults to `:chrome`, and a String or a capitalised Symbol is fine.
+```ruby
+  MyAccount.new(username: username, password: password, browser: :firefox)
+```
+
+### Driver options
+
+`driver_options` is passed to `Selenium::WebDriver.for` as `options:`. It defaults to nil, which is what Selenium itself defaults to, so leaving it alone gets you a stock browser.
+```ruby
+  options = Selenium::WebDriver::Chrome::Options.new
+  options.add_argument('--headless=new')
+
+  MyAccount.new(username: username, password: password, driver_options: options)
+```
+Or in a sub-class, if every instance should be configured the same way:
+```ruby
+  class MyAccount < WebAccount
+    private
+
+    def default_driver_options
+      Selenium::WebDriver::Chrome::Options.new.tap do |options|
+        options.add_argument('--headless=new')
+      end
+    end
+  end
+```
+
+### Timeouts
+
+There are two, both overridable in a sub-class:
+
+| Method | Default | Waits for |
+| --- | --- | --- |
+| `default_find_timeout` | 5s | An element on a page which has already loaded. |
+| `default_wait_timeout` | 30s | Navigation: a submit, the authentication behind it, and the redirect. |
+
+```ruby
+  class SlowAccount < WebAccount
+    private
+
+    def default_wait_timeout
+      60
+    end
+  end
+```
+
+### Logging in, out, and shutting down
+```ruby
+  require 'webaccount'
+
+  class MyAccount < WebAccount; end
+
+  my_account = MyAccount.new(username: username, password: password)
+  my_account.login
+  my_account.logout
+  my_account.shutdown # If necessary it logs out and then kills the selenium session.
+```
+
+### Overriding the login method to customise logins
+```ruby
+  require 'webaccount'
+
+  class MyAccount < WebAccount
+    def login
+      # Put custom login code here.
+    end
+  end
+```
+
+### Create new methods for selection and navigation
+
+Prefer `find` over `driver.find_element`: it waits up to `default_find_timeout` for the element, whereas `driver.find_element` raises the moment the element isn't there.
+```ruby
+  require 'webaccount'
+
+  class MyAccount < WebAccount
+    def list_page_link
+      find(id: 'list')
+    end
+
+    def list_page
+      login unless logged_in?
+      list_page_link.click
+    end
+  end
+
+  my_account = MyAccount.new(username: username, password: password)
+  my_account.list_page
+```
+
+## Contributing
+
+1. Fork it: https://github.com/thoran/WebAccount/fork
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -am 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Create a new pull request

data/Rakefile

@@ -0,0 +1,9 @@
+# Rakefile
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/lib/Thoran/Selenium/WebDriver/Driver/Attempt/attempt.rb

@@ -1,8 +1,8 @@
-# Thoran/Selenium/WebDriver/Attempt/attempt.rb
-# Thoran::Selenium::WebDriver::Attempt.attempt
+# Thoran/Selenium/WebDriver/Driver/Attempt/attempt.rb
+# Thoran::Selenium::WebDriver::Driver::Attempt#attempt
 
-# 20200419
-# 0.0.1
+# 20260717
+# 0.1.0
 
 # Examples:
 # 1. driver.attempt do |driver|
@@ -13,31 +13,41 @@
 # end
 
 # Changes:
-# 1. + Thoran namespace.
+# 1. Yield self, so that the documented block argument is the driver rather than nil.
+# 2. Use retry rather than loop/break.
+# 3. Re-raise rather than calling quit on @driver, which was never assigned, and exiting the process.
+# 4. - Timeout::Error: Nothing in Selenium 4 raises it. Its own timeouts, and those of
+#   Selenium::WebDriver::Wait, are Selenium::WebDriver::Error::TimeoutError.
+# 5. + The errors a flaky page actually raises, none of which were caught before.
+#   Deliberately excluded: Error::InvalidSelectorError and Error::NoSuchDriverError, which
+#   are programming and environment errors respectively, so retrying only delays the report.
 
 module Thoran
   module Selenium
     module WebDriver
       module Driver
         module Attempt
+          TRANSIENT_ERRORS = [
+            ::Selenium::WebDriver::Error::ElementClickInterceptedError,
+            ::Selenium::WebDriver::Error::ElementNotInteractableError,
+            ::Selenium::WebDriver::Error::NoSuchElementError,
+            ::Selenium::WebDriver::Error::StaleElementReferenceError,
+            ::Selenium::WebDriver::Error::TimeoutError,
+            ::Selenium::WebDriver::Error::UnexpectedAlertOpenError,
+            ::Selenium::WebDriver::Error::UnknownError,
+          ].freeze
 
-          def attempt(max_attempts = 3, &block)
+          def attempt(max_attempts = 3)
             attempts = 0
-            loop do
-              begin
-                yield
-                break
-              rescue Timeout::Error, ::Selenium::WebDriver::Error::UnknownError, ::Selenium::WebDriver::Error::NoSuchElementError => e
-                attempts += 1
-                if attempts >= max_attempts
-                  @driver.quit
-                  puts "Giving up after #{max_attempts} attempts to #{__method__} because #{e}."
-                  exit
-                end
-              end
+            begin
+              yield self
+            rescue *TRANSIENT_ERRORS => e
+              attempts += 1
+              warn "Attempt #{attempts} of #{max_attempts} failed: #{e.class}"
+              retry if attempts < max_attempts
+              raise
             end
           end
-
         end
       end
     end

data/lib/Thoran/Selenium/WebDriver/Driver/ElementPresentQ/element_presentQ.rb

@@ -0,0 +1,37 @@
+# Thoran/Selenium/WebDriver/Driver/ElementPresentQ/element_presentQ.rb
+# Thoran::Selenium::WebDriver::Driver::ElementPresentQ#element_present?
+
+# 20260717
+# 0.1.0
+
+# Examples:
+# 1. driver.element_present?(:xpath, '//a[@id="submit"]')
+# 2. driver.element_present?(:css, '#button-logout')
+
+# Changes:
+# 1. Use the public find_elements() rather than the private bridge.
+# 2. ^Driver, alongside Driver::Attempt, since this patches Driver too. Selenium's
+#   SearchContext is the find_element()/find_elements() contract, which Driver, Element,
+#   and ShadowRoot implement, rather than a home for conveniences built on top of it.
+
+module Thoran
+  module Selenium
+    module WebDriver
+      module Driver
+        module ElementPresentQ
+          def element_present?(selector_type, selector)
+            !find_elements(selector_type, selector).empty?
+          end
+        end
+      end
+    end
+  end
+end
+
+module Selenium
+  module WebDriver
+    class Driver
+      include Thoran::Selenium::WebDriver::Driver::ElementPresentQ
+    end
+  end
+end

data/lib/Thoran/Selenium.rb

@@ -1,11 +1,14 @@
 # Thoran/Selenium.rb
 # Thoran::Selenium
 
-# 20200418
-# 0.0.0
+# 20260717
+# 0.1.0
+
+# Changes:
+# 1. - Selenium::WebDriver::Remote::W3C::Bridge::ConvertLocators
+# 2. - Selenium::WebDriver::SearchContext::ElementsPresentQ
+# 3. - Selenium::WebDriver::Setup
+# 4. /Selenium::WebDriver::SearchContext::ElementPresentQ/Selenium::WebDriver::Driver::ElementPresentQ/
 
 require_relative './Selenium/WebDriver/Driver/Attempt/attempt'
-require_relative './Selenium/WebDriver/Remote/W3C/Bridge/ConvertLocators/convert_locators'
-require_relative './Selenium/WebDriver/SearchContext/ElementPresentQ/element_presentQ'
-require_relative './Selenium/WebDriver/SearchContext/ElementsPresentQ/elements_presentQ'
-require_relative './Selenium/WebDriver/Setup/setup'
+require_relative './Selenium/WebDriver/Driver/ElementPresentQ/element_presentQ'

data/lib/WebAccount/VERSION.rb

@@ -1,5 +1,6 @@
-class WebAccount
-
-  VERSION = '0.3.0'
+# WebAccount/VERSION.rb
+# WebAccount::VERSION
 
+class WebAccount
+  VERSION = '0.4.0'
 end

data/lib/web_account.rb

@@ -3,4 +3,4 @@
 # Notes:
 # 1. This is to enable an alternate means of loading: require 'web_account'.
 
-require_relative 'WebAccount'
+require_relative './webaccount'

data/lib/{WebAccount.rb → webaccount.rb}

@@ -1,17 +1,17 @@
-# WebAccount.rb
+# webaccount.rb
 # WebAccount
 
 require 'selenium-webdriver'
-require 'Thoran/Selenium'
+require_relative './Thoran/Selenium'
+require_relative './WebAccount/VERSION'
 
 class WebAccount
-
   attr_accessor :username
   attr_accessor :password
-  attr_writer :user_agent_alias
 
   def initialize(
     username: nil, password: nil,
+    browser: nil, driver_options: nil,
     login_page_url: nil,
     login_page_username_field_selector: nil, login_page_password_field_selector: nil,
     login_page_submit_button_selector: nil,
@@ -19,6 +19,7 @@ class WebAccount
     logged_out_xpath: nil
   )
     @username, @password = username, password
+    @browser, @driver_options = browser, driver_options
     @login_page_url = login_page_url
     @login_page_username_field_selector, @login_page_password_field_selector = login_page_username_field_selector, login_page_password_field_selector
     @login_page_submit_button_selector = login_page_submit_button_selector
@@ -30,7 +31,6 @@ class WebAccount
     @logged_in = false
     username ||= self.username
     password ||= self.password
-    attempts = 0
     driver.attempt do
       get_login_page
       enter_username(username)
@@ -38,7 +38,7 @@ class WebAccount
       login_page_submit_button.click
     end
     @logged_in = driver_wait.until do
-      driver.element_present?(@logout_button_selector.keys.first, @logout_button_selector.values.first)
+      driver.element_present?(logout_button_selector.keys.first, logout_button_selector.values.first)
     end
   end
   alias_method :logon, :login
@@ -70,20 +70,50 @@ class WebAccount
 
   private
 
-  def user_agent_alias
-    @user_agent_alias ||= @user_agent_alias || :chrome
+  # driver construction
+
+  def default_browser
+    :chrome
+  end
+
+  def browser
+    (@browser || default_browser).to_sym.downcase
+  end
+
+  def default_driver_options
+    nil
+  end
+
+  def driver_options
+    @driver_options || default_driver_options
   end
 
   def driver
-    @driver ||= (
-      driver = Selenium::WebDriver.setup(user_agent_alias)
-      driver.manage.timeouts.implicit_wait = 5
-      driver
-    )
+    @driver ||= Selenium::WebDriver.for(browser, options: driver_options)
+  end
+
+  # waiting
+
+  # For navigation: a submit, the authentication behind it, and the redirect.
+  def default_wait_timeout
+    30
   end
 
   def driver_wait
-    @driver_wait ||= Selenium::WebDriver::Wait.new(timeout: 180)
+    @driver_wait ||= Selenium::WebDriver::Wait.new(timeout: default_wait_timeout)
+  end
+
+  # For lookups: the element should already be on a page which has loaded.
+  def default_find_timeout
+    5
+  end
+
+  def find_wait
+    @find_wait ||= Selenium::WebDriver::Wait.new(timeout: default_find_timeout)
+  end
+
+  def find(selector)
+    find_wait.until{driver.find_element(selector.keys.first, selector.values.first)}
   end
 
   # logging in
@@ -98,16 +128,16 @@ class WebAccount
     username_field.send_keys(username)
   end
 
-  def default_username_field
-    {name: "username"}
+  def default_username_field_selector
+    {name: 'username'}
+  end
+
+  def username_field_selector
+    @login_page_username_field_selector || default_username_field_selector
   end
 
   def username_field
-    if @login_page_username_field_selector
-      driver.find_element(@login_page_username_field_selector.keys.first, @login_page_username_field_selector.values.first)
-    else
-      driver.find_element(default_username_field.keys.first, default_username_field.values.first)
-    end
+    find(username_field_selector)
   end
 
   def enter_password(password = nil)
@@ -115,28 +145,28 @@ class WebAccount
     password_field.send_keys(password)
   end
 
-  def default_password_field
-    {name: "password"}
+  def default_password_field_selector
+    {name: 'password'}
+  end
+
+  def password_field_selector
+    @login_page_password_field_selector || default_password_field_selector
   end
 
   def password_field
-    if @login_page_password_field_selector
-      driver.find_element(@login_page_password_field_selector.keys.first, @login_page_password_field_selector.values.first)
-    else
-      driver.find_element(default_password_field.keys.first, default_password_field.values.first)
-    end
+    find(password_field_selector)
   end
 
   def default_login_page_submit_button_selector
     {xpath: '//input[@type="submit" and @value="Login"]'}
   end
 
+  def login_page_submit_button_selector
+    @login_page_submit_button_selector || default_login_page_submit_button_selector
+  end
+
   def login_page_submit_button
-    if @login_page_submit_button_selector
-      driver.find_element(@login_page_submit_button_selector.keys.first, @login_page_submit_button_selector.values.first)
-    else
-      driver.find_element(default_login_page_submit_button_selector.keys.first, default_login_page_submit_button_selector.values.first)
-    end
+    find(login_page_submit_button_selector)
   end
 
   # logging out
@@ -145,11 +175,11 @@ class WebAccount
     {xpath: '//input[@type="submit" and @value="Logout"]'}
   end
 
+  def logout_button_selector
+    @logout_button_selector || default_logout_button_selector
+  end
+
   def logout_button
-    if @logout_page_submit_button_selector
-      driver.find_element(@logout_button_selector.keys.first, @logout_button_selector.values.first)
-    else
-      driver.find_element(default_logout_button_selector.keys.first, default_logout_button_selector.values.first)
-    end
+    find(logout_button_selector)
   end
 end

data/test/Thoran/Selenium/WebDriver/Driver/Attempt_test.rb

@@ -0,0 +1,169 @@
+# test/Thoran/Selenium/WebDriver/Driver/Attempt_test.rb
+
+# Notes:
+# 1. selenium-webdriver is required first because attempt.rb resolves the Selenium error
+#   classes at load time, in TRANSIENT_ERRORS, but does not require them itself.
+# 2. The transient and non-transient errors are listed here rather than read from
+#   TRANSIENT_ERRORS, so that these tests state which errors are meant to be retried rather
+#   than agreeing with whatever the implementation happens to say.
+# 3. No driver, no browser: the errors are raised directly at a dummy including the module.
+
+require 'selenium-webdriver'
+require_relative '../../../../../lib/Thoran/Selenium/WebDriver/Driver/Attempt/attempt'
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+class AttemptDummy
+  include Thoran::Selenium::WebDriver::Driver::Attempt
+end
+
+describe Thoran::Selenium::WebDriver::Driver::Attempt do
+  TRANSIENT = [
+    Selenium::WebDriver::Error::ElementClickInterceptedError,
+    Selenium::WebDriver::Error::ElementNotInteractableError,
+    Selenium::WebDriver::Error::NoSuchElementError,
+    Selenium::WebDriver::Error::StaleElementReferenceError,
+    Selenium::WebDriver::Error::TimeoutError,
+    Selenium::WebDriver::Error::UnexpectedAlertOpenError,
+    Selenium::WebDriver::Error::UnknownError,
+  ]
+
+  NON_TRANSIENT = [
+    Selenium::WebDriver::Error::InvalidSelectorError,
+    Selenium::WebDriver::Error::NoSuchDriverError,
+    ArgumentError,
+  ]
+
+  before do
+    @dummy = AttemptDummy.new
+  end
+
+  context "when the block succeeds" do
+    it "returns the value of the block" do
+      expect(@dummy.attempt{42}).must_equal(42)
+    end
+
+    it "yields itself, so that the documented block argument is the receiver" do
+      yielded = nil
+      @dummy.attempt{|driver| yielded = driver}
+      expect(yielded).must_be_same_as(@dummy)
+    end
+
+    it "calls the block once" do
+      calls = 0
+      @dummy.attempt{calls += 1}
+      expect(calls).must_equal(1)
+    end
+
+    it "says nothing" do
+      _out, err = capture_io{@dummy.attempt{42}}
+      expect(err).must_be_empty
+    end
+  end
+
+  context "when the block raises a transient error" do
+    TRANSIENT.each do |error_class|
+      it "retries #{error_class}" do
+        calls = 0
+        capture_io do
+          @dummy.attempt(3) do
+            calls += 1
+            raise error_class if calls < 3
+          end
+        end
+        expect(calls).must_equal(3)
+      end
+    end
+
+    it "returns the value of the attempt which succeeds" do
+      calls = 0
+      value = nil
+      capture_io do
+        value = @dummy.attempt(3) do
+          calls += 1
+          raise Selenium::WebDriver::Error::StaleElementReferenceError if calls < 2
+          :recovered
+        end
+      end
+      expect(value).must_equal(:recovered)
+    end
+
+    it "re-raises once max_attempts is reached" do
+      capture_io do
+        expect do
+          @dummy.attempt(3){raise Selenium::WebDriver::Error::UnknownError}
+        end.must_raise(Selenium::WebDriver::Error::UnknownError)
+      end
+    end
+
+    it "makes exactly max_attempts attempts before re-raising" do
+      calls = 0
+      capture_io do
+        begin
+          @dummy.attempt(3){calls += 1; raise Selenium::WebDriver::Error::UnknownError}
+        rescue Selenium::WebDriver::Error::UnknownError
+        end
+      end
+      expect(calls).must_equal(3)
+    end
+
+    it "honours a supplied max_attempts" do
+      calls = 0
+      capture_io do
+        begin
+          @dummy.attempt(5){calls += 1; raise Selenium::WebDriver::Error::UnknownError}
+        rescue Selenium::WebDriver::Error::UnknownError
+        end
+      end
+      expect(calls).must_equal(5)
+    end
+
+    it "defaults to three attempts" do
+      calls = 0
+      capture_io do
+        begin
+          @dummy.attempt{calls += 1; raise Selenium::WebDriver::Error::UnknownError}
+        rescue Selenium::WebDriver::Error::UnknownError
+        end
+      end
+      expect(calls).must_equal(3)
+    end
+
+    it "warns once per failed attempt, naming the error" do
+      _out, err = capture_io do
+        begin
+          @dummy.attempt(2){raise Selenium::WebDriver::Error::StaleElementReferenceError}
+        rescue Selenium::WebDriver::Error::StaleElementReferenceError
+        end
+      end
+      expect(err.lines.size).must_equal(2)
+      expect(err).must_match(/Attempt 1 of 2 failed: Selenium::WebDriver::Error::StaleElementReferenceError/)
+      expect(err).must_match(/Attempt 2 of 2 failed: Selenium::WebDriver::Error::StaleElementReferenceError/)
+    end
+  end
+
+  context "when the block raises a non-transient error" do
+    NON_TRANSIENT.each do |error_class|
+      it "does not retry #{error_class}" do
+        calls = 0
+        capture_io do
+          expect do
+            @dummy.attempt(3){calls += 1; raise error_class}
+          end.must_raise(error_class)
+        end
+        expect(calls).must_equal(1)
+      end
+    end
+
+    it "says nothing, since it did not retry" do
+      _out, err = capture_io do
+        begin
+          @dummy.attempt(3){raise Selenium::WebDriver::Error::InvalidSelectorError}
+        rescue Selenium::WebDriver::Error::InvalidSelectorError
+        end
+      end
+      expect(err).must_be_empty
+    end
+  end
+end

data/webaccount.gemspec

@@ -0,0 +1,47 @@
+require_relative './lib/WebAccount/VERSION'
+
+class Gem::Specification
+  def dependencies=(gems)
+    gems.each{|gem| add_dependency(*gem)}
+  end
+
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'webaccount'
+  spec.version = WebAccount::VERSION
+
+  spec.summary = "An abstract super-class for navigating a web-based user account via Selenium WebDriver."
+  spec.description = "Easily log into web accounts by supplying just a username and password, the URL of the login page, and a few page ids to a sub-class of WebAccount."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'http://github.com/thoran/WebAccount'
+  spec.license = 'MIT'
+
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.files = [
+    'CHANGELOG',
+    'Gemfile',
+    Dir['lib/**/*.rb'],
+    'Rakefile',
+    'README.md',
+    Dir['test/**/*.rb'],
+    'webaccount.gemspec'
+  ].flatten
+
+  spec.dependencies = [
+    ['selenium-webdriver', '>= 4.0']
+  ]
+
+  spec.development_dependencies = %w{
+    minitest
+    minitest-spec-context
+    rake
+  }
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: webaccount
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - thoran
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -16,9 +15,51 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.0'
   type: :runtime
   prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-spec-context
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -31,23 +72,22 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/Thoran/Array/AllButFirst/all_but_first.rb
-- lib/Thoran/Array/FirstX/firstX.rb
+- CHANGELOG
+- Gemfile
+- README.md
+- Rakefile
 - lib/Thoran/Selenium.rb
 - lib/Thoran/Selenium/WebDriver/Driver/Attempt/attempt.rb
-- lib/Thoran/Selenium/WebDriver/Remote/W3C/Bridge/ConvertLocators/convert_locators.rb
-- lib/Thoran/Selenium/WebDriver/SearchContext/ElementPresentQ/element_presentQ.rb
-- lib/Thoran/Selenium/WebDriver/SearchContext/ElementsPresentQ/elements_presentQ.rb
-- lib/Thoran/Selenium/WebDriver/Setup/setup.rb
-- lib/Thoran/String/ToConst/to_const.rb
-- lib/WebAccount.rb
+- lib/Thoran/Selenium/WebDriver/Driver/ElementPresentQ/element_presentQ.rb
 - lib/WebAccount/VERSION.rb
 - lib/web_account.rb
+- lib/webaccount.rb
+- test/Thoran/Selenium/WebDriver/Driver/Attempt_test.rb
+- webaccount.gemspec
 homepage: http://github.com/thoran/WebAccount
 licenses:
-- Ruby
+- MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -55,15 +95,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: An abstract super-class for navigating a web-based user account via Selenium
   WebDriver.

data/lib/Thoran/Array/AllButFirst/all_but_first.rb

@@ -1,28 +0,0 @@
-# Thoran/Array/AllButFirst/all_but_first.rb
-# Thoran::Array::AllButFirst#all_but_first
-
-# 20141223
-# 0.1.0
-
-# Description: This returns a copy of the receiving array with the first element removed.  
-
-# Changes:
-# 1. + Thoran namespace.
-
-require 'Thoran/Array/FirstX/firstX'
-
-module Thoran
-  module Array
-    module AllButFirst
-
-      def all_but_first
-        d = self.dup
-        d.first!
-        d
-      end
-
-    end
-  end
-end
-
-Array.send(:include, Thoran::Array::AllButFirst)

data/lib/Thoran/Array/FirstX/firstX.rb

@@ -1,21 +0,0 @@
-# Thoran/Array/FirstX/firstX.rb
-# Thoran::Array::FirstX#first!
-
-# 20141223
-# 0.1.0
-
-# Description: Sometimes it makes more sense to treat arrays this way.
-
-module Thoran
-  module Array
-    module FirstX
-
-      def first!
-        shift
-      end
-
-    end
-  end
-end
-
-Array.send(:include, Thoran::Array::FirstX)

data/lib/Thoran/Selenium/WebDriver/Remote/W3C/Bridge/ConvertLocators/convert_locators.rb

@@ -1,51 +0,0 @@
-# Thoran/Selenium/WebDriver/Remote/W3C/BridgeMonkeyPatch/ConvertLocators.convert_locators.rb
-# Thoran::Selenium::WebDriver::Remote::W3C::BridgeMonkeyPatch::ConvertLocators.convert_locators
-
-# 20200418
-# 0.0.0
-
-# Changes:
-# 1. + Thoran namespace.
-
-module Thoran
-  module Selenium
-    module WebDriver
-      module Remote
-        module W3C
-          module Bridge
-            module ConvertLocators
-
-              def convert_locators(how, what)
-                case how.to_s
-                when 'class name'
-                  how = 'css selector'
-                  what = ".#{escape_css(what)}"
-                when 'id'
-                  how = 'css selector'
-                  what = "##{escape_css(what)}"
-                when 'name'
-                  how = 'css selector'
-                  what = "*[name='#{escape_css(what)}']"
-                when 'tag name'
-                  how = 'css selector'
-                end
-                [how, what]
-              end
-
-            end
-          end
-        end
-      end
-    end
-  end
-end
-
-module Selenium
-  module WebDriver
-    module Remote
-      module W3C
-        Bridge.prepend(Thoran::Selenium::WebDriver::Remote::W3C::Bridge::ConvertLocators)
-      end
-    end
-  end
-end

data/lib/Thoran/Selenium/WebDriver/SearchContext/ElementPresentQ/element_presentQ.rb

@@ -1,39 +0,0 @@
-# Thoran/Selenium/WebDriver/SearchContext/ElementPresentQ/element_presentQ.rb
-# Thoran::Selenium::WebDriver::SearchContext::ElementPresentQ.element_present?
-
-# 20200418
-# 0.0.0
-
-# Examples:
-# 1. driver.element_present?(:xpath, '//a[@id="submit"]')
-# 2. driver.element_present?(:id, @logout_button_id)
-
-# Changes:
-# 1. + Thoran namespace.
-
-module Thoran
-  module Selenium
-    module WebDriver
-      module SearchContext
-        module ElementPresentQ
-
-          def element_present?(selector_type, selector)
-            bridge.find_element_by(selector_type, selector)
-            true
-          rescue ::Selenium::WebDriver::Error::NoSuchElementError
-            false
-          end
-
-        end
-      end
-    end
-  end
-end
-
-module Selenium
-  module WebDriver
-    class Driver
-      include Thoran::Selenium::WebDriver::SearchContext::ElementPresentQ
-    end
-  end
-end

data/lib/Thoran/Selenium/WebDriver/SearchContext/ElementsPresentQ/elements_presentQ.rb

@@ -1,39 +0,0 @@
-# Thoran/Selenium/WebDriver/SearchContext/ElementsPresentQ/elements_presentQ.rb
-# Thoran::Selenium::WebDriver::SearchContext::ElementsPresentQ.elements_present?
-
-# 20200418
-# 0.0.0
-
-# Examples:
-# 1. driver.elements_present?(:xpath, '//li[@class="item"]')
-# 2. driver.elements_present?(:css, 'li.item')
-
-# Changes:
-# 1. + Thoran namespace.
-
-module Thoran
-  module Selenium
-    module WebDriver
-      module SearchContext
-        module ElementsPresentQ
-
-          def elements_present?(selector_type, selector)
-            bridge.find_elements_by(selector_type, selector)
-            true
-          rescue ::Selenium::WebDriver::Error::NoSuchElementError
-            false
-          end
-
-        end
-      end
-    end
-  end
-end
-
-module Selenium
-  module WebDriver
-    class Driver
-      include Thoran::Selenium::WebDriver::SearchContext::ElementsPresentQ
-    end
-  end
-end

data/lib/Thoran/Selenium/WebDriver/Setup/setup.rb

@@ -1,66 +0,0 @@
-# Thoran/Selenium/WebDriver/Setup/setup.rb
-# Thoran::Selenium::WebDriver.setup
-
-# 20200419
-# 0.0.1
-
-# Usage:
-# 1. Binary is in the path:
-#   Selenium::WebDriver.setup('chrome') # String - lowercase
-#   Selenium::WebDriver.setup('Chrome') # String - capitalised
-#   Selenium::WebDriver.setup(:chrome) # Symbol - lowercase
-#   Selenium::WebDriver.setup(:Chrome) # Symbol - capitalised
-# 2. Binary is not in the path:
-#   Selenium::WebDriver.setup('~/Applications/Firefox.app/Contents/MacOS/firefox-bin')
-
-# Changes:
-# 1. + Thoran namespace.
-
-require 'selenium-webdriver'
-require 'Thoran/String/ToConst/to_const'
-
-module Thoran
-  module Selenium
-    module WebDriver
-      module Setup
-
-        def setup(path_or_browser)
-          if File.exist?(File.expand_path(path_or_browser.to_s))
-            path = path_or_browser
-            at(path)
-            ::Selenium::WebDriver.for(selenium_browser(path))
-          else
-            browser = path_or_browser.to_sym.downcase
-            ::Selenium::WebDriver.for(browser)
-          end
-        end
-
-        private
-
-        def at(path)
-          selenium_binary_constant(path).path = File.expand_path(path)
-        end
-
-        def selenium_browser(path)
-          case path
-          when /chrome/i; :chrome
-          when /firefox/i; :firefox
-          when /safari/i; :safari
-          end
-        end
-
-        # This method seem to be necessary only to Firefox, since there are no equivalent constants for Safari or Chrome.
-        def selenium_binary_constant(path)
-          "Selenium::WebDriver::#{selenium_browser(path).to_s.capitalize}::Binary".to_const
-        end
-
-      end
-    end
-  end
-end
-
-module Selenium
-  module WebDriver
-    extend Thoran::Selenium::WebDriver::Setup
-  end
-end

data/lib/Thoran/String/ToConst/to_const.rb

@@ -1,47 +0,0 @@
-# Thoran/String/ToConst/to_const.rb
-# Thoran::String::ToConst#to_const
-
-# 20141223
-# 0.2.0
-
-# Description: This takes a string and returns a constant, with unlimited namespacing.
-
-# History: Derived from Object#to_const 0.3.0, and superceding Object#to_const.
-
-# Changes:
-# 1. + Thoran namespace.
-
-# Todo:
-# 1. This only works for two levels of constants.  Three and you're stuffed.  So, this needs to be recursive...
-#   Done iteratively as of 0.1.0.
-# 2. Make this work for symbols.  However, this will only work if there's no namespacing.  ie. :A is OK, but :A::B is not.
-
-# Discussion:
-# 1. Should this go separately into classes for which ::const_get will work and be removed from Object?  Done as of 0.1.0.
-
-require 'Thoran/Array/AllButFirst/all_but_first'
-
-module Thoran
-  module String
-    module ToConst
-
-      def to_const
-        if self =~ /::/
-          constants = self.split('::')
-          constant = Object.const_get(constants.first)
-          constants = constants.all_but_first
-          until constants.empty? do
-            constant = constant.const_get(constants.shift)
-          end
-        else
-          constant = Object.const_get(self)
-        end
-        constant
-      end
-      alias_method :to_constant, :to_const
-
-    end
-  end
-end
-
-String.send(:include, Thoran::String::ToConst)