ruby_raider 3.13.0 → 4.0.0

data/spec/generators/trace_helper_spec.rb

@@ -7,6 +7,7 @@ require 'tmpdir'
 require 'yaml'
 require 'zip'
 require_relative '../../lib/generators/helper_generator'
+require_relative '../../lib/ruby_raider/runtime'
 require_relative '../integration/trace_format_checker'
 
 $LOAD_PATH.unshift(File.expand_path('fixtures/video_helper_stubs', __dir__))
@@ -54,7 +55,7 @@ class FakeTraceBidi
 end
 
 # Renders the real trace_helper.tt for a Selenium project, loads it, and drives its
-# Recorder the way WaitHelper's observer hook and the navigation listener do, with a
+# Recorder the way the runtime reports to Raider.observer and the navigation listener does, with a
 # driver double. The zips it writes are read back with rubyzip.
 # rubocop:disable RSpec/MultipleMemoizedHelpers, RSpec/VerifiedDoubles, RSpec/ExpectOutput, RSpec/MultipleExpectations, RSpec/ExampleLength
 describe 'Generated TraceHelper' do
@@ -67,22 +68,13 @@ describe 'Generated TraceHelper' do
   let(:bidi) { FakeTraceBidi.new(jpeg) }
   let(:html) { "<html><head><title>Login</title></head><body>#{'<p>row</p>' * 50}</body></html>" }
   let(:capabilities) { double('capabilities', browser_name: 'chrome', browser_version: '131.0.6778.85') }
-  let(:window) { double('window', size: double('size', width: 1920, height: 1080)) }
   let(:driver) do
     double('driver', screenshot_as: png, page_source: html, current_url: 'https://example.test/login', title: 'Login',
-                     capabilities: capabilities, manage: double('manage', window: window), execute_script: 2,
+                     capabilities: capabilities, execute_script: 2,
                      bidi: bidi, window_handle: 'context-1')
   end
-  let(:wait_helper) do
-    Module.new do
-      class << self
-        attr_accessor :observer
-      end
-    end
-  end
   let(:stderr) { StringIO.new }
   let(:warnings) { stderr.string.lines.grep(/\[trace\]/) }
-  let(:source) { { file: 'spec/login_page_spec.rb', line: 12 } }
   let(:failed_test) { { identifier: 'spec/login_page_spec.rb[1:1]', full_name: 'Login page logs in', status: 'failed', attempt: 2, error: nil } }
 
   def render_and_load
@@ -93,16 +85,25 @@ describe 'Generated TraceHelper' do
     load path
   end
 
+  # The inner viewport, which is what rects and the viewport screenshot are measured in.
+  def viewport_script(size)
+    allow(driver).to receive(:execute_script).with(/innerWidth/).and_return(size)
+  end
+
   def started_recorder(**lambdas)
     TraceHelper.recorder_for(driver, **lambdas).tap(&:start)
   end
 
-  # What WaitHelper reports for one action. With an element, it was found ready (action_ready).
-  def act(recorder, action, selector, status: :passed, error: nil, within: [], args: nil, element: nil)
-    token = recorder.action_started(action: action, locator: { strategy: 'id', selector: selector }, within: within,
-                                    source: source, args: args)
-    recorder.action_ready(token, element: element) if element
-    recorder.action_finished(token, status: status, waited_ms: 95, retries: 1, error: error, element: element)
+  # What the runtime reports to Raider.observer for one action, through Raider.report. With an element, it was found
+  # ready (action_ready). Returns the recorder's token.
+  def act(_recorder, action, selector, status: :passed, error: nil, within: [], args: nil, element: nil)
+    started = { action: action, locator: { strategy: 'id', selector: selector }, within: within, args: args }
+    token = Raider.report(:action_started) { started } # ACT_LINE
+    Raider.report(:action_ready, token) { { element: element } } if element
+    Raider.report(:action_finished, token) do
+      { status: status, waited_ms: 95, retries: 1, error: error, element: element }
+    end
+    token
   end
 
   # What Page.capture's script answers: the inlined CSS, the sheets it could not read and the title.
@@ -117,6 +118,11 @@ describe 'Generated TraceHelper' do
     allow(driver).to receive(:execute_script).with(/getBoundingClientRect/, element).and_return(info)
   end
 
+  # The line of act that reports a start, which is where each recorded source points.
+  def act_line
+    File.foreach(__FILE__).find_index { |line| line.end_with?("# ACT_LINE\n") && line.include?('Raider.report') } + 1
+  end
+
   def snapshot_of(path, index)
     Zip::File.open(path) { |zip| zip.read(format('steps/%04d.html', index)) }
   end
@@ -135,6 +141,7 @@ describe 'Generated TraceHelper' do
     Dir.chdir(project_dir) { example.run }
   ensure
     $stderr = original_stderr
+    Raider.observer = nil
     Object.send(:remove_const, :TraceHelper) if defined?(TraceHelper)
     FileUtils.rm_rf(project_dir)
   end
@@ -143,11 +150,11 @@ describe 'Generated TraceHelper' do
     # Recorder tmpdirs land inside the project, which the around hook removes.
     stub_const('ENV', ENV.to_h.merge(env).merge('TMPDIR' => File.join(project_dir, 'tmp')).compact)
     FileUtils.mkdir_p(File.join(project_dir, 'tmp'))
