ruby_raider 3.12.1 → 3.13.0

data/spec/integration/helpers/wait_helper_spec.rb

@@ -472,6 +472,189 @@ describe 'WaitHelper' do
     end
   end
 
+  describe '.observer' do
+    # Records every hook call; tokens are the call's index.
+    let(:observer) do
+      Class.new do
+        attr_reader :calls
+
+        def initialize = @calls = []
+
+        %i[action_started group_started].each do |hook|
+          define_method(hook) do |**details|
+            @calls << [hook, details]
+            @calls.size - 1
+          end
+        end
+
+        %i[action_ready action_finished group_retried group_finished].each do |hook|
+          define_method(hook) do |token, **details|
+            @calls << [hook, token, details]
+          end
+        end
+      end.new
+    end
+
+    around do |example|
+      WaitHelper.observer = observer
+      example.run
+    ensure
+      WaitHelper.observer = nil
+    end
+
+    def started = observer.calls.select { |call| call.first == :action_started }.map(&:last)
+    def finished = observer.calls.select { |call| call.first == :action_finished }.map(&:last)
+
+    it 'reports a click with its locator, source line, waited time and the ready element' do
+      button = element
+      driver.script({ id: 'go' }, nil, button)
+      line = __LINE__ + 1
+      page.click({ id: 'go' }, timeout: 1)
+
+      expect(observer.calls.map(&:first)).to eq(%i[action_started action_ready action_finished])
+      expect(started.first).to include(action: :click, locator: { strategy: 'id', selector: 'go' }, within: [],
+                                       source: { file: Pathname(__FILE__).relative_path_from(Dir.pwd).to_s, line: line })
+        .and(satisfy { |details| !details.key?(:label) })
+      expect(observer.calls[2][1]).to eq(0)
+      expect(finished.first).to include(status: :passed, retries: 2, error: nil, element: button)
+      expect(finished.first[:waited_ms]).to be_between(50, 500)
+    end
+
+    it 'reports the keys of send_keys and how and what of select_by as args, and nil args for other actions' do
+      driver.script({ id: 'user' }, element)
+      driver.script({ id: 'colour' }, WaitHelperSpec::FakeSelect.new)
+      page.send_keys({ id: 'user' }, 'admin', :enter, timeout: 1)
+      page.select_by({ id: 'colour' }, :text, 'Blue', timeout: 1)
+      page.click({ id: 'user' }, timeout: 1)
+
+      expect(started.map { |event| event.values_at(:action, :args) })
+        .to eq([[:send_keys, ['admin', :enter]], [:select_by, [:text, 'Blue']], [:click, nil]])
+    end
+
+    it 'reports action_ready with the ready element before the action block runs' do
+      field = element
+      driver.script({ id: 'user' }, nil, field)
+      log_when_ready = []
+      allow(observer).to receive(:action_ready).and_wrap_original do |original, token, **details|
+        log_when_ready << details[:element].log.dup
+        original.call(token, **details)
+      end
+      page.send_keys({ id: 'user' }, 'admin', timeout: 1)
+
+      expect(observer.calls.map(&:first)).to eq(%i[action_started action_ready action_finished])
+      expect(observer.calls[1]).to eq([:action_ready, 0, { element: field }])
+      expect(log_when_ready).to eq([[]])
+      expect(field.log).to eq([[:send_keys, 'admin']])
+    end
+
+    it 'reports a chained find with within, outermost first' do
+      driver.script({ css: '.form' }, element.script({ tag_name: 'td' }, element.script({ id: 'email' }, element)))
+      page.find_element(css: '.form').find_element(tag_name: 'td').find_element(id: 'email')
+
+      expect(started.last).to include(action: :find_element, locator: { strategy: 'id', selector: 'email' },
+                                      within: [{ strategy: 'css', selector: '.form' }, { strategy: 'tag_name', selector: 'td' }])
+    end
+
+    it 'reports a timed-out action as failed with its error, then re-raises' do
+      driver.script({ id: 'gone' }, nil)
+      expect { page.click({ id: 'gone' }, timeout: 0.3) }.to raise_error(WaitHelper::TimeoutError)
+
+      expect(finished.first).to include(status: :failed, element: nil)
+      expect(finished.first[:error]).to be_a(WaitHelper::TimeoutError)
+      expect(finished.first[:retries]).to be >= 2
+    end
+
+    it 'reports eventually as a group with the retries it took' do
+      tries = 0
+      page.eventually(timeout: 2) { expect(tries += 1).to eq(3) }
+
+      group = observer.calls.find { |call| call.first == :group_started }.last
+      expect(group).to include(action: :eventually)
+      expect(group[:source]).to include(line: be_a(Integer))
+      expect(observer.calls.last).to match([:group_finished, 0, { status: :passed, retries: 2, error: nil }])
+    end
+
+    it 'reports group_retried with the group token and the earlier error before each new pass of eventually' do
+      tries = 0
+      page.eventually(timeout: 2) { expect(tries += 1).to eq(3) }
+
+      retried = observer.calls.select { |call| call.first == :group_retried }
+      expect(retried.map { |call| call[1] }).to eq([0, 0])
+      expect(retried.map { |call| call.last[:error] }).to all(be_a(RSpec::Expectations::ExpectationNotMetError))
+      expect(observer.calls.map(&:first)).to eq(%i[group_started group_retried group_retried group_finished])
+    end
+
+    it 'reports a failing eventually as failed with its error' do
+      tries = 0
+      expect { page.eventually(timeout: 0.2) { expect(tries += 1).to eq(0) } }.to raise_error(RSpec::Expectations::ExpectationNotMetError)
+      expect(observer.calls.last.last).to include(status: :failed, error: be_a(RSpec::Expectations::ExpectationNotMetError))
+    end
+
+    it 'normalises class to class_name and link to link_text' do
+      aliases = { css_selector: 'css', class: 'class_name', link: 'link_text', partial_link: 'partial_link_text', name: 'name' }
+      aliases.each_key do |strategy|
+        driver.script({ strategy => 'x' }, element)
+        page.displayed?({ strategy => 'x' }, timeout: 0)
+      end
+
+      expect(started.map { |event| event[:locator][:strategy] }).to eq(aliases.values)
+    end
+
+    it 'never takes the source from a file in helpers/, such as the trace helper' do
+      # The given path of wait_helper.rb, and the real path of raider_element.rb (via __dir__).
+      given, real = WaitHelper::Waiter::HELPER_FILES.map { |file| File.dirname(file) }
+
+      expect(WaitHelper::Observation.project?(File.join(given, 'trace_helper.rb'))).to be(false)
+      expect(WaitHelper::Observation.project?(File.join(real, 'driver_helper.rb'))).to be(false)
+      expect(WaitHelper::Observation.project?(File.expand_path('spec/login_spec.rb'))).to be(true)
+    end
+
+    it 'reports no label for an action called from a page_objects method' do
+      Dir.mktmpdir do |dir|
+        FileUtils.mkdir_p(File.join(dir, 'page_objects'))
+        path = File.join(dir, 'page_objects', 'login.rb')
+        File.write(path, "def login_button(page) = page.click({ id: 'go' }, timeout: 1)\n")
+        load path
+        driver.script({ id: 'go' }, element)
+        login_button(page)
+      end
+
+      expect(started.first).not_to have_key(:label)
+      expect(started.first[:source][:file]).to end_with('page_objects/login.rb')
+    end
+
+    it 'drops the observer, warns once, and still clicks when working out the source raises' do
+      button = element
+      driver.script({ id: 'go' }, button)
+      allow(Dir).to receive(:pwd).and_raise(Errno::ENOENT)
+
+      expect { 2.times { page.click({ id: 'go' }, timeout: 1) } }.to output(/\A\[trace\] observer stopped: Errno::ENOENT.*\n\z/).to_stderr
+      expect(button.log).to eq([%i[click]] * 2)
+      expect(WaitHelper.observer).to be_nil
+    end
+
+    it 'drops an observer that raises, warns once, and still clicks' do
+      allow(observer).to receive(:action_started).and_raise('boom')
+      button = element
+      driver.script({ id: 'go' }, button)
+
+      expect { 2.times { page.click({ id: 'go' }, timeout: 1) } }.to output(/\A\[trace\] observer stopped: RuntimeError: boom\n\z/).to_stderr
+      expect(button.log).to eq([%i[click]] * 2)
+      expect(WaitHelper.observer).to be_nil
+    end
+
+    it 'still prints observer stopped under -W0, where Kernel#warn is silent' do
+      allow(observer).to receive(:action_started).and_raise('boom')
+      driver.script({ id: 'go' }, element)
+      verbose = $VERBOSE
+      $VERBOSE = nil
+
+      expect { page.click({ id: 'go' }, timeout: 1) }.to output("[trace] observer stopped: RuntimeError: boom\n").to_stderr
+    ensure
+      $VERBOSE = verbose
+    end
+  end
+
   describe '.default_timeout' do
     around do |example|
       Dir.mktmpdir do |dir|

