Browser.setDownloadBehavior fails with “Failed to find browser context …” when using flatten: true (Target.setAutoAttach)

[Iwark]

Describe the bug

When running Ferrum with flatten mode enabled (Target.setAutoAttach flatten: true), calling Browser.setDownloadBehavior with browserContextId fails with:

"Failed to find browser context for id <context_id>".

Switching to flatten: false makes the issue disappear.

To Reproduce

• Environment (Docker-based):

  • Headless Chrome runs in a sidecar container
  • Capybara.save_path is set, which Cuprite passes to Ferrum; Ferrum then attempts to configure download behavior on page initialization

• Minimal setup:

# spec/system/support/cuprite_setup.rb
require "capybara/cuprite"

Capybara.save_path = File.expand_path("./tmp/capybara", __dir__)

Capybara.register_driver(:cuprite_flatten_true) do |app|
  Capybara::Cuprite::Driver.new(app, {
    flatten: true,
    window_size: [1200, 800],
  })
end

Capybara.default_driver = Capybara.javascript_driver = :cuprite_flatten_true

# spec/system/minimal_spec.rb
require "rails_helper"

RSpec.describe "Minimal", type: :system do
  it "visits root" do
    visit "/"
    expect(page).to have_content("Welcome")
  end
end

• Failing behavior:
  • During initial page setup, Ferrum executes:
    • Browser.setDownloadBehavior(browserContextId: <context_id>, downloadPath: <path>, behavior: allow, eventsEnabled: true)
  • Chrome DevTools Protocol responds:
    • Failed to find browser context for id <context_id>
  • Subsequent Target.disposeBrowserContext may also fail similarly.

Expected behavior

Browser.setDownloadBehavior should succeed in flatten mode when provided a valid browserContextId, or Ferrum should use an alternative approach that is compatible with flattened sessions.

Screenshots

N/A

Desktop (please complete the following information):

• OS: macOS (host) + Dockerized Linux for app/chrome
• Browser: HeadlessChrome/119.0.6045.9
• Version:
  • Ferrum: 0.17.1
  • Cuprite: 0.17
  • Capybara: 3.40.0
  • Ruby: ruby 3.4.5 (2025-07-16) +PRISM [aarch64-linux]
  • Rails: 8.0.2.1

Additional context

• Cuprite sets options[:save_path] from Capybara.save_path, which triggers Ferrum to call downloads behavior during page preparation:
  • ferrum/lib/ferrum/page.rb: downloads.set_behavior(save_path: @options.save_path)
• In flatten mode the call above fails with “Failed to find browser context…”.
• Workarounds tested:
  • Set flatten: false → issue disappears, no patches required.
  • Test-only monkey patch to no-op Ferrum::Downloads#set_behavior → avoids the error but disables download behavior.

Questions:

• Is Browser.setDownloadBehavior expected to work with browserContextId under flatten: true?
• If not supported, should Ferrum skip/alter this call in flatten mode, or is there a recommended CDP alternative compatible with flattened sessions?