-    stub_const('WaitHelper', wait_helper)
     render_and_load
   end
 
   it 'writes a zip whose trace.json has format raider-trace, version 1 and the spec §1 top-level keys' do
+    viewport_script([1905, 969])
     recorder = started_recorder
     recorder.navigated('https://example.test/login')
     trace = kept(recorder)
@@ -159,12 +166,49 @@ describe 'Generated TraceHelper' do
                              'test' => { 'identifier' => 'spec/login_page_spec.rb[1:1]', 'full_name' => 'Login page logs in',
                                          'status' => 'failed', 'attempt' => 2, 'error' => nil },
                              'browser' => { 'name' => 'chrome', 'version' => '131.0.6778.85' },
-                             'viewport' => { 'width' => 1920, 'height' => 1080 }, 'device_pixel_ratio' => 2,
+                             'viewport' => { 'width' => 1905, 'height' => 969 }, 'device_pixel_ratio' => 2,
                              'capabilities' => { 'network' => true, 'console' => true, 'screenshots' => true, 'snapshots' => true },
                              'truncated' => { 'steps' => 0, 'screenshots' => 0, 'snapshots' => 0, 'network' => 0, 'console' => 0 })
     expect(trace['finished_at'] >= trace['started_at']).to be(true)
   end
 
+  it 'records a match_screenshot step with the given PNG as its screenshot, without taking another one' do
+    taken = 0
+    recorder = started_recorder(screenshot: ->(_driver) { [(taken += 1) && 'NAV', 'png'] })
+    recorder.navigated('https://example.test/login')
+    recorder.screenshot_compared(name: 'home', status: :failed, png: 'PNG-BYTES')
+    path = recorder.stop(keep: true, test: failed_test)
+    steps = TraceFormatChecker.read(path).first['steps']
+
+    expect(TraceFormatChecker.problems(path)).to eq([])
+    expect(steps.last).to include('kind' => 'action', 'action' => 'match_screenshot', 'name' => 'home', 'locator' => nil,
+                                  'status' => 'failed', 'error' => nil, 'screenshot' => 'steps/0002.png', 'snapshot' => nil)
+    expect(Zip::File.open(path) { |zip| zip.read('steps/0002.png') }).to eq('PNG-BYTES')
+    expect(taken).to eq(1)
+  end
+
+  it 'gives the match_screenshot step the comparison error and appends no failure step for it' do
+    recorder = started_recorder
+    error = RuntimeError.new('1 pixel differs')
+    recorder.screenshot_compared(name: 'home', status: :failed, png: 'PNG', error: error)
+    steps = kept(recorder, failed_test.merge(error: error))['steps']
+
+    expect(steps.map { |step| step.values_at('kind', 'action', 'status') }).to eq([%w[action match_screenshot failed]])
+    expect(steps.first['error']).to eq('class' => 'RuntimeError', 'message' => '1 pixel differs')
+  end
+
+  it 'records a passed comparison and never fails the test when the step cannot be written' do
+    recorder = started_recorder
+    recorder.screenshot_compared(name: 'home', status: :passed, png: 'PNG')
+    expect(kept(recorder)['steps'].last).to include('action' => 'match_screenshot', 'status' => 'passed')
+    allow(recorder).to receive(:add).and_raise('boom')
+    expect { recorder.screenshot_compared(name: 'again', status: :passed, png: 'PNG') }.not_to raise_error
+  end
+
+  it 'does not take match_screenshot as a media action' do
+    expect(TraceHelper::MEDIA_ACTIONS).not_to include('match_screenshot')
+  end
+
   it 'records navigate and click steps in order with index, kind, action, locator, source, waited_ms, retries' do
     recorder = started_recorder
     recorder.navigated('https://example.test/login')
@@ -178,7 +222,7 @@ describe 'Generated TraceHelper' do
     # No locator.label: a page object's element method has returned before the action runs, so it is never known.
     expect(steps.last).to include('locator' => { 'strategy' => 'id', 'selector' => 'go',
                                                  'within' => [{ 'strategy' => 'css', 'selector' => '.form' }] },
-                                  'source' => { 'file' => 'spec/login_page_spec.rb', 'line' => 12 },
+                                  'source' => { 'file' => __FILE__, 'line' => act_line },
                                   'waited_ms' => 95, 'retries' => 1, 'status' => 'passed',
                                   'screenshot' => 'steps/0002.jpg', 'snapshot' => 'steps/0002.html')
     expect(steps.last['duration_ms']).to be_a(Integer)
@@ -206,47 +250,6 @@ describe 'Generated TraceHelper' do
     expect(names).to contain_exactly('trace.json', 'steps/0001.jpg', 'steps/0001.html')
   end
 