data/spec/integration/trace_format_checker.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'zip'
+
+# Checks a trace.zip against the raider-trace v1 format (trace viewer spec §1) and
+# returns the problems it finds, so a spec can `expect(problems).to be_empty`.
+# Stricter than readers need to be: an unknown locator strategy is a problem here.
+module TraceFormatChecker
+  ENTRY_NAME = %r{\Atrace\.json\z|\Asteps/\d{4}\.(jpg|png|html|xml)\z}
+  TIMESTAMP = /\A\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z\z/
+  KINDS = %w[navigate action group failure].freeze
+  STRATEGIES = %w[id css xpath name link_text partial_link_text class_name tag_name].freeze
+  # The required keys and the types each may have: the top level, then every step.
+  FIELDS = {
+    top: {
+      'format' => [String], 'version' => [Integer], 'producer' => [Hash], 'test' => [Hash],
+      'browser' => [Hash], 'viewport' => [Hash], 'device_pixel_ratio' => [Integer, Float],
+      'started_at' => [String], 'finished_at' => [String], 'capabilities' => [Hash],
+      'truncated' => [Hash], 'steps' => [Array], 'network' => [Array], 'console' => [Array]
+    }.freeze,
+    step: {
+      'index' => [Integer], 'parent_index' => [Integer, NilClass], 'kind' => [String], 'action' => [String],
+      'locator' => [Hash, NilClass], 'url' => [String, NilClass], 'page_title' => [String, NilClass],
+      'started_at' => [String], 'duration_ms' => [Integer], 'waited_ms' => [Integer], 'retries' => [Integer],
+      'status' => [String], 'error' => [Hash, NilClass], 'source' => [Hash, NilClass], 'rect' => [Hash, NilClass],
+      'screenshot' => [String, NilClass], 'snapshot' => [String, NilClass]
+    }.freeze
+  }.freeze
+
+  # The parsed trace.json and the zip's entry names.
+  def self.read(path)
+    Zip::File.open(path) do |zip|
+      [JSON.parse(zip.read('trace.json')), zip.entries.map(&:name)]
+    end
+  end
+
+  def self.problems(path)
+    trace, names = read(path)
+    problems = names.grep_v(ENTRY_NAME).map { |name| "entry #{name.inspect} is not an allowed name" }
+    problems.concat(identity(trace)).concat(typed('trace', trace, FIELDS[:top]))
+    problems.concat(error_rules('test', trace['test'])) if trace['test'].is_a?(Hash)
+    return problems unless trace['steps'].is_a?(Array)
+
+    problems.concat(steps(trace['steps'], names)).concat(events(trace))
+  rescue Zip::Error, JSON::ParserError, Errno::ENOENT => e
+    ["not a readable trace.zip: #{e.class}: #{e.message}"]
+  end
+
+  def self.identity(trace)
+    problems = []
+    problems << "format is #{trace['format'].inspect}, not \"raider-trace\"" unless trace['format'] == 'raider-trace'
+    problems << "version is #{trace['version'].inspect}, not 1" unless trace['version'] == 1
+    problems
+  end
+
+  def self.typed(where, hash, fields)
+    fields.flat_map do |key, types|
+      next ["#{where} has no #{key.inspect}"] unless hash.key?(key)
+
+      value = hash[key]
+      next [] if types.any? { |type| value.is_a?(type) }
+
+      ["#{where}.#{key} is #{value.inspect}, not #{types.join(' or ')}"]
+    end
+  end
+
+  def self.steps(steps, names)
+    steps.each_with_index.flat_map do |step, position|
+      where = "steps[#{position}]"
+      next ["#{where} is not an object"] unless step.is_a?(Hash)
+
+      typed(where, step, FIELDS[:step]) + step_rules(where, step, position, names)
+    end
+  end
+
+  def self.step_rules(where, step, position, names)
+    problems = []
+    problems << "#{where}.index is #{step['index'].inspect}, not #{position + 1}" unless step['index'] == position + 1
+    problems << "#{where}.kind #{step['kind'].inspect} is not one of #{KINDS.join(', ')}" unless KINDS.include?(step['kind'])
+    problems << "#{where}.started_at #{step['started_at'].inspect} is not UTC ISO-8601 with ms" unless TIMESTAMP.match?(step['started_at'].to_s)
+    parent = step['parent_index']
+    problems << "#{where}.parent_index #{parent} is not an earlier step" if parent && !parent.between?(1, position)
+    problems.concat(error_rules(where, step))
+    problems.concat(locator_rules(where, step['locator']))
+    problems.concat(typed_rules(where, step))
+    problems.concat(media_rules(where, step, names))
+  end
+
+  # error is null or { "class": String, "message": String }, on steps and on test.
+  def self.error_rules(where, holder)
+    return ["#{where} has no \"error\""] unless holder.key?('error')
+
+    error = holder['error']
+    return [] if error.nil?
+    return ["#{where}.error is #{error.inspect}, not null or an object"] unless error.is_a?(Hash)
+
+    %w[class message].filter_map { |key| "#{where}.error.#{key} is not a string" unless error[key].is_a?(String) }
+  end
+
+  # label is optional: ruby_raider never writes it, but another producer may.
+  def self.locator_rules(where, locator)
+    return [] unless locator.is_a?(Hash)
+
+    label = locator.key?('label') && !locator['label'].is_a?(String) ? ["#{where}.locator.label is not a string"] : []
+    label + [locator, *Array(locator['within'])].filter_map do |one|
+      strategy = one['strategy']
+      "#{where}.locator strategy #{strategy.inspect} is not canonical" unless STRATEGIES.include?(strategy)
+    end
+  end
+
+  # value and secret exist only on send_keys and select_by; a secret value is null.
+  # element, when present, is { tag, label?, role? } on an action step.
+  def self.typed_rules(where, step)
+    problems = []
+    typed = %w[send_keys select_by].include?(step['action'])
+    problems << "#{where} has value/secret but is not send_keys or select_by" if !typed && (step.key?('value') || step.key?('secret'))
+    problems << "#{where} is #{step['action']} without value and secret" if typed && !(step.key?('value') && step.key?('secret'))
+    problems << "#{where}.secret is true but value is not null" if step['secret'] == true && !step['value'].nil?
+    element = step['element']
+    problems << "#{where}.element is not an action step's { tag, label?, role? }" if step.key?('element') && !(element.is_a?(Hash) && element['tag'].is_a?(String) && step['kind'] == 'action')
+    problems
+  end
+
+  def self.media_rules(where, step, names)
+    %w[screenshot snapshot].filter_map do |key|
+      entry = step[key]
+      "#{where}.#{key} #{entry.inspect} is not an entry in the zip" if entry && !names.include?(entry)
+    end
+  end
+
+  def self.events(trace)
+    count = [trace['steps'].size, 1].max
+    %w[network console].flat_map do |list|
+      Array(trace[list]).each_with_index.filter_map do |event, position|
+        index = event.is_a?(Hash) ? event['step_index'] : nil
+        "#{list}[#{position}].step_index #{index.inspect} is not between 1 and #{count}" unless index.is_a?(Integer) && index.between?(1, count)
+      end
+    end
+  end
+end

