ruby_raider 3.13.0 → 4.0.0

data/spec/runtime/browser/finders_browser_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime'
+require_relative '../support/browser'
+
+RSpec.describe 'Raider finders in a real browser', :browser do
+  include Raider::Helpers
+
+  let(:driver) { Raider::Spec::Browser.driver }
+
+  before(:all) { Raider::Spec::Browser.open('locators.html') } # rubocop:disable RSpec/BeforeAfterAll
+
+  after(:all) { Raider::Spec::Browser.quit } # rubocop:disable RSpec/BeforeAfterAll
+
+  def id_of(element)
+    element.attribute('id')
+  end
+
+  describe 'label:' do
+    it 'finds a field through label for' do
+      expect(id_of(driver.find_element(label: 'Password'))).to eq('password')
+    end
+
+    it 'finds a field inside a wrapping label' do
+      expect(id_of(driver.find_element(label: 'Username'))).to eq('username')
+    end
+
+    it 'finds a field by aria-label' do
+      expect(id_of(driver.find_element(label: 'Search site'))).to eq('search')
+    end
+
+    it 'finds a field by aria-labelledby' do
+      expect(id_of(driver.find_element(label: 'Phone number'))).to eq('phone')
+    end
+
+    it 'matches a substring and skips the longer label under exact: true' do
+      expect(id_of(driver.find_element(label: 'Email address'))).to eq('email-address')
+      expect(id_of(driver.find_element(label: ['Email address', { exact: true }]))).to eq('email-address')
+    end
+
+    it 'skips the longer label when the exact label is scoped' do
+      scope = driver.find_element(id: 'scope')
+      expect(id_of(scope.find_element(label: ['Email', { exact: true }]))).to eq('scoped-email')
+    end
+
+    it 'treats a substring as ambiguous and exact as unique' do
+      expect { driver.find_element(label: 'Email') }.to raise_error(Raider::AmbiguousMatch)
+      expect(driver.find_elements(label: 'Email').size).to eq(3)
+      expect(driver.find_elements(label: ['Email', { exact: true }]).size).to eq(2)
+    end
+
+    it 'scopes to the section' do
+      scope = driver.find_element(id: 'scope')
+      expect(id_of(scope.find_element(label: 'Email'))).to eq('scoped-email')
+    end
+
+    it 'raises NoSuchElementError when nothing matches' do
+      expect { driver.find_element(label: 'Nope') }.to raise_error(Selenium::WebDriver::Error::NoSuchElementError)
+    end
+  end
+
+  describe 'placeholder:' do
+    it 'matches a substring' do
+      expect(driver.find_elements(placeholder: 'Enter').size).to eq(2)
+    end
+
+    it 'matches exactly' do
+      expect(id_of(driver.find_element(placeholder: ['Enter code', { exact: true }]))).to eq('code')
+    end
+  end
+
+  it 'finds an image by alt' do
+    expect(id_of(driver.find_element(alt: 'Company logo'))).to eq('logo')
+  end
+
+  it 'finds a link by title' do
+    expect(id_of(driver.find_element(title: 'Read the docs'))).to eq('docs-link')
+  end
+
+  describe 'text:' do
+    it 'returns the innermost element, not its ancestor' do
+      expect(id_of(driver.find_element(text: 'Sign in'))).to eq('sign-in')
+    end
+
+    it 'ignores the title and script elements that contain the text' do
+      expect(driver.find_elements(text: 'Sign in').size).to eq(1)
+    end
+
+    it 'raises AmbiguousMatch naming three buttons' do
+      expect { driver.find_element(text: 'Save') }.to raise_error(Raider::AmbiguousMatch) { |error|
+        expect(error.message).to include('matched 3 elements', '(+0 more)')
+        expect(error.message).to include('<button id="save-a" class="primary">Save</button>',
+                                         '<button id="save-b" class="secondary">Save</button>')
+      }
+    end
+
+    it 'find_elements is never strict' do
+      expect(driver.find_elements(text: 'Save').size).to eq(3)
+    end
+  end
+
+  describe 'test_id:' do
+    it 'matches the data-testid value exactly' do
+      expect(driver.find_elements(test_id: 'item').size).to eq(0)
+      expect(id_of(driver.find_element(test_id: 'item-1'))).to eq('item-one')
+      expect(id_of(driver.find_element(test_id: 'item-2'))).to eq('item-two')
+    end
+  end
+
+  describe 'by_role' do
+    before(:all) { Raider::Spec::Browser.open('roles.html') } # rubocop:disable RSpec/BeforeAfterAll
+
+    after(:all) { Raider::Spec::Browser.open('locators.html') } # rubocop:disable RSpec/BeforeAfterAll
+
+    it 'scopes to a shadow root and leaves the document search blind to it' do
+      host = driver.find_element(id: 'shadow-host')
+      expect(host.shadow_root.find_element(by_role('button', name: 'Shadow inner')).text).to eq('Shadow inner')
+      expect(driver.find_elements(by_role('button', name: 'Shadow inner'))).to be_empty # documented engine gap
+    end
+
+    it 'filters headings by level' do
+      expect(driver.find_element(by_role('heading', level: 1)).text).to eq('Roles')
+    end
+
+    it 'finds a role inside the scope element' do
+      scope = driver.find_element(id: 'scope')
+      button = scope.find_element(by_role('button', name: 'Save'))
+      expect(driver.execute_script('return arguments[0].closest("#scope") !== null', button)).to be(true)
+    end
+
+    it 'is strict at the page level when two buttons match' do
+      expect { driver.find_element(by_role('button', name: 'Save')) }.to raise_error(Raider::AmbiguousMatch)
+    end
+  end
+
+  describe 'with a BiDi session' do
+    let(:bidi_driver) { Raider::Spec::Browser.bidi_driver }
+
+    before(:all) { Raider::Spec::Browser.bidi_driver.navigate.to(Raider::Spec::Browser.fixture_url('locators.html')) } # rubocop:disable RSpec/BeforeAfterAll
+
+    after(:all) { Raider::Spec::Browser.quit_bidi } # rubocop:disable RSpec/BeforeAfterAll
+
+    it 'finds a field by label through the BiDi bridge' do
+      expect(id_of(bidi_driver.find_element(label: 'Password'))).to eq('password')
+    end
+  end
+end

