ruby_raider 3.10.0 → 3.12.0

data/lib/generators/templates/helpers/raider_element.tt

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+<%- if mobile? -%>
+# An element found through WaitHelper. It has the same waiting methods as the
+# mixin, minus the locator, so calls chain:
+#   find_element(accessibility_id: 'list').find_element(accessibility_id: 'row').tap
+#   find_element(accessibility_id: 'card').swipe('left')
+# Everything else (tag_name, rect, location, ...) goes to the raw Appium
+# element without waiting. APIs that type-check their argument
+# (driver.action, execute_script) need .native.
+<%- else -%>
+# An element found through WaitHelper. It has the same waiting methods as the
+# mixin, minus the locator, so calls chain:
+#   find_element(css: '.form').find_element(id: 'email').send_keys('a')
+# Everything else (tag_name, rect, property, ...) goes to the raw Selenium
+# element without waiting. Selenium APIs that type-check their argument
+# (switch_to.frame, Support::Select, driver.action, execute_script) need .native.
+<%- end -%>
+class RaiderElement
+  def initialize(driver, lookup)
+    @driver = driver
+    @lookup = lookup
+  end
+
+  def native
+    @lookup.element
+  end
+
+  def find_element(locator = nil, visible: true, timeout: nil, **by)
+    waiter(timeout).find_element(child(locator, by), visible)
+  end
+
+  def find_elements(locator = nil, timeout: nil, **by)
+    waiter(timeout).find_elements(child(locator, by))
+  end
+
+<%- if mobile? -%>
+  %i[click clear].each do |action|
+    define_method(action) do |timeout: nil|
+      perform(action, timeout) { |element| element.public_send(action) }
+      self
+    end
+  end
+
+  # tap is Appium's word for click. With a block it stays Ruby's Object#tap.
+  def tap(timeout: nil, &block)
+    return super(&block) if block
+
+    perform(:tap, timeout, &:click)
+    self
+  end
+<%- else -%>
+  %i[click clear submit].each do |action|
+    define_method(action) do |timeout: nil|
+      perform(action, timeout) { |element| element.public_send(action) }
+      self
+    end
+  end
+<%- end -%>
+
+  %i[text displayed? enabled? selected?].each do |reader|
+    define_method(reader) do |timeout: nil|
+      perform(reader, timeout) { |element| element.public_send(reader) }
+    end
+  end
+
+  def send_keys(*keys, timeout: nil)
+    perform(:send_keys, timeout) { |element| element.send_keys(*keys) }
+    self
+  end
+
+<%- unless mobile? -%>
+  def select_by(how, what, timeout: nil)
+    perform(:select_by, timeout) { |element| Selenium::WebDriver::Support::Select.new(element).select_by(how, what) }
+    self
+  end
+
+<%- end -%>
+  def attribute(name, timeout: nil)
+    perform(:attribute, timeout) { |element| element.attribute(name) }
+  end
+
+<%- if mobile? -%>
+  # direction: 'up', 'down', 'left' or 'right'.
+  %i[swipe scroll].each do |kind|
+    define_method(kind) do |direction, timeout: nil|
+      gesture = WaitHelper::Gesture.new(@driver, kind, direction)
+      perform(kind, timeout) { |element| gesture.perform(element) }
+      self
+    end
+  end
+
+  # Scrolls the screen until this element is visible, up to max_scrolls times.
+  def scroll_to(direction: 'down', max_scrolls: 10, timeout: nil)
+    scroller = WaitHelper::Scroller.new(WaitHelper::Gesture.new(@driver, :scroll, direction), max_scrolls)
+    waiter(timeout).perform_action(:scroll_to, @lookup, WaitHelper::Waiter::CHECKS[:scroll_to], between: scroller) { nil }
+    self
+  end
+<%- else -%>
+  def hover(timeout: nil)
+    perform(:hover, timeout) { |element| @driver.action.move_to(element).perform }
+    self
+  end
+
+  def scroll_into_view(timeout: nil)
+    perform(:scroll_into_view, timeout) { |element| @driver.action.scroll_to(element).perform }
+    self
+  end
+
+  # target: a RaiderElement, a raw element, or a driver-scoped locator.
+  def drag_and_drop(target, timeout: nil)
+    drop = WaitHelper::Lookup.for(@driver, target, {})
+    waiter(timeout).perform_action(:drag_and_drop, @lookup, WaitHelper::Waiter::CHECKS[:drag_and_drop],
+                                   target: drop) do |source, destination|
+      @driver.action.drag_and_drop(source, destination).perform
+    end
+    self
+  end
+<%- end -%>
+
+  def ==(other)
+    native == (other.is_a?(RaiderElement) ? other.native : other)
+  end
+
+  def eql?(other)
+    self == other
+  end
+
+  def hash
+    native.hash
+  end
+
+  private
+
+  # WaitHelper::Lookup.for reads this to reuse how a wrapper was found.
+  attr_reader :lookup
+
+  def waiter(timeout)
+    WaitHelper::Waiter.new(@driver, timeout: timeout)
+  end
+
+  def child(locator, by)
+    WaitHelper::Lookup.for(@driver, locator, by, scope: @lookup)
+  end
+
+  def perform(action, timeout, &block)
+    waiter(timeout).perform_action(action, @lookup, WaitHelper::Waiter::CHECKS.fetch(action), &block)
+  end
+
+  def method_missing(name, *args, **options, &block)
+    return super unless native.respond_to?(name)
+
+    native.public_send(name, *args, **options, &block)
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    native.respond_to?(name) || super
+  end
+end