data/spec/integration/trace_page_server.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+# Serves the trace e2e page over HTTP on 127.0.0.1 (never file://), so the browser makes
+# real requests that WebDriver BiDi reports: the page, its same-origin stylesheet and /api.
+class TracePageServer
+  CSS_RULE = '#title { color: rgb(1, 2, 3); }'
+  PAGE = <<~HTML
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>Trace e2e</title>
+        <link rel="stylesheet" href="/style.css">
+      </head>
+      <body>
+        <h1 id="title">Trace</h1>
+        <input type="password" id="pw" placeholder="Password">
+        <input type="text" id="pw2" autocomplete="current-password" placeholder="Confirm password">
+        <input id="name" placeholder="Name">
+        <button id="go">Go</button>
+        <p id="status"></p>
+        <script>
+          document.getElementById('go').addEventListener('click', function () {
+            fetch('/api').then(function (response) { return response.json(); })
+              .then(function (body) { document.getElementById('status').textContent = body.status; });
+            console.error('trace e2e error');
+          });
+        </script>
+      </body>
+    </html>
+  HTML
+  ROUTES = {
+    '/' => ['200 OK', 'text/html; charset=utf-8', PAGE],
+    '/style.css' => ['200 OK', 'text/css', "#{CSS_RULE}\n"],
+    '/api' => ['200 OK', 'application/json', '{"status":"answered by /api"}']
+  }.freeze
+  NOT_FOUND = ['404 Not Found', 'text/plain', 'not found'].freeze
+  # /api answers this late, so a network entry's duration_ms has something to measure.
+  API_DELAY = 0.3
+
+  attr_reader :url
+
+  def initialize
+    @server = TCPServer.new('127.0.0.1', 0)
+    @url = "http://127.0.0.1:#{@server.addr[1]}/"
+    @thread = Thread.new { accept_loop }
+  end
+
+  def stop
+    @thread.kill
+    @server.close
+  end
+
+  private
+
+  # A thread per connection: Chrome opens speculative connections that may send nothing.
+  def accept_loop
+    loop do
+      client = @server.accept
+      Thread.new(client) { |socket| answer(socket) }
+    end
+  rescue IOError
+    nil
+  end
+
+  def answer(socket)
+    request_line = socket.gets.to_s
+    nil while (line = socket.gets) && line != "\r\n"
+    path = request_line.split[1].to_s.split('?').first
+    status, type, body = ROUTES.fetch(path, NOT_FOUND)
+    sleep(API_DELAY) if path == '/api'
+    socket.write("HTTP/1.1 #{status}\r\nContent-Type: #{type}\r\nContent-Length: #{body.bytesize}\r\n" \
+                 "Cache-Control: no-store\r\nConnection: close\r\n\r\n#{body}")
+  rescue StandardError => e
+    warn "[trace page server] #{e.class}: #{e.message}"
+  ensure
+    socket.close
+  end
+end