-  it 'records a Cucumber step as a cucumber_step group carrying its name, with the actions it ran as children' do
-    recorder = started_recorder
-    group = recorder.step_started(name: 'When I log in as admin', source: source)
-    act(recorder, :click, 'login')
-    recorder.step_finished(group, status: :passed, error: nil)
-    act(recorder, :click, 'outside')
-    steps = kept(recorder)['steps']
-
-    expect(steps.map { |step| step.values_at('index', 'parent_index', 'kind', 'action', 'status', 'name') })
-      .to eq([[1, nil, 'group', 'cucumber_step', 'passed', 'When I log in as admin'], [2, 1, 'action', 'click', 'passed', nil],
-              [3, nil, 'action', 'click', 'passed', nil]])
-    expect(steps[1..].map { |step| step.key?('name') }).to eq([false, false])
-  end
-
-  it 'records a failed Cucumber step with its error' do
-    recorder = started_recorder
-    group = recorder.step_started(name: 'Then I see the dashboard', source: source)
-    recorder.step_finished(group, status: :failed, error: RuntimeError.new('no dashboard'))
-    step = kept(recorder)['steps'].first
-
-    expect(step).to include('status' => 'failed', 'error' => { 'class' => 'RuntimeError', 'message' => 'no dashboard' })
-  end
-
-  it 'keeps only the last pass of eventually as child steps and counts the earlier passes in retries' do
-    recorder = started_recorder
-    group = recorder.group_started(action: :eventually, source: source)
-    2.times do |pass|
-      act(recorder, :click, 'refresh')
-      act(recorder, :text, 'welcome', status: :failed, error: RuntimeError.new("not yet #{pass}"))
-      recorder.group_retried(group, error: RuntimeError.new("not yet #{pass}"))
-    end
-    act(recorder, :click, 'refresh')
-    act(recorder, :text, 'welcome')
-    recorder.group_finished(group, status: :passed, retries: 2, error: nil)
-    steps = kept(recorder)['steps']
-
-    expect(steps.map { |step| step.values_at('index', 'parent_index', 'kind', 'action', 'status') })
-      .to eq([[1, nil, 'group', 'eventually', 'passed'], [2, 1, 'action', 'click', 'passed'], [3, 1, 'action', 'text', 'passed']])
-    expect(steps.first).to include('retries' => 2, 'error' => { 'class' => 'RuntimeError', 'message' => 'not yet 1' }, 'screenshot' => nil, 'snapshot' => nil)
-  end
-
   it 'appends a failure step with the error when no traced step was running' do
     recorder = started_recorder
     recorder.navigated('https://example.test/login')
@@ -278,20 +281,6 @@ describe 'Generated TraceHelper' do
       .to eq([['action', 'failed', { 'class' => 'RuntimeError', 'message' => 'Waited 10s for {id: "go"} to be visible' }]])
   end
 
-  it 'still gives the test error a step when the step that raised it was dropped by eventually' do
-    recorder = started_recorder
-    error = RuntimeError.new('not yet')
-    group = recorder.group_started(action: :eventually, source: source)
-    act(recorder, :click, 'refresh', status: :failed, error: error)
-    recorder.group_retried(group, error: error)
-    act(recorder, :click, 'refresh')
-    recorder.group_finished(group, status: :passed, retries: 1, error: nil)
-    steps = kept(recorder, failed_test.merge(error: error))['steps']
-
-    expect(steps.map { |step| step.values_at('kind', 'status') }).to eq([%w[group passed], %w[action passed]])
-    expect(steps.first['error']).to eq('class' => 'RuntimeError', 'message' => 'not yet')
-  end
-
   it 'appends a failure step when the step that raised the test error was dropped by max_steps' do
     allow(TraceHelper).to receive(:config).and_return(trace_config.merge('max_steps' => 2))
     recorder = started_recorder
@@ -317,6 +306,20 @@ describe 'Generated TraceHelper' do
     expect(TraceHelper.enabled?).to be(true)
   end
 
+  describe 'viewport' do
+    it 'is nil when the inner size cannot be read' do
+      viewport_script(nil)
+
+      expect(kept(started_recorder)['viewport']).to eq('width' => nil, 'height' => nil)
+    end
+
+    it 'is nil when the script raises' do
+      allow(driver).to receive(:execute_script).with(/innerWidth/).and_raise(Selenium::WebDriver::Error::WebDriverError, 'no page')
+
+      expect(kept(started_recorder)['viewport']).to eq('width' => nil, 'height' => nil)
+    end
+  end
+
   describe 'snapshots' do
     def sanitize(page, css: '', skipped: 0)
       TraceHelper::Snapshot.sanitize(page, css: css, skipped: skipped)
@@ -458,11 +461,10 @@ describe 'Generated TraceHelper' do
       element_script(field, secret: false)
       recorder = started_recorder
       act(recorder, :send_keys, 'user', args: ['admin', :enter], element: field)
-      act(recorder, :select_by, 'colour', args: [:text, 'Blue'], element: field)
       act(recorder, :click, 'go', element: field)
       steps = kept(recorder)['steps']
 
-      expect(steps.map { |step| step.values_at('value', 'secret') }).to eq([['admin{enter}', false], ['Blue', false], [nil, nil]])
+      expect(steps.map { |step| step.values_at('value', 'secret') }).to eq([['admin{enter}', false], [nil, nil]])
       expect(steps.last.keys).not_to include('value', 'secret')
     end
 
@@ -578,17 +580,25 @@ describe 'Generated TraceHelper' do
     expect(Dir.children(File.join(project_dir, 'tmp'))).to be_empty
   end
 
-  it 'makes the recorder the WaitHelper observer until cleanup, so no test inherits it' do
+  it 'makes the recorder the Raider observer until cleanup, so no test inherits it' do
     recorder = started_recorder
-    expect(WaitHelper.observer).to be(recorder)
+    expect(Raider.observer).to be(recorder)
 
     recorder.stop(keep: false, test: failed_test)
     recorder.cleanup