data/lib/generators/templates/helpers/session_state.tt

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'time'
+require 'uri'
+require 'yaml'
+
+# Saves the browser login (cookies, localStorage, sessionStorage) to .raider/auth/<name>.json
+# and restores it into a new browser. The file holds live session tokens: it is git-ignored,
+# written 0600, and its values are never printed.
+#
+#   SessionState.new(driver, name: 'user').reuse(valid: -> { account.logged_in? }) { log_in }
+#
+# RAIDER_LOGIN_STATE=off always logs in and never saves; =refresh logs in and saves again.
+# Stale age is login_state.max_age (seconds) in config/config.yml.
+class SessionState
+  FORMAT = 1
+  DEFAULT_MAX_AGE = 3600
+  NAME_PATTERN = /\A[a-z0-9_-]+\z/.freeze
+  DIR = File.join('.raider', 'auth')
+  READ_STORAGE = 'return Object.assign({}, window[arguments[0]]);'
+  WRITE_STORAGE = 'var s = window[arguments[0]]; s.clear(); var d = arguments[1]; ' \
+                  'Object.keys(d).forEach(function (k) { s.setItem(k, d[k]); });'
+  STORAGES = { 'local_storage' => 'localStorage', 'session_storage' => 'sessionStorage' }.freeze
+  COOKIE_KEYS = %i[name value domain path secure http_only same_site].freeze
+
+  attr_reader :name
+
+  def initialize(driver, name: 'user')
+    raise ArgumentError, "name must match #{NAME_PATTERN.source}" unless name.to_s.match?(NAME_PATTERN)
+
+    @driver = driver
+    @name = name.to_s
+  end
+
+  def path
+    File.join(DIR, "#{name}.json")
+  end
+
+  def reuse(valid: nil, &login)
+    lock = open_lock unless ENV.fetch('RAIDER_LOGIN_STATE', nil) == 'off'
+    lock ? reuse_locked(lock, valid, &login) : login.call
+    true
+  end
+
+  def save
+    ensure_dir
+    visit_origin
+    state = { 'format' => FORMAT, 'name' => name, 'origin' => origin, 'saved_at' => Time.now.utc.iso8601,
+              'cookies' => @driver.manage.all_cookies.map { |cookie| dump_cookie(cookie) } }
+    STORAGES.each { |key, kind| state[key] = @driver.execute_script(READ_STORAGE, kind) || {} }
+    write_atomically(JSON.generate(state))
+    path
+  end
+
+  def restore
+    state = read_state
+    usable?(state) && apply(state)
+  rescue StandardError => e
+    fall_back("could not restore #{path} (#{e.class})")
+  end
+
+  def clear
+    FileUtils.rm_f(path)
+  end
+
+  def fresh?
+    state = read_state
+    usable?(state) && Time.now - Time.iso8601(state['saved_at']) < max_age
+  rescue ArgumentError, TypeError
+    false
+  end
+
+  private
+
+  # Warnings wait until the outcome is known: a peer's save can still rescue a failed restore,
+  # and each fallback warns once, only when it really logs in.
+  def reuse_locked(lock, valid, &login)
+    @reason = @note = nil
+    @deferred = true
+    reused = reused?(lock, valid)
+    @deferred = false
+    return warn(@note) if reused && @note
+    return if reused
+
+    warn("[login_state] #{@reason}, logging in again") if @reason
+    clear
+    reset if @applied
+    login.call
+    save_after_login
+  ensure
+    lock.close
+  end
+
+  # Restores under a shared lock, so parallel workers restore at the same time; only a real
+  # login takes the exclusive lock. Upgrading drops the shared lock first, so a worker that
+  # gets the exclusive lock after another one saved restores that login instead.
+  def reused?(lock, valid)
+    if ENV.fetch('RAIDER_LOGIN_STATE', nil) == 'refresh'
+      lock.flock(File::LOCK_EX)
+      return false
+    end
+    lock.flock(File::LOCK_SH)
+    seen = saved_signature
+    return true if restored?(valid)
+
+    lock.flock(File::LOCK_UN) # Windows will not upgrade a held shared lock in place
+    lock.flock(File::LOCK_EX)
+    saved_signature != seen && restored?(valid)
+  end
+
+  def restored?(valid)
+    fresh? && restore && still_valid?(valid)
+  end
+
+  # inode, mtime and size: mtime alone misses a save in the same second on coarse filesystems
+  def saved_signature
+    stat = File.stat(path)
+    [stat.ino, stat.mtime, stat.size]
+  rescue SystemCallError
+    nil
+  end
+
+  def open_lock
+    ensure_dir
+    File.open(File.join(DIR, "#{name}.lock"), File::RDWR | File::CREAT, 0o600)
+  rescue SystemCallError => e
+    fall_back("cannot write #{DIR} (#{e.class}), so nothing is saved")
+  end
+
+  def save_after_login
+    save
+  rescue StandardError => e
+    warn("[login_state] could not save #{path} (#{e.class}), the next run logs in again")
+  end
+
+  def reset
+    visit_origin
+    @driver.manage.delete_all_cookies
+    STORAGES.each_value { |kind| @driver.execute_script(WRITE_STORAGE, kind, {}) }
+  rescue StandardError
+    nil # a browser that cannot be reset fails the real login on its own
+  end
+
+  def visit_origin
+    @driver.navigate.to("#{origin}/") unless origin_of(URI.parse(@driver.current_url.to_s)) == origin
+  end
+
+  def still_valid?(valid)
+    valid.nil? || valid.call || fall_back("login restored from #{path} is no longer valid")
+  rescue StandardError => e
+    fall_back("validity check failed (#{e.class})")
+  end
+
+  def apply(state)
+    @driver.navigate.to("#{origin}/")
+    @applied = true
+    @driver.manage.delete_all_cookies
+    live, skipped = state['cookies'].partition { |cookie| live_for_origin?(cookie) }
+    live.each { |cookie| add_cookie(load_cookie(cookie)) }
+    note("[login_state] #{skipped.size} cookies skipped (expired or another domain) from #{path}") if skipped.any?
+    STORAGES.each { |key, kind| @driver.execute_script(WRITE_STORAGE, kind, state[key] || {}) }
+    @driver.navigate.refresh
+    true
+  end
+
+  def add_cookie(attributes)
+    @driver.manage.add_cookie(attributes.dup) # Selenium's Manager rewrites the hash it is given
+  rescue StandardError
+    raise unless attributes.key?(:same_site)
+
+    @driver.manage.add_cookie(attributes.except(:same_site))
+  end
+
+  def live_for_origin?(cookie)
+    (cookie['expires'].nil? || Time.iso8601(cookie['expires']) > Time.now) && domain_matches?(cookie['domain'])
+  end
+
+  def domain_matches?(domain)
+    bare = domain.to_s.delete_prefix('.')
+    bare.empty? || base_uri.host == bare || base_uri.host.end_with?(".#{bare}")
+  end
+
+  def dump_cookie(cookie)
+    COOKIE_KEYS.to_h { |key| [key.to_s, cookie[key]] }.merge('expires' => cookie[:expires]&.to_time&.utc&.iso8601)
+  end
+
+  def load_cookie(cookie)
+    COOKIE_KEYS.to_h { |key| [key, cookie[key.to_s]] }
+               .merge(expires: cookie['expires'] && Time.iso8601(cookie['expires'])).compact
+  end
+
+  def read_state
+    JSON.parse(File.read(path)) if File.exist?(path)
+  rescue JSON::ParserError, SystemCallError
+    fall_back("#{path} is unreadable or corrupt")
+  end
+
+  def usable?(state)
+    return false unless state
+    return state['origin'] == origin if state.is_a?(Hash) && state['format'] == FORMAT
+
+    fall_back("#{path} has an unsupported format")
+  end
+
+  def write_atomically(json)
+    temp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+    File.write(temp, json, perm: 0o600)
+    File.rename(temp, path)
+  end
+
+  def ensure_dir
+    FileUtils.chmod(0o700, FileUtils.mkdir_p(DIR))
+  end
+
+  def config
+    @config ||= YAML.load_file('config/config.yml') || {}
+  end
+
+  def max_age
+    Integer(config.dig('login_state', 'max_age') || DEFAULT_MAX_AGE)
+  end
+
+  def base_uri
+    @base_uri ||= URI.parse(config.fetch('url'))
+  end
+
+  def origin
+    @origin ||= origin_of(base_uri)
+  end
+
+  def origin_of(uri)
+    port = uri.port == uri.default_port ? '' : ":#{uri.port}"
+    "#{uri.scheme}://#{uri.host}#{port}"
+  end
+
+  def fall_back(reason)
+    @deferred ? (@reason ||= reason) : warn("[login_state] #{reason}, logging in again")
+    false
+  end
+
+  def note(message)
+    @deferred ? @note = message : warn(message)
+  end
+end

