ruby_raider 3.13.0 → 4.0.0

data/spec/runtime/matchers/retrying_block_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+
+RSpec.describe 'Raider block expectations with value matchers' do
+  include Raider::Matchers
+
+  before { Raider.timeout = 0.3 }
+
+  after { Raider.reset }
+
+  let(:counter) do
+    Class.new do
+      attr_reader :calls
+
+      def initialize = @calls = 0
+      def next_value = @calls += 1
+    end.new
+  end
+
+  it 'retries a value matcher until the block value matches' do
+    expect { counter.next_value }.to eq(3)
+    expect(counter.calls).to eq(3)
+  end
+
+  it 'fails with the waited time and rspec own message' do
+    expect { expect { 1 }.to eq(2) }
+      .to raise_error(RSpec::Expectations::ExpectationNotMetError, /\(waited 0\.[34]\d?s\) \nexpected: 2\n     got: 1/)
+  end
+
+  it 'fails a negated matcher with the waited time' do
+    expect { expect { 'x' }.not_to eq('x') }
+      .to raise_error(RSpec::Expectations::ExpectationNotMetError, /\(waited 0\.[34]\d?s\) \nexpected: value != "x"\n     got: "x"/)
+  end
+
+  it 'retries not_to include until the value stops including it' do
+    values = [%w[x y], %w[x], %w[y]]
+    expect { values.size > 1 ? values.shift : values.first }.not_to include('x')
+  end
+
+  it 'retries to_not as well' do
+    values = [1, 1, 2]
+    expect { values.size > 1 ? values.shift : values.first }.to_not eq(1) # rubocop:disable RSpec/NotToNot
+  end
+
+  it 'retries match, be_empty and be > 3' do
+    n = 0
+    expect { (n += 1) > 1 ? 'abc' : 'x' }.to match(/abc/)
+    m = 0
+    expect { (m += 1) > 1 ? [] : [1] }.to be_empty
+    k = 0
+    expect { k += 1 }.to be > 3
+  end
+
+  it 'retries through lookup errors' do
+    calls = 0
+    result = proc do
+      raise Selenium::WebDriver::Error::NoSuchElementError, 'gone' if (calls += 1) <= 2
+
+      'ok'
+    end
+    expect(&result).to eq('ok')
+    expect(calls).to eq(3)
+  end
+
+  it 'retries AmbiguousMatch and stale elements' do
+    calls = 0
+    expect do
+      calls += 1
+      raise Raider::AmbiguousMatch.new('d', []) if calls == 1
+      raise Selenium::WebDriver::Error::StaleElementReferenceError, 'stale' if calls == 2
+
+      7
+    end.to eq(7)
+  end
+
+  it 're-raises the last lookup error when no value was ever read' do
+    expect { expect { raise Selenium::WebDriver::Error::NoSuchElementError, 'never' }.to eq(1) }
+      .to raise_error(Selenium::WebDriver::Error::NoSuchElementError, /never/)
+  end
+
+  it 'makes finds inside the block a single attempt' do
+    seen = nil
+    expect { seen = Raider::Wait.immediate? }.to be(true)
+    expect(seen).to be(true)
+  end
+
+  it 'evaluates raise_error once' do
+    calls = 0
+    expect { (calls += 1) && raise(ArgumentError) }.to raise_error(ArgumentError)
+    expect(calls).to eq(1)
+  end
+
+  it 'evaluates change once' do
+    list = []
+    calls = 0
+    expect { list << (calls += 1) }.to change { list.size }.by(1)
+    expect(calls).to eq(1)
+  end
+
+  it 'evaluates output once' do
+    calls = 0
+    expect { [calls += 1, print('a')] }.to output('a').to_stdout
+    expect(calls).to eq(1)
+  end
+
+  it 'evaluates throw_symbol once' do
+    calls = 0
+    expect { (calls += 1) && throw(:done) }.to throw_symbol(:done)
+    expect(calls).to eq(1)
+  end
+
+  it 'evaluates yield_control once' do
+    calls = 0
+    expect { |probe| (calls += 1) && probe.to_proc.call }.to yield_control
+    expect(calls).to eq(1)
+  end
+
+  it 'keeps a Raider matcher on a block with its own wait and message' do
+    Raider.timeout = 2
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    expect { expect { [1] }.to have_count(2, wait: 0.2) }
+      .to raise_error(RSpec::Expectations::ExpectationNotMetError, /expected the block to have count 2, last seen 1/)
+    expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 1
+  end
+
+  it 'treats a timeout inside the block as not ready and re-raises it after the deadline' do
+    expect { expect { Raider::Wait.until(timeout: 0.05) { false } }.to eq(1) }
+      .to raise_error(Raider::TimeoutError, /condition not met/)
+  end
+
+  it 'passes once a block that raised a Raider::TimeoutError twice returns the value' do
+    calls = 0
+    expect { (calls += 1) <= 2 ? raise(Raider::TimeoutError, 'slow') : 5 }.to eq(5)
+  end
+
+  it 'reports the last poll error rather than an older value' do
+    calls = 0
+    block = proc do
+      raise Selenium::WebDriver::Error::NoSuchElementError, 'later gone' if (calls += 1) > 1
+
+      'x'
+    end
+    expect { expect(&block).to eq('y') }
+      .to raise_error(Selenium::WebDriver::Error::NoSuchElementError, /later gone/)
+  end
+
+  it 'reports the last value when the last poll read one' do
+    calls = 0
+    block = proc do
+      raise Selenium::WebDriver::Error::NoSuchElementError, 'early' if (calls += 1) == 1
+
+      'x'
+    end
+    expect { expect(&block).to eq('y') }
+      .to raise_error(RSpec::Expectations::ExpectationNotMetError, /got: "x"/)
+  end
+
+  it 'does not chain the internal timeout as a cause' do
+    expect { expect { 1 }.to eq(2) }.to raise_error(RSpec::Expectations::ExpectationNotMetError) { |error|
+      expect(error.cause).to be_nil
+    }
+  end
+end

