ruby_raider 3.13.0 → 4.0.0

data/spec/runtime/matchers/base_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+
+RSpec.describe 'Raider::Matchers::Base' do
+  after { Raider.reset }
+
+  let(:matcher_class) do
+    Class.new(Raider::Matchers::Base) do
+      def verb = 'have value'
+      def read(subject) = subject.value
+      def pass?(value) = value == expected
+    end
+  end
+
+  let(:subject_class) do
+    Class.new do
+      attr_reader :reads
+
+      def initialize(*values, error: nil)
+        @values = values
+        @error = error
+        @reads = 0
+      end
+
+      def value
+        @reads += 1
+        raise @error, 'gone' if @error
+
+        @values[[@reads, @values.size].min - 1]
+      end
+
+      def tag_name = raise(Selenium::WebDriver::Error::WebDriverError, 'no tag')
+    end
+  end
+
+  it 'passes once the value changes to the expected one' do
+    element = subject_class.new('a', 'a', 'b')
+    expect(matcher_class.new('b', wait: 1).matches?(element)).to be(true)
+    expect(element.reads).to be >= 3
+  end
+
+  it 'retries the negated form until the value changes away' do
+    element = subject_class.new('b', 'b', 'a')
+    expect(matcher_class.new('b', wait: 1).does_not_match?(element)).to be(true)
+    expect(element.reads).to be >= 3
+  end
+
+  it 'reports the last value seen after the wait' do
+    matcher = matcher_class.new('b', wait: 0.2)
+    expect(matcher.matches?(subject_class.new('a'))).to be(false)
+    expect(matcher.failure_message).to match(/\A#{Regexp.escape('expected <element> to have value "b", last seen "a" after ')}0\.\d+s\z/)
+  end
+
+  it 'words the negated failure' do
+    matcher = matcher_class.new('a', wait: 0.2)
+    expect(matcher.does_not_match?(subject_class.new('a'))).to be(false)
+    expect(matcher.failure_message_when_negated)
+      .to match(/\A#{Regexp.escape('expected <element> not to have value "a", last seen "a" after ')}0\.\d+s\z/)
+  end
+
+  it 'uses the configured timeout when wait is nil' do
+    Raider.timeout = 0.2
+    matcher = matcher_class.new('b')
+    matcher.matches?(subject_class.new('a'))
+    expect(matcher.failure_message).to match(/after 0\.[23]\d*s\z/)
+  end
+
+  it 'calls a Proc actual on every poll and describes it as the block' do
+    calls = 0
+    matcher = matcher_class.new('b', wait: 0.3)
+    result = matcher.matches?(proc { subject_class.new("v#{calls += 1}") })
+    expect(result).to be(false)
+    expect(calls).to be >= 2
+    expect(matcher.failure_message).to start_with('expected the block to have value "b", last seen "v')
+  end
+
+  it 'propagates an error raised by a Proc actual' do
+    expect { matcher_class.new('b', wait: 1).matches?(proc { raise 'boom' }) }.to raise_error(RuntimeError, 'boom')
+  end
+
+  it 'reports not found when the element never appears' do
+    element = subject_class.new(error: Selenium::WebDriver::Error::NoSuchElementError)
+    matcher = matcher_class.new('b', wait: 0.2)
+    expect(matcher.matches?(element)).to be(false)
+    expect(matcher.failure_message).to include('last seen: not found')
+  end
+
+  it 'counts absence as a pass when the matcher allows it' do
+    absent = Class.new(matcher_class) { def absent_passes? = true }
+    element = subject_class.new(error: Selenium::WebDriver::Error::StaleElementReferenceError)
+    expect(absent.new('x', wait: 0.2).matches?(element)).to be(true)
+    expect(absent.new('x', wait: 0.2).does_not_match?(element)).to be(false)
+  end
+
+  context 'when the read raises a selenium TimeoutError' do
+    before { stub_const('SlowRead', Class.new(Selenium::WebDriver::Error::TimeoutError)) }
+
+    let(:timeout_error) { SlowRead }
+    let(:reader_class) do
+      Class.new do
+        def initialize(error, fails)
+          @error = error
+          @fails = fails
+        end
+
+        def value
+          raise @error, 'slow' if (@fails -= 1) >= 0
+
+          'ok'
+        end
+      end
+    end
+
+    it 'retries it as not yet' do
+      reader = reader_class.new(timeout_error, 2)
+      expect(matcher_class.new('ok', wait: 1).matches?(reader)).to be(true)
+    end
+
+    it 'counts it as absence when the matcher allows' do
+      absent = Class.new(matcher_class) { def absent_passes? = true }
+      expect(absent.new('x', wait: 1).matches?(reader_class.new(timeout_error, Float::INFINITY))).to be(true)
+    end
+
+    it 'still ends at the matcher deadline' do
+      expect(matcher_class.new('ok', wait: 0.2).matches?(reader_class.new(timeout_error, Float::INFINITY))).to be(false)
+    end
+  end
+
+  it 'reports the elapsed time rather than the configured wait' do
+    Raider.timeout = 30
+    matcher = matcher_class.new('b', wait: 0.3)
+    matcher.matches?(subject_class.new('a'))
+    seconds = matcher.failure_message[/after ([\d.]+)s/, 1].to_f
+    expect(seconds).to be_between(0.3, 0.5)
+  end
+
+  it 'fails with a message for an actual without tag_name' do
+    actual = Struct.new(:value).new('a')
+    matcher = matcher_class.new('b', wait: 0.1)
+    expect(matcher.matches?(actual)).to be(false)
+    expect(matcher.failure_message).to start_with('expected #<struct')
+  end
+
+  it 'supports block expectations and describes itself' do
+    matcher = matcher_class.new('b')
+    expect(matcher.supports_block_expectations?).to be(true)
+    expect(matcher.description).to eq('have value "b"')
+  end
+
+  describe '#read_with_zero_wait' do
+    let(:reader) { matcher_class.new('x') }
+
+    it 'passes timeout: 0 when the method accepts it' do
+      target = Class.new { def text(timeout: 5) = timeout }.new
+      expect(reader.read_with_zero_wait(target, :text)).to eq(0)
+    end
+
+    it 'omits it otherwise' do
+      target = Class.new { def text = 'plain' }.new
+      expect(reader.read_with_zero_wait(target, :text)).to eq('plain')
+    end
+  end
+end

data/spec/runtime/matchers/element_spec.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../support/fake_bridge'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+
+RSpec.describe 'Raider element matchers' do
+  include Raider::Matchers
+
+  let(:bridge) { Raider::Spec::FakeBridge.new }
+  let(:element) { Selenium::WebDriver::Element.new(bridge, 'e1') }
+  let(:gone) { Selenium::WebDriver::Error::NoSuchElementError }
+
+  after { Raider.reset }
+
+  describe 'have_text' do
+    it 'passes once the text arrives' do
+      bridge.answer(:element_text, 'Welcome', 'Welcome back Ann')
+      expect(have_text('Welcome back Ann', wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'matches a whitespace-normalised substring' do
+      bridge.answer(:element_text, "Hi\n  Welcome   back Ann  ")
+      expect(have_text('Welcome back', wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'fails exact on extra text with the last seen value' do
+      bridge.answer(:element_text, 'Welcome back Ann!')
+      matcher = have_text('Welcome back Ann', exact: true, wait: 0.2)
+      expect(matcher.matches?(element)).to be(false)
+      expect(matcher.failure_message)
+        .to match(/\A#{Regexp.escape('expected <element> to have exact text "Welcome back Ann", last seen "Welcome back Ann!" after ')}0\.\d+s\z/)
+    end
+
+    it 'matches a regexp against the normalised text' do
+      bridge.answer(:element_text, "Hi  Ann\n Lee")
+      expect(have_text(/Ann Lee/, wait: 1).matches?(element)).to be(true)
+      expect(have_text(/Bob/, wait: 0.2).matches?(element)).to be(false)
+    end
+
+    it 'words an exact regexp failure' do
+      bridge.answer(:element_text, 'Bob')
+      matcher = have_text(/Ann/, exact: true, wait: 0.2)
+      expect(matcher.matches?(element)).to be(false)
+      expect(matcher.failure_message).to start_with('expected <element> to have exact text /Ann/, last seen "Bob"')
+    end
+
+    it 'waits for the text to change when negated' do
+      bridge.answer(:element_text, 'Loading', 'Loading', 'Done')
+      expect(have_text('Loading', wait: 1).does_not_match?(element)).to be(true)
+    end
+
+    it 'words the negated failure' do
+      bridge.answer(:element_text, 'Loading')
+      matcher = have_text('Loading', wait: 0.2)
+      expect(matcher.does_not_match?(element)).to be(false)
+      expect(matcher.failure_message_when_negated)
+        .to match(/\A#{Regexp.escape('expected <element> not to have text "Loading", last seen "Loading" after ')}0\.\d+s\z/)
+    end
+
+    it 'reads a template element with timeout: 0 so the wait is not doubled' do
+      seen = []
+      reader = Object.new
+      reader.define_singleton_method(:text) { |timeout: 5| seen << timeout && 'hello' }
+      expect(have_text('hello', wait: 1).matches?(reader)).to be(true)
+      expect(seen).to eq([0])
+    end
+
+    it 'does not pass a timeout to a reader that does not take one' do
+      expect(have_text('hello', wait: 1).matches?(Struct.new(:text).new('hello'))).to be(true)
+    end
+  end
+
+  describe 'have_value' do
+    it 'reads the value attribute' do
+      bridge.answer(:element_attribute, nil, 'admin')
+      expect(have_value('admin', wait: 1).matches?(element)).to be(true)
+    end
+  end
+
+  describe 'have_value with a regexp' do
+    it 'matches the value' do
+      bridge.answer(:element_attribute, 'xyz')
+      expect(have_value(/y/, wait: 1).matches?(element)).to be(true)
+    end
+  end
+
+  describe 'have_attribute' do
+    it 'passes when the attribute is present' do
+      bridge.answer(:element_attribute, nil, '/home')
+      expect(have_attribute('href', wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'fails when the attribute stays absent' do
+      bridge.answer(:element_attribute, nil)
+      expect(have_attribute('href', wait: 0.2).matches?(element)).to be(false)
+    end
+
+    it 'matches a regexp' do
+      bridge.answer(:element_attribute, 'btn', 'btn active')
+      expect(have_attribute('class', /active/, wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'compares a string by equality' do
+      bridge.answer(:element_attribute, 'btn active')
+      expect(have_attribute('class', 'btn', wait: 0.2).matches?(element)).to be(false)
+    end
+  end
+
+  describe 'state matchers' do
+    it 'be_visible passes once displayed turns true' do
+      bridge.answer(:element_displayed?, false, true)
+      expect(be_visible(wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'be_hidden passes in one poll on a block whose find is always empty' do
+      driver = Raider::Spec.driver(bridge)
+      calls = 0
+      Raider.timeout = 5
+      expect { (calls += 1) && driver.find_element(id: 'gone') }.to be_hidden
+      expect(calls).to eq(1)
+    end
+
+    it 'have_text fails on a block whose find is always empty after about three polls' do
+      driver = Raider::Spec.driver(bridge)
+      calls = 0
+      matcher = have_text('x', wait: 0.3)
+      expect(matcher.matches?(-> { (calls += 1) && driver.find_element(id: 'gone') })).to be(false)
+      expect(calls).to be_between(3, 4)
+    end
+
+    it 'be_hidden passes when the element is absent' do
+      bridge.answer(:element_displayed?, gone)
+      expect(be_hidden(wait: 0.2).matches?(element)).to be(true)
+    end
+
+    it 'be_hidden passes when not displayed' do
+      bridge.answer(:element_displayed?, false)
+      expect(be_hidden(wait: 0.2).matches?(element)).to be(true)
+    end
+
+    it 'be_hidden fails on a visible element with the last seen state' do
+      bridge.answer(:element_displayed?, true)
+      matcher = be_hidden(wait: 0.2)
+      expect(matcher.matches?(element)).to be(false)
+      expect(matcher.failure_message).to match(/\A#{Regexp.escape('expected <element> to be hidden, last seen visible after ')}0\.\d+s\z/)
+    end
+
+    it 'be_visible failure reads last seen hidden' do
+      bridge.answer(:element_displayed?, false)
+      matcher = be_visible(wait: 0.2)
+      expect(matcher.matches?(element)).to be(false)
+      expect(matcher.failure_message).to match(/\A#{Regexp.escape('expected <element> to be visible, last seen hidden after ')}0\.\d+s\z/)
+    end
+
+    it 'be_enabled and be_disabled read enabled?' do
+      bridge.answer(:element_enabled?, false, true)
+      expect(be_enabled(wait: 1).matches?(element)).to be(true)
+      bridge.answer(:element_enabled?, false)
+      expect(be_disabled(wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'be_checked reads selected?' do
+      bridge.answer(:element_selected?, false, true)
+      expect(be_checked(wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'be_checked failure reads last seen unchecked' do
+      bridge.answer(:element_selected?, false)
+      matcher = be_checked(wait: 0.2)
+      expect(matcher.matches?(element)).to be(false)
+      expect(matcher.failure_message).to match(/\A#{Regexp.escape('expected <element> to be checked, last seen unchecked after ')}0\.\d+s\z/)
+    end
+  end
+
+  describe 'absence and staleness' do
+    it 'not_to be_visible passes on an absent element' do
+      bridge.answer(:element_displayed?, gone)
+      expect(be_visible(wait: 1).does_not_match?(element)).to be(true)
+    end
+
+    it 'not_to be_visible passes on a stale raw element' do
+      bridge.answer(:element_displayed?, Selenium::WebDriver::Error::StaleElementReferenceError)
+      expect(be_visible(wait: 1).does_not_match?(element)).to be(true)
+    end
+
+    it 'be_visible keeps retrying an absent element and fails' do
+      bridge.answer(:element_displayed?, gone)
+      matcher = be_visible(wait: 0.2)
+      expect(matcher.matches?(element)).to be(false)
+      expect(matcher.failure_message).to include('last seen: not found')
+    end
+
+    it 'fails at once with the hint for a stale raw element' do
+      bridge.answer(:element_text, Selenium::WebDriver::Error::StaleElementReferenceError)
+      matcher = have_text('x', wait: 5)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      expect(matcher.matches?(element)).to be(false)
+      expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 1
+      expect(matcher.failure_message).to eq(
+        'expected <element> to have text "x", but the element is stale; ' \
+        'use the block form (expect { page.element }) so it is found again'
+      )
+    end
+
+    it 'be_hidden passes on a stale raw element' do
+      bridge.answer(:element_displayed?, Selenium::WebDriver::Error::StaleElementReferenceError)
+      expect(be_hidden(wait: 1).matches?(element)).to be(true)
+    end
+
+    it 'retries a stale element read through a block' do
+      bridge.answer(:element_text, Selenium::WebDriver::Error::StaleElementReferenceError, 'x')
+      expect(have_text('x', wait: 1).matches?(proc { element })).to be(true)
+    end
+
+    it 'composes with and' do
+      bridge.answer(:element_text, 'abc')
+      bridge.answer(:element_displayed?, true)
+      expect(element).to have_text('a', wait: 1).and be_visible(wait: 1)
+    end
+  end
+
+  describe 'compound matchers' do
+    before do
+      bridge.answer(:element_text, 'abc')
+      bridge.answer(:element_displayed?, true)
+    end
+
+    it 'passes the block form of and when both hold' do
+      expect { element }.to have_text('a', wait: 1).and be_visible(wait: 1)
+    end
+
+    it 'fails the block form of and with a combined message' do
+      matcher = have_text('a', wait: 0.1).and be_hidden(wait: 0.1)
+      expect(matcher.matches?(proc { element })).to be(false)
+      expect(matcher.failure_message).to include('to be hidden')
+    end
+
+    it 'passes the block form of or when one side holds' do
+      expect { element }.to have_text('zzz', wait: 0.1).or be_visible(wait: 0.1)
+    end
+
+    it 'fails the block form of or when neither holds' do
+      matcher = have_text('zzz', wait: 0.1).or be_hidden(wait: 0.1)
+      expect(matcher.matches?(proc { element })).to be(false)
+    end
+
+    it 'passes a three-way block chain when all hold' do
+      bridge.answer(:element_enabled?, true)
+      expect { element }.to have_text('a', wait: 1).and(be_visible(wait: 1)).and be_enabled(wait: 1)
+    end
+
+    it 'fails a three-way block chain when the last does not hold' do
+      bridge.answer(:element_enabled?, false)
+      matcher = have_text('a', wait: 0.1).and(be_visible(wait: 0.1)).and be_enabled(wait: 0.1)
+      expect(matcher.matches?(proc { element })).to be(false)
+      expect(matcher.failure_message).to include('to be enabled')
+    end
+
+    it 'mixes or into a block chain' do
+      expect { element }.to have_text('zzz', wait: 0.1).or(be_hidden(wait: 0.1)).or be_visible(wait: 0.1)
+    end
+
+    it 'keeps the value form working' do
+      expect(element).to have_text('a', wait: 1) & be_visible(wait: 1)
+    end
+
+    it 'keeps the value form of or working' do
+      expect(element).to have_text('zzz', wait: 0.1) | be_visible(wait: 0.1)
+    end
+  end
+
+  it 'works through expect syntax with a block' do
+    bridge.answer(:element_text, 'x')
+    expect { element }.to have_text('x', wait: 1)
+  end
+end

data/spec/runtime/matchers/page_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+
+RSpec.describe 'Raider page matchers' do
+  include Raider::Matchers
+
+  # A driver whose title and url change from poll to poll; the last answer repeats.
+  let(:driver_class) do
+    Class.new do
+      def initialize(titles, urls)
+        @titles = titles
+        @urls = urls
+      end
+
+      def title
+        @titles.size > 1 ? @titles.shift : @titles.first
+      end
+
+      def current_url
+        @urls.size > 1 ? @urls.shift : @urls.first
+      end
+    end
+  end
+
+  after { Raider.reset }
+
+  describe 'have_count' do
+    it 'passes at once on an Array of the right size' do
+      expect(have_count(2).matches?([1, 2])).to be(true)
+    end
+
+    it 'fails an Array without waiting' do
+      matcher = have_count(2, wait: 10)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      expect(matcher.matches?([1])).to be(false)
+      expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 0.05
+      expect(matcher.failure_message).to eq('expected the array to have count 2, last seen 1 after 0s')
+    end
+
+    it 'passes on the first poll for a block whose find_elements is always empty' do
+      driver = Raider::Spec.driver(Raider::Spec::FakeBridge.new)
+      calls = 0
+      Raider.timeout = 5
+      expect { (calls += 1) && driver.find_elements(css: '.row') }.to have_count(0)
+      expect(calls).to eq(1)
+    end
+
+    it 'keeps calling a block until the count arrives' do
+      calls = 0
+      expect { (calls += 1) > 2 ? [1, 2, 3] : [] }.to have_count(3)
+    end
+
+    it 'words a block failure with the last count' do
+      matcher = have_count(3, wait: 0.2)
+      expect(matcher.matches?(-> { [1, 2] })).to be(false)
+      expect(matcher.failure_message).to match(/\A#{Regexp.escape('expected the block to have count 3, last seen 2 after ')}0\.\d+s\z/)
+    end
+
+    it 'waits for the count to leave when negated' do
+      sizes = [[1, 2, 3], [1, 2, 3], [1]]
+      expect(have_count(3, wait: 1).does_not_match?(-> { sizes.size > 1 ? sizes.shift : sizes.first })).to be(true)
+    end
+  end
+
+  describe 'have_title' do
+    it 'passes once the title changes' do
+      driver = driver_class.new(%w[Loading Account], [''])
+      expect(have_title('Account', wait: 1).matches?(driver)).to be(true)
+    end
+
+    it 'accepts a Regexp' do
+      expect(driver_class.new(['My Account'], [''])).to have_title(/Account\z/)
+    end
+
+    it 'fails with the last title' do
+      matcher = have_title('Account', wait: 0.2)
+      expect(matcher.matches?(driver_class.new(['Home'], ['']))).to be(false)
+      expect(matcher.failure_message).to match(/\A#{Regexp.escape('expected the page to have title "Account", last seen "Home" after ')}0\.\d+s\z/)
+    end
+  end
+
+  describe 'have_url' do
+    let(:driver) { driver_class.new([''], ['https://x/account']) }
+
+    it 'matches a Regexp' do
+      expect(driver).to have_url(%r{/account$})
+    end
+
+    it 'matches a whole String' do
+      expect(driver).to have_url('https://x/account')
+    end
+
+    it 'does not match a fragment of the url' do
+      matcher = have_url('account', wait: 0.2)
+      expect(matcher.matches?(driver)).to be(false)
+      expect(matcher.failure_message)
+        .to match(/\A#{Regexp.escape('expected the page to have url "account", last seen "https://x/account" after ')}0\.\d+s\z/)
+    end
+  end
+end

data/spec/runtime/matchers/presence_spec.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+require_relative '../support/fake_bridge'
+
+RSpec.describe 'Raider presence matchers' do
+  include Raider::Matchers
+
+  let(:bridge) { Raider::Spec::FakeBridge.new }
+  let(:driver) { Raider::Spec.driver(bridge) }
+
+  before { Raider.timeout = 0.3 }
+
+  after { Raider.reset }
+
+  it 'passes on the second poll once the element appears' do
+    bridge.enqueue([])
+    bridge.enqueue(['e'])
+    expect(driver).to have_element(id: 'x')
+    expect(bridge.calls.count { |call| call.first == :find_elements_by }).to eq(2)
+  end
+
+  it 'passes a negated expectation on the first poll when nothing matches' do
+    expect(driver).not_to have_element(id: 'x')
+    expect(bridge.calls.count { |call| call.first == :find_elements_by }).to eq(1)
+  end
+
+  it 'names the locator and the last count on failure' do
+    matcher = have_element({ id: 'x' }, wait: 0.1)
+    expect(matcher.matches?(driver)).to be(false)
+    expect(matcher.failure_message).to match(/to have element .*id: "x".*last seen 0/)
+  end
+
+  it 'builds a css locator from have_css' do
+    expect(have_css('.row').expected).to eq({ css: '.row' })
+  end
+
+  it 'builds an xpath locator from have_xpath' do
+    expect(have_xpath('//p', wait: 1).expected).to eq({ xpath: '//p' })
+  end
+
+  it 'refuses a hash together with keywords' do
+    expect { have_element({ id: 'x' }, css: '.y') }.to raise_error(ArgumentError)
+  end
+
+  it 'refuses no locator at all' do
+    expect { have_element }.to raise_error(ArgumentError)
+  end
+
+  it 'says the block when the subject is a block' do
+    Raider.timeout = 0.1
+    bridge.enqueue(['e'])
+    bridge.enqueue(['e'])
+    expect { expect { driver }.not_to have_element(id: 'x') }
+      .to raise_error(RSpec::Expectations::ExpectationNotMetError, /expected the block not to have element/)
+  end
+end