data/spec/runtime/browser/matchers_browser_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+require_relative '../support/browser'
+
+RSpec.describe 'Raider matchers in a real browser', :browser do
+  include Raider::Matchers
+
+  let(:driver) { Raider::Spec::Browser.driver }
+  let(:heading) { driver.find_element(id: 'heading') }
+
+  before do
+    Raider.timeout = 2
+    Raider::Spec::Browser.open('matchers.html')
+  end
+
+  after do
+    Raider.reset
+  end
+
+  after(:all) { Raider::Spec::Browser.quit } # rubocop:disable RSpec/BeforeAfterAll
+
+  it 'waits for the heading text to change' do
+    expect(heading).to have_text('Ready')
+  end
+
+  it 'waits for a button to hide after a click' do
+    button = driver.find_element(id: 'hide-me')
+    button.click
+    expect(button).to be_hidden
+  end
+
+  it 'reads an input value and its attributes' do
+    field = driver.find_element(id: 'name')
+    expect(field).to have_value('Ann')
+    expect(field).to have_attribute('type', 'text')
+    expect(field).to be_enabled
+  end
+
+  it 'waits for the list to grow to three items' do
+    expect { driver.find_elements(css: 'li') }.to have_count(3)
+  end
+
+  it 'waits for the title and url after a click' do
+    driver.find_element(id: 'finish').click
+    expect(driver).to have_title('Done')
+    expect(driver).to have_url(/#done$/)
+  end
+
+  it 'passes a negated matcher once the text has moved on' do
+    expect(heading).not_to have_text('Loading')
+  end
+
+  it 'works in a plain class that mixes in both matcher modules' do
+    world = Class.new do
+      include RSpec::Matchers
+      include Raider::Matchers
+
+      def check(element)
+        expect(element).to have_text('Ready', wait: 2)
+      end
+    end
+    expect(world.new.check(heading)).to be(true)
+  end
+end

data/spec/runtime/browser/retrying_block_browser_spec.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime'
+require_relative '../../../lib/ruby_raider/runtime/rspec'
+require_relative '../support/browser'
+
+RSpec.describe 'Raider block expectations in a real browser', :browser do
+  include Raider::Matchers
+
+  let(:driver) { Raider::Spec::Browser.driver }
+
+  before do
+    Raider.reset
+    Raider.timeout = 3
+    Raider::Spec::Browser.open('actionability.html')
+  end
+
+  after { Raider.reset }
+
+  after(:all) { Raider::Spec::Browser.quit } # rubocop:disable RSpec/BeforeAfterAll
+
+  it 'waits for text set after 300 ms' do
+    driver.execute_script(<<~JS)
+      document.body.insertAdjacentHTML('beforeend', '<p id="status">pending</p>');
+      setTimeout(() => { document.getElementById('status').textContent = 'done'; }, 300);
+    JS
+    expect { driver.find_element(id: 'status').text }.to eq('done')
+  end
+
+  it 'finds an element inserted after 300 ms through have_element' do
+    driver.execute_script(<<~JS)
+      setTimeout(() => document.body.insertAdjacentHTML('beforeend', '<p id="late-p">x</p>'), 300);
+    JS
+    expect(driver).to have_element(id: 'late-p')
+  end
+end

data/spec/runtime/browser/role_engine_browser_spec.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime'
+require_relative '../support/browser'
+
+RSpec.describe 'The in-page role engine', :browser do
+  let(:driver) { Raider::Spec::Browser.driver }
+
+  before(:all) { Raider::Spec::Browser.open('roles.html') } # rubocop:disable RSpec/BeforeAfterAll
+
+  after(:all) { Raider::Spec::Browser.quit } # rubocop:disable RSpec/BeforeAfterAll
+
+  def engine(body, *args)
+    driver.execute_script("#{Raider::RoleFinder::ENGINE}\n#{body}", *args)
+  end
+
+  def element(id)
+    driver.find_element(id: id)
+  end
+
+  def ids(elements)
+    elements.map { |e| e.attribute('id') }
+  end
+
+  def query(scope, role, options = {})
+    engine('return window.__raider.role(arguments[0] || document, arguments[1], arguments[2])',
+           scope, role, { 'name' => nil, 'exact' => false, 'includeHidden' => false, 'level' => nil }.merge(options))
+  end
+
+  role_cases = {
+    'r-h1' => 'heading', 'r-h2' => 'heading', 'r-h3' => 'heading', 'r-h4' => 'heading', 'r-h5' => 'heading',
+    'r-h6' => 'heading', 'r-link' => 'link', 'r-anchor' => 'generic', 'r-area' => 'link',
+    'r-article' => 'article', 'r-header-in-article' => 'generic', 'r-footer-in-article' => 'generic',
+    'r-aside' => 'complementary', 'r-button' => 'button', 'r-datalist' => 'listbox', 'r-details' => 'group',
+    'r-summary' => nil, 'r-dialog' => 'dialog', 'r-fieldset' => 'group', 'r-figure' => 'figure',
+    'r-header' => 'banner', 'r-footer' => 'contentinfo', 'r-form' => 'form', 'r-hr' => 'separator',
+    'r-img' => 'img', 'r-img-empty-alt' => 'presentation', 'r-img-presentation' => 'presentation',
+    'r-in-button' => 'button', 'r-in-image' => 'button', 'r-in-reset' => 'button', 'r-in-submit' => 'button',
+    'r-in-checkbox' => 'checkbox', 'r-in-radio' => 'radio', 'r-in-range' => 'slider',
+    'r-in-number' => 'spinbutton', 'r-in-search' => 'searchbox', 'r-in-search-list' => 'combobox',
+    'r-in-email' => 'textbox', 'r-in-tel' => 'textbox', 'r-in-text' => 'textbox', 'r-in-url' => 'textbox',
+    'r-in-password' => 'textbox', 'r-in-default' => 'textbox', 'r-in-text-list' => 'combobox',
+    'r-in-hidden' => nil, 'r-ul' => 'list', 'r-ol' => 'list', 'r-menu' => 'list', 'r-li' => 'listitem',
+    'r-li-orphan' => 'generic', 'r-main' => 'main', 'r-math' => 'math', 'r-meter' => 'meter',
+    'r-nav' => 'navigation', 'r-select' => 'combobox', 'r-option' => 'option', 'r-select-multiple' => 'listbox',
+    'r-select-size' => 'listbox', 'r-output' => 'status', 'r-progress' => 'progressbar',
+    'r-section' => 'generic', 'r-section-label' => 'region', 'r-section-labelledby' => 'region',
+    'r-table' => 'table', 'r-thead' => 'rowgroup', 'r-tbody' => 'rowgroup', 'r-tfoot' => 'rowgroup',
+    'r-tr' => 'row', 'r-th-col' => 'columnheader', 'r-th-colscope' => 'columnheader',
+    'r-th-first' => 'rowheader', 'r-th-only-1' => 'columnheader', 'r-th-only-2' => 'columnheader',
+    'cy-self' => 'region', 'cy-a' => 'region', 'cy-b' => 'region', 'cy-button' => 'button', 'r-th-second' => 'columnheader', 'r-th-scoperow' => 'rowheader',
+    'r-td' => 'cell', 'r-td-grid' => 'gridcell', 'r-td-grid-ancestor' => 'gridcell', 'r-textarea' => 'textbox',
+    'r-div' => 'generic', 'r-span' => 'generic', 'r-div-button' => 'button', 'r-role-tokens' => 'button',
+    'r-bad-role' => 'button', 'r-explicit-over-implicit' => 'button',
+    'r-p' => 'paragraph', 'r-blockquote' => 'blockquote', 'r-code' => 'code', 'r-em' => 'emphasis',
+    'r-strong' => 'strong', 'r-del' => 'deletion', 'r-ins' => 'insertion', 'r-sub' => 'subscript',
+    'r-sup' => 'superscript', 'r-time' => 'time', 'r-dfn' => 'term', 'r-dt' => 'term', 'r-dd' => 'definition',
+    'r-caption' => 'caption', 'r-html' => 'document', 'r-search' => 'search', 'r-address' => 'group',
+    'r-optgroup' => 'group'
+  }.freeze
+
+  name_cases = {
+    'n-labelledby' => 'First Second label', 'n-lb-hidden' => 'Hidden label', 'n-lb-nested' => 'Nest text',
+    'n-lb-missing' => 'Falls back', 'n-arialabel' => 'Close dialog', 'n-labelfor' => 'Email address',
+    'n-wrapped' => 'Wrapped label', 'n-img' => 'Company logo', 'n-input-image' => 'Go', 'n-area' => 'Area name',
+    'n-submit' => 'Send', 'n-input-button' => 'Plain value', 'n-reset' => 'Clear',
+    # Known gap: a valueless submit has a browser-supplied default label ("Submit") the engine does not know.
+    'n-submit-empty' => '',
+    'n-table' => 'Sales', 'n-fieldset' => 'Contact', 'n-figure' => 'Chart caption', 'n-title' => 'Tooltip only',
+    'n-title-fallback' => 'Text wins', 'n-embedded' => 'Search for cats', 'n-slider' => 'Rate 7 stars',
+    'n-select' => 'Pick Two', 'n-content' => 'Go icon now', 'n-blocks' => 'One Two', 'n-inline' => 'Abcd',
+    'n-heading' => 'Spaced title', 'n-hidden-child' => 'Visible', 'n-div-button' => 'Div button',
+    'n-generic' => '', 'n-li' => '', 'n-unreferenced-hidden' => '', 'n-unlabelled' => '', 'cy-self' => '', 'cy-a' => 'B', 'cy-b' => 'A', 'cy-button' => 'Self button',
+    'n-placeholder' => 'Email address', 'n-placeholder-title' => 'Title wins', 'n-placeholder-area' => 'Say more'
+  }.freeze
+
+  hidden_cases = {
+    'h-visible' => false, 'h-aria-hidden' => true, 'h-anc-aria' => true, 'h-anc-none' => true,
+    'h-display-none' => true, 'h-attr' => true, 'h-visibility' => true, 'h-vis-parent-child' => false,
+    'h-vis-inherit' => true, 'r-in-hidden' => true, 'o-option' => false, 'dc-button' => false
+  }.freeze
+
+  describe 'getRole' do
+    role_cases.each do |id, role|
+      it "maps ##{id} to #{role.inspect}" do
+        expect(engine('return window.__raider.getRole(arguments[0])', element(id))).to eq(role)
+      end
+    end
+  end
+
+  describe 'accessibleName' do
+    name_cases.each do |id, name|
+      it "names ##{id} #{name.inspect}" do
+        expect(engine('return window.__raider.accessibleName(arguments[0])', element(id))).to eq(name)
+      end
+    end
+  end
+
+  describe 'isHidden' do
+    hidden_cases.each do |id, hidden|
+      it "reports ##{id} hidden=#{hidden}" do
+        expect(engine('return window.__raider.isHidden(arguments[0])', element(id))).to eq(hidden)
+      end
+    end
+  end
+
+  describe 'role' do
+    it 'matches the name case-insensitively as a substring' do
+      expect(ids(query(element('saves'), 'button', 'name' => 'save'))).to eq(%w[save-1 save-2 save-3])
+    end
+
+    it 'matches a name exactly and case-sensitively' do
+      expect(ids(query(element('saves'), 'button', 'name' => 'Save', 'exact' => true))).to eq(['save-1'])
+    end
+
+    it 'adds hidden elements under includeHidden' do
+      found = ids(query(element('saves'), 'button', 'name' => 'save', 'includeHidden' => true))
+      expect(found).to eq(%w[save-1 save-2 save-3 save-hidden])
+    end
+
+    it 'searches the whole document in document order' do
+      expect(ids(query(nil, 'button', 'name' => 'Save', 'exact' => true))).to eq(%w[save-1 scope-save])
+    end
+
+    it 'limits the search to the scope and leaves the outside button out' do
+      expect(ids(query(element('scope'), 'button'))).to eq(['scope-save'])
+    end
+
+    it 'leaves out buttons under hidden ancestors and keeps the visible child of a hidden parent' do
+      found = ids(query(nil, 'button'))
+      expect(found).to include('h-visible', 'h-vis-parent-child')
+      expect(found).not_to include('h-anc-aria', 'h-anc-none', 'h-vis-inherit', 'h-visibility')
+    end
+
+    it 'finds an option inside a closed select and a display: contents button' do
+      expect(ids(query(nil, 'option', 'name' => 'Pick me'))).to eq(['o-option'])
+      expect(ids(query(nil, 'button', 'name' => 'Contents button'))).to eq(['dc-button'])
+    end
+
+    it 'filters headings by level from the tag or aria-level' do
+      expect(ids(query(nil, 'heading', 'level' => 2))).to eq(%w[r-h2 lv-aria n-heading])
+      expect(ids(query(nil, 'heading', 'level' => 1))).to eq(['r-h1'])
+    end
+
+    it 'searches a shadow root scope and resolves labelledby inside it' do
+      host = element('shadow-host')
+      names = driver.execute_script('return arguments[0].shadowRoot.querySelectorAll("button").length', host)
+      expect(names).to eq(2)
+      found = engine('return window.__raider.role(arguments[0].shadowRoot, "button", { name: "Labelled inner" })', host)
+      expect(found.size).to eq(1)
+    end
+
+    it 'never returns the scope element itself' do
+      expect(ids(query(element('scope-button'), 'button'))).to eq(['scope-inner'])
+    end
+
+    it 'finds by an explicit role on a div' do
+      expect(ids(query(element('scope-button'), 'button', 'name' => 'inner'))).to eq(['scope-inner'])
+    end
+
+    it 'still answers every role query with labelledby cycles on the page' do
+      expect(ids(query(element('cy-button').find_element(xpath: '..'), 'button', 'name' => 'Self button')))
+        .to include('cy-button')
+      expect(query(nil, 'button')).not_to be_empty
+    end
+
+    it 'writes nothing to the page but window.__raider' do
+      added = driver.execute_script(
+        "delete window.__raider; var before = Object.keys(window);\n#{Raider::RoleFinder::ENGINE}\n" \
+        'return Object.keys(window).filter(function (k) { return before.indexOf(k) < 0 })'
+      )
+      expect(added).to eq(['__raider'])
+      expect(engine('return Object.keys(window.__raider).sort()')).to eq(%w[accessibleName getRole isHidden role])
+    end
+
+    it 'merges into an existing window.__raider instead of replacing it' do
+      result = driver.execute_script(
+        "window.__raider = { keep: 1 }; #{Raider::RoleFinder::ENGINE}\nreturn [window.__raider.keep, typeof window.__raider.role]"
+      )
+      expect(result).to eq([1, 'function'])
+    end
+  end
+end

data/spec/runtime/browser/strict_browser_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../../lib/ruby_raider/runtime'
+require_relative '../support/browser'
+
+RSpec.describe 'Raider find waits in a real browser', :browser do
+  let(:driver) { Raider::Spec::Browser.driver }
+
+  before do
+    Raider.reset
+    Raider.timeout = 3
+    Raider::Spec::Browser.open('actionability.html')
+  end
+
+  after { Raider.reset }
+
+  after(:all) { Raider::Spec::Browser.quit } # rubocop:disable RSpec/BeforeAfterAll
+
+  def insert_after(delay, html)
+    driver.execute_script(<<~JS, delay, html)
+      const [delay, html] = arguments;
+      setTimeout(() => document.body.insertAdjacentHTML('beforeend', html), delay);
+    JS
+  end
+
+  it 'finds and clicks a button inserted after 300 ms' do
+    driver.execute_script('window.clicked = false')
+    insert_after(300, '<button id="late" onclick="window.clicked = true">Late</button>')
+    driver.find_element(id: 'late').click
+    expect(driver.execute_script('return window.clicked')).to be(true)
+  end
+
+  it 'returns three rows inserted after 300 ms from find_elements' do
+    insert_after(300, '<p class="late-row">1</p><p class="late-row">2</p><p class="late-row">3</p>')
+    expect(driver.find_elements(css: '.late-row').size).to eq(3)
+  end
+end

data/spec/runtime/by_role_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require_relative '../../lib/ruby_raider/runtime'
+
+RSpec.describe 'Raider.by_role' do
+  it 'returns just the role for a bare role' do
+    expect(Raider.by_role('button')).to eq(role: ['button'])
+  end
+
+  it 'adds the name option' do
+    expect(Raider.by_role('button', name: 'Save')).to eq(role: ['button', { name: 'Save' }])
+  end
+
+  it 'adds exact and include_hidden only when set' do
+    expect(Raider.by_role('link', name: 'Home', exact: true, include_hidden: true))
+      .to eq(role: ['link', { name: 'Home', exact: true, include_hidden: true }])
+    expect(Raider.by_role('link', include_hidden: true)).to eq(role: ['link', { include_hidden: true }])
+  end
+
+  it 'carries a heading level' do
+    expect(Raider.by_role('heading', name: 'Intro', level: 2)).to eq(role: ['heading', { name: 'Intro', level: 2 }])
+  end
+
+  it 'rejects a level on another role or outside 1 to 6' do
+    expect { Raider.by_role('button', level: 1) }.to raise_error(ArgumentError, /heading/)
+    expect { Raider.by_role('heading', level: 0) }.to raise_error(ArgumentError, /1 to 6/)
+    expect { Raider.by_role('heading', level: '2') }.to raise_error(ArgumentError, /1 to 6/)
+  end
+
+  it 'stringifies a symbol role' do
+    expect(Raider.by_role(:heading)).to eq(role: ['heading'])
+  end
+
+  it 'rejects an unknown role' do
+    expect { Raider.by_role('foo') }
+      .to raise_error(ArgumentError, "unknown role 'foo'; roles are the ARIA role names such as button, link, textbox")
+  end
+
+  it 'rejects a non-String name' do
+    expect { Raider.by_role('button', name: /Save/) }.to raise_error(ArgumentError)
+  end
+
+  it 'has a frozen ROLES list' do
+    expect(Raider::ROLES).to be_frozen.and include('button', 'generic')
+  end
+
+  it 'is available on Raider::Helpers' do
+    helper = Object.new.extend(Raider::Helpers)
+    expect(helper.by_role('tab', name: 'One')).to eq(role: ['tab', { name: 'One' }])
+  end
+end

data/spec/runtime/config_spec.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'rspec'
+require 'tmpdir'
+require 'fileutils'
+require_relative '../../lib/ruby_raider/runtime/config'
+
+RSpec.describe 'Raider configuration' do
+  let(:env_keys) { %w[RAIDER_STRICT RAIDER_ACTIONABILITY RAIDER_TIMEOUT RAIDER_TEST_ID_ATTRIBUTE] }
+
+  around do |example|
+    saved = env_keys.to_h { |key| [key, ENV.fetch(key, nil)] }
+    env_keys.each { |key| ENV.delete(key) }
+    Raider.reset
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) { example.run }
+    end
+  ensure
+    saved.each { |key, value| value ? ENV[key] = value : ENV.delete(key) }
+    Raider.reset
+  end
+
+  def write_config(content)
+    FileUtils.mkdir_p('config')
+    File.write(Raider::CONFIG_FILE, content)
+    Raider.reset
+  end
+
+  it 'uses defaults without a file or env' do
+    expect([Raider.strict, Raider.actionability, Raider.timeout, Raider.test_id_attribute])
+      .to eq([true, true, 10, 'data-testid'])
+  end
+
+  it 'prefers file values over defaults' do
+    write_config("strict: false\nactionability: 'off'\ntimeout: 3.5\ntest_id_attribute: data-qa\n")
+    expect([Raider.strict, Raider.actionability, Raider.timeout, Raider.test_id_attribute])
+      .to eq([false, false, 3.5, 'data-qa'])
+  end
+
+  it 'prefers env over the file' do
+    write_config("strict: true\n")
+    ENV['RAIDER_STRICT'] = 'off'
+    expect(Raider.strict).to be(false)
+  end
+
+  it 'reads env timeout and test id attribute' do
+    ENV['RAIDER_TIMEOUT'] = '2.5'
+    ENV['RAIDER_TEST_ID_ATTRIBUTE'] = 'data-cy'
+    expect([Raider.timeout, Raider.test_id_attribute]).to eq([2.5, 'data-cy'])
+  end
+
+  it 'prefers the setter over env' do
+    ENV['RAIDER_STRICT'] = 'off'
+    Raider.strict = true
+    expect(Raider.strict).to be(true)
+  end
+
+  it 'ignores a non-Hash YAML file' do
+    write_config("- one\n- two\n")
+    expect(Raider.timeout).to eq(10)
+  end
+
+  it 'reads a file that holds a symbol value' do
+    write_config("platform: :ios\ntimeout: 7\n")
+    expect(Raider.timeout).to eq(7)
+  end
+
+  it 'raises Raider::Error naming the file for malformed YAML' do
+    write_config("timeout: [7\n")
+    expect { Raider.timeout }.to raise_error(Raider::Error, %r{config/config\.yml})
+  end
+
+  it 're-reads the file after reset' do
+    write_config("timeout: 4\n")
+    expect(Raider.timeout).to eq(4)
+    write_config("timeout: 6\n")
+    expect(Raider.timeout).to eq(6)
+  end
+end