-    expect(WaitHelper.observer).to be_nil
+    expect(Raider.observer).to be_nil
   end
 
-  it 'records navigation and the failure without WaitHelper' do
-    hide_const('WaitHelper')
+  it 'leaves an observer that is not the recorder alone on release' do
+    other = Object.new
+    recorder = started_recorder
+    Raider.observer = other
+    TraceHelper.release(recorder)
+
+    expect(Raider.observer).to be(other)
+  end
+
+  it 'records navigation and the failure with no observer events' do
     recorder = started_recorder
     recorder.navigated('https://example.test/login')
     steps = kept(recorder, failed_test.merge(error: RuntimeError.new('boom')))['steps']
@@ -596,25 +606,50 @@ describe 'Generated TraceHelper' do
     expect(steps.map { |step| step['kind'] }).to eq(%w[navigate failure])
   end
 
+  it 'takes each step source from the first frame outside the runtime and the helpers' do
+    recorder = started_recorder
+    act(recorder, :click, 'go')
+    act(recorder, :send_keys, 'user', args: ['admin'])
+    sources = kept(recorder)['steps'].map { |step| step['source'] }
+
+    expect(sources).to all(include('file' => __FILE__))
+    expect(sources.first['line']).to be_a(Integer)
+  end
+
+  it 'gives the token nil, so the runtime sends no ready or finished, when not recording' do
+    recorder = TraceHelper.recorder_for(driver)
+
+    expect(recorder.action_started(action: :click, locator: { strategy: 'id', selector: 'go' }, within: [])).to be_nil
+  end
+
+  it 'records the actions the runtime emits as steps with their locator strategy' do
+    recorder = started_recorder
+    %w[click send_keys clear submit].each { |action| act(recorder, action, 'go', args: nil) }
+    steps = kept(recorder)['steps']
+
+    expect(steps.map { |step| step['action'] }).to eq(%w[click send_keys clear submit])
+    expect(TraceHelper::MEDIA_ACTIONS).to eq(%w[navigate click send_keys clear submit])
+  end
+
   context 'with TRACE=off' do
     let(:env) { { 'TRACE' => 'off' } }
 
-    it 'returns a NullRecorder and leaves WaitHelper.observer nil with TRACE=off or enabled: false' do
+    it 'returns a NullRecorder and leaves Raider.observer nil with TRACE=off or enabled: false' do
       recorder = TraceHelper.recorder_for(driver)
 
       expect(recorder).to be_a(TraceHelper::NullRecorder)
       expect(recorder.start).to be_nil
       expect(recorder.stop(keep: true, test: failed_test)).to be_nil
-      expect(WaitHelper.observer).to be_nil
+      expect(Raider.observer).to be_nil
     end
   end
 
   context 'with enabled: false' do
     let(:trace_config) { { 'enabled' => false } }
 
-    it 'returns a NullRecorder and leaves WaitHelper.observer nil with TRACE=off or enabled: false' do
+    it 'returns a NullRecorder and leaves Raider.observer nil with TRACE=off or enabled: false' do
       expect(TraceHelper.recorder_for(driver)).to be_a(TraceHelper::NullRecorder)
-      expect(WaitHelper.observer).to be_nil
+      expect(Raider.observer).to be_nil
     end
   end
 
@@ -681,18 +716,214 @@ describe 'Generated TraceHelper' do
     expect(warnings).to eq(["[trace] could not write the trace: No space left on device; tracing disabled for this run\n"])
     expect(TraceHelper.enabled?).to be(false)
     expect(TraceHelper.recorder_for(driver)).to be_a(TraceHelper::NullRecorder)