data/spec/utilities/trace_command_spec.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'fileutils'
+require 'yaml'
+require 'stringio'
+require_relative '../../lib/commands/utility_commands'
+
+# rubocop:disable RSpec/FilePath
+RSpec.describe UtilityCommands do
+  let(:dir) { Dir.mktmpdir('raider-trace-project') }
+  let(:config_path) { File.join(dir, 'config', 'config.yml') }
+
+  around do |example|
+    FileUtils.mkdir_p(File.join(dir, 'config'))
+    File.write(config_path, "browser: chrome\ntimeout: 10\ntrace:\n  enabled: true\n  max_steps: 200\n  max_mb: 20\n")
+    Dir.chdir(dir) { example.run }
+  ensure
+    FileUtils.rm_rf(dir)
+  end
+
+  def run_cli(*args)
+    out = StringIO.new
+    err = StringIO.new
+    status = 0
+    $stdout = out
+    $stderr = err
+    begin
+      described_class.start(args)
+    rescue SystemExit => e
+      status = e.status
+    ensure
+      $stdout = STDOUT
+      $stderr = STDERR
+    end
+    [out.string, err.string, status]
+  end
+
+  describe 'trace on/off' do
+    it 'round-trips trace.enabled, keeping the other trace keys and config keys' do
+      out, _err, status = run_cli('trace', 'off')
+      config = YAML.load_file(config_path)
+      expect([status, out]).to match([0, /Trace capture disabled/])
+      expect(config).to include('browser' => 'chrome', 'timeout' => 10, 'trace' => { 'enabled' => false, 'max_steps' => 200, 'max_mb' => 20 })
+
+      out, = run_cli('trace', 'on')
+      expect(out).to include('Trace capture enabled')
+      expect(YAML.load_file(config_path)['trace']).to eq('enabled' => true, 'max_steps' => 200, 'max_mb' => 20)
+    end
+
+    it 'adds a trace block to a config that has none' do
+      File.write(config_path, "browser: chrome\n")
+      run_cli('trace', 'off')
+      expect(YAML.load_file(config_path)['trace']).to eq('enabled' => false)
+    end
+  end
+
+  describe 'trace with an unknown subcommand' do
+    it 'exits 1 with usage' do
+      _out, err, status = run_cli('trace', 'bogus')
+      expect(status).to eq(1)
+      expect(err).to include("Unknown trace command 'bogus'", 'on|off')
+    end
+  end
+end
+# rubocop:enable RSpec/FilePath

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_raider
 version: !ruby/object:Gem::Version