data/spec/runtime/observer_spec.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../lib/ruby_raider/runtime'
+require_relative 'support/fake_bridge'
+
+RSpec.describe 'Raider::Observer' do
+  let(:bridge) { Raider::Spec::FakeBridge.new }
+  let(:driver) { Raider::Spec.driver(bridge) }
+  let(:recorder_class) do
+    Class.new do
+      attr_reader :events
+
+      def initialize = @events = []
+
+      def action_started(**details)
+        @events << [:action_started, details]
+        :token
+      end
+
+      def action_ready(token, **details) = @events << [:action_ready, token, details]
+      def action_finished(token, **details) = @events << [:action_finished, token, details]
+    end
+  end
+  let(:recorder) { recorder_class.new }
+
+  before do
+    Raider.reset
+    Raider::Actionability.reset_notice
+    allow($stderr).to receive(:puts)
+    allow(Raider::Describe).to receive(:element) { |element| "<el #{element.ref.last}>" }
+    Raider.observer = recorder
+  end
+
+  after { Raider.reset }
+
+  def names = recorder.events.map(&:first)
+  def finished = recorder.events.last.last
+
+  it 'reports a role click with its retries' do
+    bridge.script_results.push([Selenium::WebDriver::Element.new(bridge, 'a')])
+    button = driver.find_element(Raider.by_role('button', name: 'Save'))
+    bridge.script_results.push({ 'check' => 'stable', 'first' => false }, { 'check' => 'stable', 'first' => false }, nil)
+    button.click
+    started, ready, done = recorder.events
+    expect(started).to eq([:action_started, { action: :click, locator: { strategy: 'role', selector: 'button, name: Save' }, within: [], args: nil }])
+    expect(ready).to eq([:action_ready, :token, { element: button }])
+    expect(done[1]).to eq(:token)
+    expect(done[2]).to include(status: :passed, retries: 2, error: nil, element: button)
+    expect(done[2][:waited_ms]).to be_a(Integer)
+  end
+
+  it 'hands the observer a frozen copy of the keys so it cannot change what is typed' do
+    keys = ['a']
+    seen = nil
+    recorder.define_singleton_method(:action_started) { |**details| (seen = details[:args]) << 'evil' }
+    bridge.enqueue(['f'])
+    driver.find_element(id: 'x').send_keys(*keys)
+    expect(seen).to be_frozen
+    expect(bridge.calls.select { |call| call.first == :send_keys_to_element }.map(&:last)).to eq([['a']])
+  end
+
+  it 'reports a nested send_keys with its within chain and keys' do
+    bridge.enqueue(['f'])
+    form = driver.find_element(css: 'form')
+    bridge.enqueue(['i'])
+    field = form.find_element(id: 'email')
+    bridge.script_results.push(nil)
+    field.send_keys('a')
+    expect(recorder.events.first.last).to eq(
+      action: :send_keys, locator: { strategy: 'id', selector: 'email' },
+      within: [{ strategy: 'css', selector: 'form' }], args: ['a']
+    )
+  end
+
+  it 'reports clear and submit with nil args' do
+    bridge.enqueue(['a'])
+    el = driver.find_element(name: 'q')
+    bridge.script_results.push(nil, nil)
+    el.clear
+    el.submit
+    expect(recorder.events.select { |e| e.first == :action_started }.map { |e| [e.last[:action], e.last[:args]] })
+      .to eq([[:clear, nil], [:submit, nil]])
+  end
+
+  it 'reports a failed timeout with the error and re-raises it' do
+    Raider.timeout = 0.3
+    bridge.enqueue(['a'])
+    el = driver.find_element(id: 'x')
+    bridge.script_results.concat([{ 'check' => 'visible' }] * 50)
+    expect { el.click }.to raise_error(Raider::NotActionable) { |error|
+      expect(finished).to include(status: :failed, error: error)
+      expect(finished[:retries]).to eq(error.retries)
+      expect(error.retries).to be >= 1
+    }
+    expect(names).to eq(%i[action_started action_finished])
+  end
+
+  it 're-raises a non-StandardError after reporting it' do
+    el = Selenium::WebDriver::Element.new(bridge, 'e1')
+    bridge.script_results.push(Interrupt.new('stop'))
+    expect { el.click }.to raise_error(Interrupt)
+    expect(finished).to include(status: :failed)
+    expect(finished[:error]).to be_a(Interrupt)
+  end
+
+  it 'still reports with force: true' do
+    bridge.answer(:element_tag_name, 'div')
+    Selenium::WebDriver::Element.new(bridge, 'e1').click(force: true)
+    expect(names).to eq(%i[action_started action_ready action_finished])
+    expect(finished).to include(status: :passed, retries: 0)
+  end
+
+  it 'still reports with actionability off' do
+    Raider.actionability = false
+    Selenium::WebDriver::Element.new(bridge, 'e1').click
+    expect(names).to eq(%i[action_started action_ready action_finished])
+  end
+
+  it 'still reports a native click' do
+    appium = Class.new(Raider::Spec::FakeBridge) { def current_context = 'NATIVE_APP' }.new
+    appium.answer(:element_displayed?, false, true).answer(:element_enabled?, true)
+    Selenium::WebDriver::Element.new(appium, 'e1').click
+    expect(names).to eq(%i[action_started action_ready action_finished])
+    expect(finished[:retries]).to eq(1)
+  end
+
+  it 'gives a nil locator to an unstamped element' do
+    bridge.answer(:element_tag_name, 'div')
+    Selenium::WebDriver::Element.new(bridge, 'e1').click(force: true)
+    expect(recorder.events.first.last).to include(locator: nil, within: [])
+  end
+
+  it 'lets the click happen when the observer raises, prints once and clears it' do
+    recorder.define_singleton_method(:action_started) { |**| raise ArgumentError, 'boom' }
+    bridge.answer(:element_tag_name, 'div')
+    Selenium::WebDriver::Element.new(bridge, 'e1').click(force: true)
+    expect(bridge.calls.last).to eq([:click_element, 'e1'])
+    expect($stderr).to have_received(:puts).with('[raider] observer stopped: ArgumentError: boom').once
+    expect(Raider.observer).to be_nil
+  end
+
+  it 'passes the token the observer returned back to later events' do
+    bridge.answer(:element_tag_name, 'div')
+    Selenium::WebDriver::Element.new(bridge, 'e1').click(force: true)
+    expect(recorder.events.map { |e| e[1] }.drop(1)).to eq(%i[token token])
+  end
+
+  describe 'a broken observer' do
+    let(:element) { Selenium::WebDriver::Element.new(bridge, 'e1') }
+
+    before { bridge.answer(:element_tag_name, 'div') }
+
+    [NotImplementedError, SystemStackError, ArgumentError].each do |klass|
+      %i[action_started action_ready action_finished].each do |hook|
+        it "survives #{klass} in #{hook}: the click happens, one line, observer cleared" do
+          recorder.define_singleton_method(hook) { |*, **| raise klass, 'boom' }
+          element.click(force: true)
+          expect(bridge.calls.last).to eq([:click_element, 'e1'])
+          expect($stderr).to have_received(:puts).with("[raider] observer stopped: #{klass}: boom").once
+          expect(Raider.observer).to be_nil
+        end
+      end
+    end
+
+    it 'lets an Interrupt from the observer propagate' do
+      recorder.define_singleton_method(:action_started) { |**| raise Interrupt }
+      expect { element.click(force: true) }.to raise_error(Interrupt)
+    end
+
+    it 'truncates the message to its first line and 200 characters' do
+      recorder.define_singleton_method(:action_started) { |**| raise ArgumentError, "#{'x' * 500}\nsecond" }
+      element.click(force: true)
+      expect($stderr).to have_received(:puts).with("[raider] observer stopped: ArgumentError: #{'x' * 200}")
+    end
+
+    it 'survives an exception whose message raises' do
+      error = Class.new(StandardError) { def message = raise('no') }
+      recorder.define_singleton_method(:action_started) { |**| raise error }
+      expect { element.click(force: true) }.not_to raise_error
+      expect(Raider.observer).to be_nil
+    end
+
+    it 'leaves a replacement observer installed' do
+      other = recorder_class.new
+      recorder.define_singleton_method(:action_started) do |**|
+        Raider.observer = other
+        raise 'swap'
+      end
+      element.click(force: true)
+      expect(Raider.observer).to equal(other)
+    end
+
+    it 'does not report again for an action taken inside a hook' do
+      inner = Selenium::WebDriver::Element.new(bridge, 'e2')
+      started = 0
+      recorder.define_singleton_method(:action_started) do |**|
+        started += 1
+        inner.click(force: true)
+        :token
+      end
+      element.click(force: true)
+      expect(bridge.calls.select { |c| c.first == :click_element }).to eq([[:click_element, 'e2'], [:click_element, 'e1']])
+      expect(started).to eq(1)
+    end
+
+    it 'sends no follow-up events when action_started returns nil' do
+      events = []
+      recorder.define_singleton_method(:action_started) { |**| nil }
+      recorder.define_singleton_method(:action_ready) { |*, **| events << :ready }
+      recorder.define_singleton_method(:action_finished) { |*, **| events << :finished }
+      element.click(force: true)
+      expect(events).to be_empty
+    end
+  end
+
+  describe 'stamping' do
+    it 'shares one frozen stamp across a find_elements result' do
+      bridge.enqueue(%w[a b c])
+      stamps = driver.find_elements(id: 'x').map { |e| e.instance_variable_get(:@raider_locator) }
+      expect(stamps.map(&:object_id).uniq.size).to eq(1)
+      expect([stamps.first.frozen?, stamps.first[:within].frozen?]).to eq([true, true])
+    end
+
+    it 'deep-freezes the stamp and keeps the caller string out of it' do
+      bridge.enqueue(['a'])
+      selector = +'#login'
+      stamp = driver.find_element(css: selector).instance_variable_get(:@raider_locator)
+      expect([stamp[:strategy].frozen?, stamp[:selector].frozen?]).to eq([true, true])
+      expect(stamp[:selector]).not_to equal(selector)
+      selector << '-changed'
+      expect(stamp[:selector]).to eq('#login')
+    end
+
+    it 'leaves a frozen element unstamped without raising' do
+      element = Selenium::WebDriver::Element.new(bridge, 'a').freeze
+      expect(Raider::Observer.stamp(element, [{ id: 'x' }], driver)).to equal(element)
+      expect(Raider::Observer.locator_of(element)).to be_nil
+    end
+
+    it 'chains three levels, outermost first' do
+      %w[m f i].each { |id| bridge.enqueue([id]) }
+      field = driver.find_element(css: 'main').find_element(css: 'form').find_element(id: 'email')
+      expect(Raider::Observer.locator_of(field)[:within]).to eq(
+        [{ strategy: 'css', selector: 'main' }, { strategy: 'css', selector: 'form' }]
+      )
+    end
+
+    it 'stamps through the first alias' do
+      bridge.enqueue(['a'])
+      expect(Raider::Observer.locator_of(driver.first(id: 'x'))).to include(strategy: 'id', selector: 'x')
+    end
+
+    it 'takes the first item of an Array-form selector through a real find' do
+      bridge.enqueue(['a'])
+      found = driver.find_element(text: ['Save', { exact: true }])
+      expect(Raider::Observer.locator_of(found)).to include(strategy: 'text', selector: 'Save')
+    end
+  end
+
+  describe 'Raider.report' do
+    it 'returns nil without an observer or when the hook is missing' do
+      Raider.observer = Object.new
+      expect(Raider.report(:nothing)).to be_nil
+      Raider.observer = nil
+      expect(Raider.report(:nothing) { raise 'not built' }).to be_nil
+    end
+
+    it 'builds the details from the block only for an observer that responds' do
+      seen = nil
+      Raider.observer = Object.new.tap { |o| o.define_singleton_method(:hook) { |first, **d| seen = [first, d] } }
+      Raider.report(:hook, 1) { { a: 2 } }
+      expect(seen).to eq([1, { a: 2 }])
+    end
+
+    it 'catches a failing block under the same rescue' do
+      Raider.observer = recorder
+      Raider.report(:action_started) { raise 'bad' }
+      expect($stderr).to have_received(:puts).with('[raider] observer stopped: RuntimeError: bad')
+      expect(Raider.observer).to be_nil
+    end
+  end
+
+  describe 'with no observer' do
+    before { Raider.observer = nil }
+
+    it 'sends the same bridge commands as a bare click' do
+      bridge.script_results.push({ 'check' => 'visible' }, nil)
+      Selenium::WebDriver::Element.new(bridge, 'e1').click
+      expect(bridge.calls).to eq([[:click_element, 'e1']])
+      expect(bridge.script_calls.size).to eq(2)
+    end
+
+    it 'yields without a run' do
+      expect { |block| Raider::Observer.emit_action(nil, :click, &block) }.to yield_with_args(nil)
+    end
+  end
+
+  describe '.locator_of' do
+    # Straight through the stamp: Selenium rejects some of these spellings before any find succeeds.
+    def locate(*args)
+      element = Selenium::WebDriver::Element.new(bridge, 'a')
+      Raider::Observer.locator_of(Raider::Observer.stamp(element, args, driver))
+    end
+
+    {
+      [:css_selector, 'a'] => %w[css a], [{ class: 'k' }] => %w[class_name k], [{ link: 'l' }] => %w[link_text l],
+      [:partial_link, 'p'] => %w[partial_link_text p], ['class name', 'k'] => %w[class_name k],
+      ['css selector', 'a'] => %w[css a], ['link text', 'l'] => %w[link_text l],
+      ['partial link text', 'p'] => %w[partial_link_text p], ['tag name', 'div'] => %w[tag_name div],
+      [:id, 'x'] => %w[id x], [{ xpath: '//a' }] => ['xpath', '//a'], [{ label: 'Email' }] => %w[label Email],
+      [{ test_id: 't' }] => %w[test_id t], [{ text: ['Hi', { exact: true }] }] => %w[text Hi]
+    }.each do |args, (strategy, selector)|
+      it "normalises #{args.inspect}" do
+        expect(locate(*args)).to eq(strategy: strategy, selector: selector, within: [])
+      end
+    end
+
+    it 'renders a role with its options' do
+      expect(locate(role: ['button', { name: 'Save', exact: true }])[:selector]).to eq('button, name: Save, exact: true')
+    end
+
+    it 'renders a bare role' do
+      expect(locate(role: 'button')).to include(strategy: 'role', selector: 'button')
+    end
+
+    it 'stamps find_elements results too' do
+      bridge.enqueue(%w[a b])
+      found = driver.find_elements(id: 'x')
+      expect(found.map { |e| Raider::Observer.locator_of(e) }).to all(include(strategy: 'id', selector: 'x'))
+    end
+
+    it 'returns nil for an unstamped element' do
+      expect(Raider::Observer.locator_of(Selenium::WebDriver::Element.new(bridge, 'e1'))).to be_nil
+    end
+  end
+
+  it 'names the runtime directory as LIB_DIR' do
+    expect(Raider::Observer::LIB_DIR).to eq(File.expand_path('../../lib/ruby_raider/runtime', __dir__))
+  end
+end