-    expect(WaitHelper.observer).to be_nil
+    expect(Raider.observer).to be_nil
+  end
+
+  describe 'a navigation in flight' do
+    let(:started_ms) { 1_793_568_600_020 }
+
+    def request_sent(id, url)
+      bidi.emit('network.beforeRequestSent', 'request' => { 'request' => id, 'method' => 'GET', 'url' => url },
+                                             'timestamp' => started_ms)
+    end
+
+    it 'credits requests made between navigating and navigated to the navigate step' do
+      recorder = started_recorder
+      recorder.navigating('https://example.test/start')
+      request_sent('r1', 'https://example.test/start')
+      recorder.navigated('https://example.test/')
+      act(recorder, :click, 'go')
+      request_sent('r2', 'https://example.test/api')
+      trace = kept(recorder)
+
+      expect(trace['steps'].map { |step| step.values_at('index', 'action', 'status') }).to eq([[1, 'navigate', 'passed'], [2, 'click', 'passed']])
+      expect(trace['network'].map { |entry| entry.values_at('step_index', 'url') })
+        .to eq([[1, 'https://example.test/start'], [2, 'https://example.test/api']])
+    end
+
+    it 'keeps the old path: navigated alone adds one finished navigate step' do
+      recorder = started_recorder
+      recorder.navigated('https://example.test/login')
+
+      expect(kept(recorder)['steps'].map { |step| step.values_at('kind', 'status') }).to eq([%w[navigate passed]])
+    end
+
+    it 'finishes a navigation that never completed as failed at the next navigating' do
+      recorder = started_recorder
+      recorder.navigating('https://example.test/down')
+      recorder.navigating('https://example.test/up')
+      recorder.navigated('https://example.test/up')
+      steps = kept(recorder)['steps']
+
+      expect(steps.map { |step| step.values_at('kind', 'status', 'url') })
+        .to eq([['navigate', 'failed', 'https://example.test/down'], ['navigate', 'passed', 'https://example.test/login']])
+    end
+
+    it 'finishes a navigation that never completed as failed at stop' do
+      recorder = started_recorder
+      recorder.navigating('https://example.test/down')
+      steps = kept(recorder)['steps']
+
+      expect(steps.map { |step| step.values_at('kind', 'status') }).to eq([%w[navigate failed]])
+    end
+
+    it 'finishes a navigation that never completed as failed when the next action is added, with only its own duration' do
+      clock = 100.0
+      allow(TraceHelper).to receive(:monotonic_now) { clock }
+      recorder = started_recorder
+      recorder.navigating('https://example.test/down')
+      clock += 0.25
+      act(recorder, :click, 'go')
+      clock += 60
+      steps = kept(recorder)['steps']
+
+      expect(steps.map { |step| step.values_at('action', 'status') }).to eq([%w[navigate failed], %w[click passed]])
+      expect(steps.first['duration_ms']).to eq(250)
+    end
+
+    it 'adds no second failure step for the error a pending navigation ends the test with' do
+      error = Selenium::WebDriver::Error::WebDriverError.new('net::ERR_CONNECTION_REFUSED')
+      recorder = started_recorder
+      recorder.navigating('https://example.test/down')
+      steps = kept(recorder, failed_test.merge(error: error))['steps']
+
+      expect(steps.map { |step| step.values_at('kind', 'status') }).to eq([%w[navigate failed]])
+      expect(steps.first['error']).to include('message' => a_string_including('ERR_CONNECTION_REFUSED'))
+    end
+
+    it 'adds no failure step for the error of the action that followed a pending navigation' do
+      error = RuntimeError.new('boom')
+      recorder = started_recorder
+      recorder.navigating('https://example.test/down')
+      act(recorder, :click, 'go', status: :failed, error: error)
+      steps = kept(recorder, failed_test.merge(error: error))['steps']
+
+      expect(steps.map { |step| step.values_at('kind', 'status') }).to eq([%w[navigate failed], %w[action failed]])
+    end
+
+    it 'keeps the page url a back or forward navigation started from when the driver does not give one' do
+      alert = { open: false }
+      stub_const('VideoHelper', Module.new { define_singleton_method(:alert_open?) { |_driver| alert[:open] } })
+      recorder = started_recorder
+      recorder.navigated('https://example.test/login')
+      alert[:open] = true
+      recorder.navigating(nil)
+      recorder.navigated(nil)
+      steps = kept(recorder)['steps']
+
+      expect(steps.map { |step| step['url'] }).to eq(['https://example.test/login', 'https://example.test/login'])
+    end
+
+    it 'is driven by the listener before each navigation, and the null recorder ignores it' do
+      listener = TraceHelper.listener
+      recorder = started_recorder
+      listener.before_navigate_to('https://example.test/a', driver)
+      listener.after_navigate_to('https://example.test/a', driver)
+      listener.before_navigate_back(driver)
+      listener.after_navigate_back(driver)
+      listener.before_navigate_forward(driver)
+      listener.after_navigate_forward(driver)
+
+      expect(kept(recorder)['steps'].map { |step| step['status'] }).to eq(%w[passed passed passed])
+      expect(TraceHelper::NullRecorder.new.navigating('https://example.test/')).to be_nil
+    end
+  end
+
+  describe 'mocked requests' do
+    let(:started_ms) { 1_793_568_600_020 }
+    let(:recorder) { started_recorder }
+    let(:network) { kept(recorder)['network'] }
+
+    before { recorder.navigated('https://example.test/login') }
+
+    def start(id, hop = 0)
+      recorder.network_started([id, hop], { method: 'GET', url: "https://example.test/#{id}", status: nil, duration_ms: nil }, at: started_ms)
+    end
+
+    def complete(id, status, hop = 0)
+      recorder.network_completed([id, hop], { status: status }, started_ms + 7)
+    end
+
+    it 'marks a pending entry and still completes it' do
+      start('r1')
+      recorder.network_marked(['r1', 0], { mocked: 'fulfilled' })
+      complete('r1', 200)
+
+      expect(network.map { |entry| entry.values_at('mocked', 'status', 'duration_ms') }).to eq([['fulfilled', 200, 7]])
+    end
+
+    it 'applies an early mark when the entry starts' do
+      recorder.network_marked(['r1', 0], { mocked: 'failed' })
+      start('r1')
+
+      expect(network.map { |entry| entry['mocked'] }).to eq(['failed'])
+      expect(recorder.instance_variable_get(:@early_marks)).to be_empty
+    end
+
+    it 'marks only its hop' do
+      start('r1', 0)
+      start('r1', 1)
+      recorder.network_marked(['r1', 1], { mocked: 'fulfilled' })
+
+      expect(network.map { |entry| entry['mocked'] }).to eq([nil, 'fulfilled'])
+    end
+
+    it 'caps early marks at MAX_PENDING' do
+      cap = TraceHelper::Recorder::MAX_PENDING
+      (cap + 5).times { |index| recorder.network_marked(["m#{index}", 0], { mocked: 'fulfilled' }) }
+      marks = recorder.instance_variable_get(:@early_marks)
+
+      expect(marks.size).to eq(cap)
+      expect(marks.keys.first).to eq(['m5', 0])
+    end
+
+    it 'keeps the status from the mark when no completion arrives' do
+      start('r1')
+      recorder.network_marked(['r1', 0], { mocked: 'fulfilled', status: 503 })
+
+      expect(network.map { |entry| entry.values_at('mocked', 'status') }).to eq([['fulfilled', 503]])
+    end
+
+    it 'keeps the mark status when the completion has none' do
+      start('r1')
+      recorder.network_marked(['r1', 0], { mocked: 'fulfilled', status: 503 })
+      complete('r1', nil)
+
+      expect(network.map { |entry| entry['status'] }).to eq([503])
+    end
+
+    it 'is fed by NetworkHelper.observer, registered when recorder_for runs' do
+      helper = Module.new { class << self; attr_accessor :observer; end }
+      stub_const('NetworkHelper', helper)
+      started = started_recorder
+      started.network_started(['r1', 0], { url: 'https://example.test/r1' })
+      helper.observer.request_mocked(request_id: 'r1', redirect_count: 0, outcome: 'failed', status: nil)
+
+      expect(helper.observer).to be(TraceHelper::MockMarks)
+      expect(kept(started)['network'].map { |entry| entry['mocked'] }).to eq(['failed'])
+    end
+
+    it 'does not raise when a mark cannot be applied' do
+      allow(TraceHelper).to receive(:active_recorder).and_raise(RuntimeError, 'boom')
+
+      expect { TraceHelper::MockMarks.request_mocked(request_id: 'r1', redirect_count: 0, outcome: 'failed') }.not_to raise_error
+    end
+
+    it 'is accepted by the format checker, which rejects other values' do
+      trace = { 'network' => [{ 'mocked' => 'maybe' }, { 'mocked' => 'fulfilled' }, {}] }
+      expect(TraceFormatChecker.mocked_rules(trace['network']).size).to eq(1)
+    end
   end
 
   describe 'browser wiring' do
     let(:started_ms) { 1_793_568_600_020 }
     let(:bidi_events) { %w[network.beforeRequestSent network.responseCompleted network.fetchError log.entryAdded] }
 