data/lib/generators/templates/helpers/spec_helper.tt

@@ -13,6 +13,17 @@ require_relative 'browser_helper'
 require_relative 'driver_helper'
 <%- end -%>
 require_relative 'video_helper'
+<%- if wait_helper? -%>
+require_relative 'wait_helper'
+<%- end -%>
+<%- if web? -%>
+require_relative 'session_state'
+<%- end -%>
+<%- if web? && examples? -%>
+require_relative '../models/model_factory'
+require_relative '../page_objects/pages/login'
+require_relative '../page_objects/pages/account'
+<%- end -%>
 
 module SpecHelper
   RSpec.configure do |config|
@@ -26,6 +37,9 @@ module SpecHelper
     <%- else -%>
     config.include(DriverHelper)
     <%- end -%>
+    <%- if wait_helper? -%>
+    config.include(WaitHelper)
+    <%- end -%>
     <%- if mobile? -%>
     config.before(:each) do
       driver.start_driver
@@ -49,6 +63,20 @@ module SpecHelper
       @video_recorder = VideoHelper.recorder_for(<%= watir? ? 'browser' : 'driver' %>)
       @video_recorder.start
     end
+<%- if web? && examples? -%>
+
+    config.before(:each, :logged_in) do
+      user = ModelFactory.for('users')['registered user']
+      account = Account.new(<%= watir? ? 'browser' : 'driver' %>)
+      SessionState.new(<%= watir? ? 'browser.driver' : 'driver' %>).reuse(
+        valid: -> { account.tap(&:visit).header.customer_name == "Welcome back #{user['name']}" }
+      ) do
+        login = Login.new(<%= watir? ? 'browser' : 'driver' %>)
+        login.visit
+        login.login(user['username'], user['password'])
+      end
+    end
+<%- end -%>
 
     config.after(:each) do |example|
       example_name = example.description