-  version: 3.12.1
+  version: 3.13.0
 platform: ruby
 authors:
 - Agustin Pequeno
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-11-01 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -122,6 +122,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
@@ -292,6 +312,7 @@ files:
 - lib/generators/templates/helpers/raider_element.tt
 - lib/generators/templates/helpers/session_state.tt
 - lib/generators/templates/helpers/spec_helper.tt
+- lib/generators/templates/helpers/trace_helper.tt
 - lib/generators/templates/helpers/video_helper.tt
 - lib/generators/templates/helpers/wait_helper.tt
 - lib/ruby_raider.rb
@@ -353,6 +374,7 @@ files:
 - spec/generators/fixtures/templates/test_partial.tt
 - spec/generators/fixtures/video_helper_stubs/selenium-webdriver.rb
 - spec/generators/template_renderer_spec.rb
+- spec/generators/trace_helper_spec.rb
 - spec/generators/video_helper_spec.rb
 - spec/integration/commands/browser_update_after_creation_spec.rb
 - spec/integration/commands/scaffolding_commands_spec.rb
@@ -391,6 +413,8 @@ files:
 - spec/integration/scaffolding_e2e_spec.rb
 - spec/integration/settings_helper.rb
 - spec/integration/spec_helper.rb
+- spec/integration/trace_format_checker.rb
+- spec/integration/trace_page_server.rb
 - spec/menus/menu_generator_spec.rb
 - spec/scaffolding/name_normalizer_spec.rb
 - spec/scaffolding/scaffold_project_detector_spec.rb
@@ -401,6 +425,7 @@ files:
 - spec/utilities/desktop_downloader_spec.rb
 - spec/utilities/ffmpeg_spec.rb
 - spec/utilities/headless_config_spec.rb
+- spec/utilities/trace_command_spec.rb
 - spec/utilities/utilities_spec.rb
 - spec/utilities/video_command_spec.rb
 homepage: https://github.com/RubyRaider/ruby_raider