-    def request_sent(id, method, url, at)
-      bidi.emit('network.beforeRequestSent',
-                'request' => { 'request' => id, 'method' => method, 'url' => url,
-                               'headers' => [{ 'name' => 'Cookie', 'value' => { 'type' => 'string', 'value' => 'session=hush' } }] },
-                'timestamp' => at)
+    def request_sent(id, method, url, at, hop: 0)
+      bidi.emit('network.beforeRequestSent', 'redirectCount' => hop,
+                                             'request' => { 'request' => id, 'method' => method, 'url' => url,
+                                                            'headers' => [{ 'name' => 'Cookie', 'value' => { 'type' => 'string', 'value' => 'session=hush' } }] },
+                                             'timestamp' => at)
     end
 
     it 'subscribes passively to the four BiDi events and never adds a request handler' do
@@ -780,6 +1011,151 @@ describe 'Generated TraceHelper' do
       )
     end
 
+    # A redirect keeps the request id; each hop has its own redirectCount. Chrome starts hop 1 in the same
+    # millisecond hop 0 completes, so the two events can arrive in either order.
+    it 'keeps each hop of a redirect as its own entry with its own status and duration' do
+      recorder = started_recorder
+      recorder.navigated('https://example.test/start')
+      request_sent('r1', 'GET', 'https://example.test/start', started_ms)
+      request_sent('r1', 'GET', 'https://example.test/', started_ms + 1, hop: 1)
+      bidi.emit('network.responseCompleted', 'redirectCount' => 0, 'timestamp' => started_ms + 1,
+                                             'request' => { 'request' => 'r1' }, 'response' => { 'status' => 302 })
+      bidi.emit('network.responseCompleted', 'redirectCount' => 1, 'timestamp' => started_ms + 206,
+                                             'request' => { 'request' => 'r1' }, 'response' => { 'status' => 200 })
+
+      expect(kept(recorder)['network'].map { |entry| entry.values_at('url', 'status', 'duration_ms') }).to eq(
+        [['https://example.test/start', 302, 1], ['https://example.test/', 200, 205]]
+      )
+    end
+
+    it 'drops one malformed BiDi event, warns once and keeps tracing' do
+      recorder = started_recorder
+      bidi.emit('network.beforeRequestSent', 'request' => 'string', 'timestamp' => started_ms)
+      bidi.emit('network.responseCompleted', 'request' => { 'request' => 'bad', 'timings' => 'string' },
+                                             'response' => 'string', 'timestamp' => started_ms)
+      bidi.emit('log.entryAdded', 'level' => 'info', 'text' => 'bad', 'timestamp' => started_ms, 'stackTrace' => 'string')
+      request_sent('r1', 'GET', 'https://example.test/ok', started_ms)
+      bidi.emit('network.responseCompleted', 'request' => { 'request' => 'r1' }, 'timestamp' => started_ms + 5,
+                                             'response' => { 'status' => 200 })
+      bidi.emit('log.entryAdded', 'level' => 'info', 'text' => 'good', 'timestamp' => started_ms)
+      trace = kept(recorder)
+
+      expect(trace['network'].map { |entry| [entry['url'], entry['status']] }).to include(['https://example.test/ok', 200])
+      expect(trace['console'].map { |entry| entry['text'] }).to include('good')
+      expect(TraceHelper.enabled?).to be(true)
+      expect(warnings.size).to eq(1)
+      expect(warnings.first).to match(/dropped a malformed BiDi .* event/)
+    end
+
+    describe 'hardening against hostile event content' do
+      it 'keeps tracing and records no duration for a timing or timestamp that is not finite' do
+        recorder = started_recorder
+        recorder.navigated('https://example.test/login')
+        request_sent('r1', 'GET', 'https://example.test/a', started_ms)
+        bidi.emit('network.responseCompleted', 'request' => { 'request' => 'r1' }, 'timestamp' => Float::INFINITY,
+                                               'response' => { 'status' => 200 })
+        request_sent('r2', 'GET', 'https://example.test/b', Float::INFINITY)
+        bidi.emit('network.responseCompleted', 'request' => { 'request' => 'r2', 'timings' => { 'timeOrigin' => Float::INFINITY, 'responseEnd' => 5 } },
+                                               'timestamp' => started_ms, 'response' => { 'status' => 200 })
+        bidi.emit('log.entryAdded', 'level' => 'info', 'text' => 'inf', 'timestamp' => Float::INFINITY)
+        trace = kept(recorder)
+
+        expect(TraceHelper.enabled?).to be(true)
+        expect(trace['network'].map { |entry| entry.values_at('url', 'status', 'duration_ms') })
+          .to eq([['https://example.test/a', 200, nil], ['https://example.test/b', 200, nil]])
+        expect(trace['console'].map { |entry| entry['text'] }).to eq(['inf'])
+      end
+
+      it 'drops, and records nothing for, an event whose request is not an object with a string id' do
+        recorder = started_recorder
+        recorder.navigated('https://example.test/login')
+        bidi.emit('network.beforeRequestSent', 'request' => 'string', 'timestamp' => started_ms)
+        bidi.emit('network.beforeRequestSent', 'request' => { 'request' => 123, 'url' => 'https://example.test/x' }, 'timestamp' => started_ms)
+        bidi.emit('network.responseCompleted', 'request' => 'string', 'timestamp' => started_ms, 'response' => { 'status' => 200 })
+        bidi.emit('network.responseCompleted', 'request' => { 'request' => 123 }, 'timestamp' => started_ms, 'response' => { 'status' => 200 })
+        bidi.emit('network.fetchError', 'request' => 'string', 'errorText' => 'x', 'timestamp' => started_ms)
+        bidi.emit('network.fetchError', 'request' => { 'request' => 123 }, 'errorText' => 'x', 'timestamp' => started_ms)
+        pending = recorder.instance_variable_get(:@requests).size + recorder.instance_variable_get(:@early).size
+
+        expect(pending).to eq(0)
+        expect(kept(recorder)['network']).to eq([])
+        expect(TraceHelper.enabled?).to be(true)
+        expect(warnings.size).to eq(1)
+      end
+
+      it 'treats a redirectCount that is not an Integer as 0' do
+        recorder = started_recorder
+        recorder.navigated('https://example.test/login')
+        request_sent('r1', 'GET', 'https://example.test/a', started_ms, hop: '7')
+        bidi.emit('network.responseCompleted', 'redirectCount' => 0, 'request' => { 'request' => 'r1' }, 'timestamp' => started_ms + 4,
+                                               'response' => { 'status' => 200 })
+
+        expect(kept(recorder)['network'].map { |entry| entry.values_at('status', 'duration_ms') }).to eq([[200, 4]])
+      end
+
+      it 'keeps only scalar values for network and console fields' do
+        recorder = started_recorder
+        recorder.navigated('https://example.test/login')
+        bidi.emit('network.beforeRequestSent', 'request' => { 'request' => 'r1', 'method' => ['GET'], 'url' => { 'nested' => 'x' } },
+                                               'timestamp' => started_ms)
+        bidi.emit('network.responseCompleted', 'request' => { 'request' => 'r1' }, 'timestamp' => started_ms + 1,
+                                               'response' => { 'status' => { 'a' => 1 }, 'mimeType' => ['x'], 'bytesReceived' => { 'b' => 2 } })
+        bidi.emit('network.beforeRequestSent', 'request' => { 'request' => 'r3', 'method' => 'GET', 'url' => 'https://example.test/n' },
+                                               'timestamp' => started_ms)
+        bidi.emit('network.responseCompleted', 'request' => { 'request' => 'r3' }, 'timestamp' => started_ms + 1,
+                                               'response' => { 'status' => 200, 'bytesReceived' => Float::INFINITY })
+        bidi.emit('network.beforeRequestSent', 'request' => { 'request' => 'r2', 'method' => 'GET', 'url' => 'https://example.test/e' },
+                                               'timestamp' => started_ms)
+        bidi.emit('network.fetchError', 'request' => { 'request' => 'r2' }, 'errorText' => { 'deep' => 'x' }, 'timestamp' => started_ms + 1)
+        bidi.emit('log.entryAdded', 'level' => { 'a' => 1 }, 'text' => %w[a b], 'timestamp' => started_ms)
+        trace = kept(recorder)
+
+        expect(trace['network'].map { |entry| entry.values_at('method', 'url', 'status', 'mime_type', 'bytes', 'error') })
+          .to eq([[nil, nil, nil, nil, nil, nil], ['GET', 'https://example.test/n', 200, nil, nil, nil],
+                  ['GET', 'https://example.test/e', nil, nil, nil, nil]])
+        expect(trace['console'].map { |entry| entry.values_at('level', 'text') }).to eq([[nil, nil]])
+      end
+
+      it 'caps the pending requests and the early completions, dropping the oldest' do
+        recorder = started_recorder
+        cap = TraceHelper::Recorder::MAX_PENDING
+        (cap + 5).times do |index|
+          recorder.network_started("s#{index}", { url: "https://example.test/#{index}" })
+          recorder.network_completed("e#{index}", { status: 200 })
+        end
+        requests = recorder.instance_variable_get(:@requests)
+        early = recorder.instance_variable_get(:@early)
+
+        expect([requests.size, early.size]).to eq([cap, cap])
+        expect(requests.keys.first).to eq('s5')
+        expect(early.keys.first).to eq('e5')
+        expect(TraceHelper.enabled?).to be(true)
+      end
+
+      it 'warns about a dropped event even after another notice, and the notice is not hidden by it' do
+        TraceHelper.warn_once('something left out')
+        recorder = started_recorder
+        bidi.emit('network.beforeRequestSent', 'request' => 'string', 'timestamp' => started_ms)
+        bidi.emit('network.beforeRequestSent', 'request' => 'string', 'timestamp' => started_ms)
+        TraceHelper.warn_once('another')
+
+        expect(warnings.size).to eq(2)
+        expect(warnings.first).to eq("[trace] something left out\n")
+        expect(warnings.last).to match(/dropped a malformed BiDi network.beforeRequestSent event/)
+        expect(recorder).not_to be_nil
+        expect(TraceHelper.enabled?).to be(true)
+      end
+
+      it 'warns once about a dropped event before any other notice, leaving that notice free' do
+        started_recorder
+        bidi.emit('log.entryAdded', 'level' => 'info', 'text' => 'x', 'timestamp' => 1, 'stackTrace' => 'string')
+        TraceHelper.warn_once('something left out')
+
+        expect(warnings.size).to eq(2)
+        expect(warnings.last).to eq("[trace] something left out\n")
+      end
+    end
+
     it 'records capabilities network/console false and warns once when subscribe raises' do
       bidi.failure = Selenium::WebDriver::Error::WebDriverError.new('no such frame')
       traces = Array.new(2) do
