webaccount 0.3.1 → 0.5.0

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
@@ -56,6 +56,10 @@ class WebAccount
     driver.quit
   end
 
+  def driver
+    @driver ||= Selenium::WebDriver.for(browser, options: driver_options)
+  end
+
   # predicate methods
 
   def logged_in?
@@ -70,20 +74,46 @@ class WebAccount
 
   private
 
-  def user_agent_alias
-    @user_agent_alias ||= @user_agent_alias || :chrome
+  # driver construction
+
+  def default_browser
+    :chrome
   end
 
-  def driver
-    @driver ||= (
-      driver = Selenium::WebDriver.setup(user_agent_alias)
-      driver.manage.timeouts.implicit_wait = 5
-      driver
-    )
+  def browser
+    (@browser || default_browser).to_sym.downcase
+  end
+
+  def default_driver_options
+    nil
+  end
+
+  def driver_options
+    @driver_options || default_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/test/webaccount_test.rb

@@ -0,0 +1,45 @@
+# test/webaccount_test.rb
+
+# Notes:
+# 1. No browser: Selenium::WebDriver.for is swapped for a stand-in for the length of
+#   each example and put back afterwards, so what is asserted is what WebAccount asks
+#   of Selenium and what it hands back.
+
+require_relative '../lib/webaccount'
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+describe WebAccount do
+  def with_driver_factory(&block)
+    calls = []
+    stand_in = Object.new
+    original = Selenium::WebDriver.method(:for)
+    Selenium::WebDriver.define_singleton_method(:for){|browser, options: nil| calls << [browser, options]; stand_in}
+    block.call(stand_in, calls)
+  ensure
+    Selenium::WebDriver.define_singleton_method(:for, original)
+  end
+
+  describe "#driver" do
+    it "is public, so that the logged-in browser can be driven from outside" do
+      _(WebAccount.public_method_defined?(:driver)).must_equal(true)
+    end
+
+    it "is the browser Selenium made, made once" do
+      with_driver_factory do |stand_in, calls|
+        account = WebAccount.new
+        _(account.driver).must_be_same_as(stand_in)
+        _(account.driver).must_be_same_as(stand_in)
+        _(calls.length).must_equal(1)
+      end
+    end
+
+    it "is made with the browser and driver options given" do
+      with_driver_factory do |stand_in, calls|
+        WebAccount.new(browser: 'Firefox', driver_options: :options).driver
+        _(calls).must_equal([[:firefox, :options]])
+      end
+    end
+  end
+end

data/webaccount.gemspec

@@ -0,0 +1,48 @@
+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 = 'https://github.com/thoran/webaccount'
+  spec.license = 'MIT'
+
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.files = [
+    'CHANGELOG',
+    'LICENSE',
+    '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.1
+  version: 0.5.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,24 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/Thoran/Array/AllButFirst/all_but_first.rb
-- lib/Thoran/Array/FirstX/firstX.rb
+- CHANGELOG
+- Gemfile
+- LICENSE
+- 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/WebAccount/VERSION.rb
+- lib/Thoran/Selenium/WebDriver/Driver/ElementPresentQ/element_presentQ.rb
 - lib/web_account.rb
-homepage: http://github.com/thoran/WebAccount
+- lib/webaccount.rb
+- lib/webaccount/VERSION.rb
+- test/Thoran/Selenium/WebDriver/Driver/Attempt_test.rb
+- test/webaccount_test.rb
+- webaccount.gemspec
+homepage: https://github.com/thoran/webaccount
 licenses:
-- Ruby
+- MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -55,15 +97,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.7
-signing_key:
+rubygems_version: 4.0.22
 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