data/spec/runtime/role_finder_spec.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../lib/ruby_raider/runtime'
+require_relative 'support/fake_bridge'
+
+RSpec.describe 'Raider role finder' do
+  let(:bridge) { Raider::Spec::FakeBridge.new }
+  let(:driver) { Raider::Spec.driver(bridge) }
+  let(:locator) { Raider.by_role('button', name: 'Save') }
+  let(:options) { { 'name' => 'Save', 'exact' => false, 'includeHidden' => false, 'level' => nil } }
+
+  before { allow(Raider::Describe).to receive(:element) { |element| "<el #{element.ref.last}>" } }
+
+  after { Raider.reset }
+
+  # These examples are about the role engine, so each find makes one attempt.
+  around { |example| Raider::Wait.immediately { example.run } }
+
+  def element(id)
+    Selenium::WebDriver::Element.new(bridge, id)
+  end
+
+  it 'queries the engine with a nil scope from the driver' do
+    bridge.script_results << [element('a')]
+    driver.find_elements(locator)
+    expect(bridge.script_calls.first.drop(1)).to eq([nil, 'button', options])
+  end
+
+  it 'scopes the query to the element' do
+    scope = element('s')
+    bridge.script_results << []
+    scope.find_elements(Raider.by_role('listitem'))
+    expect(bridge.script_calls.first.drop(1)).to eq([scope, 'listitem', { 'name' => nil, 'exact' => false,
+                                                                          'includeHidden' => false, 'level' => nil }])
+  end
+
+  it 'scopes the query to a shadow root instead of the document' do
+    shadow = Selenium::WebDriver::ShadowRoot.new(bridge, 'sr')
+    bridge.script_results << []
+    shadow.find_elements(Raider.by_role('button'))
+    expect(bridge.script_calls.first[1]).to equal(shadow)
+  end
+
+  it 'carries a heading level and rejects bad ones before any script runs' do
+    bridge.script_results << []
+    driver.find_elements(Raider.by_role('heading', level: 2))
+    expect(bridge.script_calls.first.last).to include('level' => 2)
+    [{ role: ['button', { level: 2 }] }, { role: ['heading', { level: 7 }] }, { role: ['heading', { level: '2' }] }].each do |bad|
+      expect { driver.find_elements(bad) }.to raise_error(ArgumentError, /level/)
+    end
+    expect(bridge.script_calls.size).to eq(1)
+  end
+
+  it 'accepts the two-argument form and string option keys' do
+    bridge.script_results << []
+    driver.find_elements(:role, ['button', { 'name' => 'Save' }])
+    expect(bridge.script_calls.first.drop(1)).to eq([nil, 'button', options])
+  end
+
+  it 'accepts a bare role string' do
+    bridge.script_results << []
+    driver.find_elements(role: 'button')
+    expect(bridge.script_calls.first[2]).to eq('button')
+  end
+
+  it 'accepts a string role key in both forms' do
+    bridge.script_results.push([], [])
+    driver.find_elements('role' => ['button', { name: 'Save' }])
+    driver.find_elements('role', ['button', { name: 'Save' }])
+    expect(bridge.script_calls.map { |call| call.drop(1) }).to eq([[nil, 'button', options]] * 2)
+  end
+
+  it 'finds a single element through a string role key' do
+    bridge.script_results << [element('a')]
+    expect(driver.find_element('role' => 'button').ref.last).to eq('a')
+  end
+
+  {
+    'a nil value' => { role: nil },
+    'an unknown role' => { role: 'buton' },
+    'a Hash value' => { role: { a: 1 } },
+    'a blank role' => { role: ['', { name: 'x' }] },
+    'non-Hash options' => { role: %w[button Save] },
+    'a Regexp name' => { role: ['button', { name: /Save/ }] }
+  }.each do |label, locator|
+    it "raises ArgumentError for #{label} before any script runs" do
+      expect { driver.find_elements(locator) }.to raise_error(ArgumentError, /role|unknown role/)
+      expect { driver.find_element(locator) }.to raise_error(ArgumentError)
+      expect(bridge.script_calls).to be_empty
+    end
+  end
+
+  it 'raises AmbiguousMatch from find_element on two matches' do
+    bridge.script_results << [element('a'), element('b')]
+    expect { driver.find_element(locator) }.to raise_error(Raider::AmbiguousMatch) { |error|
+      expect(error.message).to start_with('`by_role(\'button\', name: "Save")` matched 2 elements')
+    }
+  end
+
+  it 'returns the single match' do
+    bridge.script_results << [element('a')]
+    expect(driver.find_element(locator).ref.last).to eq('a')
+  end
+
+  it 'returns the first match when strict is off' do
+    Raider.strict = false
+    bridge.script_results << [element('a'), element('b')]
+    expect(driver.find_element(locator).ref.last).to eq('a')
+  end
+
+  it 'raises NoSuchElementError with no matches' do
+    bridge.script_results << []
+    expect { driver.find_element(locator) }
+      .to raise_error(Selenium::WebDriver::Error::NoSuchElementError, /no such element: by_role\('button', name: "Save"\)/)
+  end
+
+  it 'raises NoSuchElementError with no matches when strict is off' do
+    Raider.strict = false
+    bridge.script_results << []
+    expect { driver.find_element(locator) }
+      .to raise_error(Selenium::WebDriver::Error::NoSuchElementError, /no such element: by_role/)
+  end
+
+  it 'propagates a JavascriptError that is not about the engine' do
+    bridge.script_results << Selenium::WebDriver::Error::JavascriptError.new('boom')
+    expect { driver.find_elements(locator) }.to raise_error(Selenium::WebDriver::Error::JavascriptError, 'boom')
+  end
+
+  it 'leaves other locators for Selenium' do
+    bridge.enqueue(%w[a b])
+    expect(driver.find_elements(css: 'x').size).to eq(2)
+    expect(bridge.calls.first.first).to eq(:find_elements_by)
+    expect(bridge.script_calls).to be_empty
+  end
+
+  context 'with an Appium NATIVE_APP bridge' do
+    let(:bridge) do
+      klass = stub_const('Appium::Core::Base::Bridge', Class.new(Raider::Spec::FakeBridge) do
+        class << self; attr_accessor :locator_converter; end
+        define_method(:current_context) { 'NATIVE_APP' }
+      end)
+      klass.locator_converter = Selenium::WebDriver::Remote::Bridge::LocatorConverter.new
+      klass.new
+    end
+
+    it 'raises NotSupported' do
+      expect { driver.find_elements(locator) }
+        .to raise_error(Raider::NotSupported, 'by_role needs a web context; use accessibility_id on native screens')
+    end
+
+    it 'raises NotSupported from find_element too' do
+      expect { driver.find_element(locator) }.to raise_error(Raider::NotSupported)
+    end
+  end
+end