@@ -846,6 +1222,14 @@ describe 'Generated TraceHelper' do
         .to eq([true, true, true, true, false, false])
     end
 
+    context 'with BIDI=off' do
+      let(:env) { { 'BIDI' => 'off' } }
+
+      it 'is false for every browser' do
+        expect(TraceHelper.bidi?('chrome')).to be(false)
+      end
+    end
+
     context 'with TRACE=off' do
       let(:env) { { 'TRACE' => 'off' } }
 
@@ -872,7 +1256,7 @@ describe 'Generated TraceHelper' do
 
     def load_driver_helper
       generator = HelpersGenerator.new(%w[selenium rspec proj])
-      %w[driver_helper video_helper].each do |name|
+      %w[driver_helper video_helper network_helper screenshot_helper].each do |name|
         source = File.read(File.expand_path("../../lib/generators/templates/helpers/#{name}.tt", __dir__))
         File.write(File.join(project_dir, "#{name}.rb"), ERB.new(source, trim_mode: '-').result(generator.instance_eval { binding }))
       end
@@ -906,7 +1290,7 @@ describe 'Generated TraceHelper' do
     before { load_driver_helper }
 
     after do
-      %i[DriverHelper VideoHelper].each { |name| Object.send(:remove_const, name) if Object.const_defined?(name) }
+      %i[DriverHelper VideoHelper NetworkHelper].each { |name| Object.send(:remove_const, name) if Object.const_defined?(name) }
       $LOADED_FEATURES.delete(trace_feature)
     end
 
@@ -925,8 +1309,8 @@ describe 'Generated TraceHelper' do
         .to eq([['navigate', 'https://example.test/login'], ['navigate', 'https://example.test/login']])
     end
 
-    context 'with VIDEO=off and TRACE=off' do
-      let(:env) { { 'VIDEO' => 'off', 'TRACE' => 'off' } }
+    context 'with VIDEO=off, TRACE=off and BIDI=off' do
+      let(:env) { { 'VIDEO' => 'off', 'TRACE' => 'off', 'BIDI' => 'off' } }
 
       it 'passes no listener at all' do
         expect(created_arguments.keys).to eq([:options])
@@ -937,9 +1321,17 @@ describe 'Generated TraceHelper' do
       end
     end
 
-    it 'sets web_socket_url only for chrome, edge and firefox and not with TRACE=off' do
+    it 'sets web_socket_url only for chrome, edge and firefox' do
       expect(%w[chrome edge firefox safari].map { |browser| options_for(browser).web_socket_url }).to eq([true, true, true, nil])
     end
+
+    context 'with TRACE=off' do
+      let(:env) { { 'TRACE' => 'off' } }
+
+      it 'still sets web_socket_url for the network mocks' do
+        expect(options_for('chrome').web_socket_url).to be(true)
+      end
+    end
   end
 end
 # rubocop:enable RSpec/MultipleMemoizedHelpers, RSpec/VerifiedDoubles, RSpec/ExpectOutput, RSpec/MultipleExpectations, RSpec/ExampleLength