rubycdp/ferrum
61.2
Adequate · 6 November 2026
12.2k
lines of production code
Ruby
with Go
4
measurements over time
What this system is
Features
Added binstubs and browser helper to console script
Bundler-generated binstubs for rake and rspec have been added to the bin directory to facilitate running these tools. Additionally, the bin/console script now includes a browser helper function that initializes a Ferrum browser instance, allowing users to easily interact with a browser within the IRB console environment.
bin · high confidence
New Frame DOM and Runtime modules for JavaScript evaluation and node manipulation
This change introduces the \Ferrum::Frame::DOM\ and \Ferrum::Frame::Runtime\ modules, which provide the core capabilities for interacting with a frame's content. Users can now evaluate JavaScript expressions via \evaluate\, \execute\, and \evaluate\_async\, and manipulate the DOM by querying nodes with CSS or XPath selectors (\xpath\, \at\_xpath\, etc.), retrieving page metadata (\current\_url\, \doctype\, \body\), and injecting scripts or styles. The runtime layer handles the conversion between Ruby and JavaScript values, including specific handling for cyclic objects and execution context errors.
lib/ferrum/frame · high confidence
New browser contexts, accessibility API, and dedicated input classes
Ferrum now supports browser contexts (isolated profiles similar to incognito windows) via the new \Context\ and \Contexts\ classes, allowing users to create, manage, and dispose of separate browsing sessions with independent cookies and storage. A new \Accessibility\ API (\Ferrum::Page\#accessibility\) exposes the CDP Accessibility domain, enabling queries for the full or partial accessibility tree, node lookup by role or name, and live AX event subscriptions. Additionally, keyboard and mouse interactions are now handled by dedicated \Ferrum::Keyboard\ and \Ferrum::Mouse\ classes, providing more granular control over key presses, typing sequences, mouse movements, and clicks.
lib/ferrum · high confidence
New console message API and restructured browser logging
Users now have access to a structured Console API that captures browser console output, uncaught exceptions, and network/security log entries as typed \Ferrum::Console::Message\ objects. These messages expose detailed metadata including severity, source, timestamp, arguments, and stack trace locations, allowing for programmatic inspection and filtering of page activity. Additionally, the internal browser log formatting has been refactored into distinct strategies (Default, Annotated, and JSON), enabling users to choose output formats suitable for debugging or tooling integration via the \FERRUM\_LOG\_FORMAT\ environment variable.
lib/ferrum/console, lib/ferrum/log · high confidence
New utility modules for retries, timing, platform detection, and thread safety
Ferrum introduces four new utility modules in lib/ferrum/utils to improve reliability and cross-platform support. The new Attempt module provides a retry-with-backoff helper for re-running blocks on specific exceptions. ElapsedTime offers monotonic-clock-based timeout and elapsed-time tracking. Platform adds detection helpers for macOS (including Apple Silicon), Windows, Linux, and MRI Ruby. Thread introduces a spawn helper that allows controlling whether unhandled exceptions in Ferrum's background threads abort the host process, addressing stability issues where Ferrum's threads could take down the main application.
lib/ferrum/utils · high confidence
Behavioural changes
2 commits (0 fixes) modifying sig/concurrent
A change to existing behaviour in sig/concurrent — 2 commits, 3 files: “Add RBS types (\#565)”; “chore(sig): drop stale Browser::Client signatures” (refs \#565).
sig/concurrent · medium confidence · unverified
28 commits (6 fixes) modifying lib/ferrum/browser/options
A change to existing behaviour in lib/ferrum/browser/options — 28 commits (6 fixs), 1 file: “Support for headless=new (\#379)”; “fix: build and linters”; “feat: respect \:host\ option when spawning Chrome”; and 25 more (refs \#379, \#610, \#555, \#620, \#564, …).
lib/ferrum/browser/options · medium confidence · unverified
5 commits (1 fix) modifying docker
A change to existing behaviour in docker — 5 commits (1 fix), 20 files: “fix(docker): retry snapshot.debian.org downloads for about 2.5 minutes in the chromium backfill”; “feat: console messages API, a reworked logger and browser output kept after startup (\#658)”; “ref(browser): read browser details over CDP and ask /json/version only for url: (\#651)”; and 2 more (refs \#658, \#651, \#645).
docker · medium confidence · unverified
64 commits (29 fixes) modifying sig/ferrum
A change to existing behaviour in sig/ferrum — 64 commits (29 fixs), 69 files: “fix(client): give up on a websocket write the browser doesn't take (\#644)”; “fix: run extensions before page scripts in popups and out-of-process iframes (\#663)”; “fix: \[\#583\] Don't raise timeout on lazy iframes (\#597)”; and 61 more (refs \#644, \#663, \#583, \#597, \#565, …).
sig/ferrum · medium confidence · unverified
Major architectural rewrite: new context/page model and CDP client
Ferrum has been rewritten to use a modern Chrome DevTools Protocol (CDP) architecture, replacing the previous single-page model with support for multiple browser contexts (incognito profiles) and pages. The library now introduces a dedicated \Client\ and \SessionClient\ for managing WebSocket connections and command routing, a new \Cookie\ class with full attribute access, and a \Utils::Event\ for tracking event iterations. Users can now create pages in new contexts, access workers and service workers, and benefit from improved error handling with specific exceptions like \NoSuchPageError\ and \TimeoutError\ that name the timed-out command.
ferrum · high confidence
Major page API restructuring with new capabilities
The page module has been refactored into distinct components, introducing new capabilities for CSS animation playback control, live page screencasting, and performance tracing, while also adding support for WebP screenshots, MHTML snapshots, and streaming PDF generation to improve memory efficiency. This change replaces the previous monolithic page implementation with specialized modules for frames, screenshots, and input, and removes the legacy DOM, Frame, Input, Net, and Runtime modules.
lib/ferrum/page · high confidence
Refactored browser launch and process management
The browser launch logic has been restructured to improve reliability and configuration handling. A new \Binary\ module replaces the previous \Cliver\ dependency to locate browser executables on the system PATH. Browser command-line arguments are now constructed by a dedicated \Command\ class that merges default flags with user options, and an \Options\ class centralizes configuration resolution. The \Process\ class has been updated to use these new components, supporting explicit \ws\_url\ connections and improved process lifecycle management, including better cleanup of temporary user data directories.
lib/ferrum/browser · high confidence
Removes global thread exception handling and adds concurrency utilities
The library no longer globally sets \Thread.abort\_on\_exception\ and \Thread.report\_on\_exception\, preventing Ferrum from altering the global Ruby thread behavior which could affect other parts of an application. Instead, it introduces a \concurrent-ruby\ dependency and new utility modules (\ferrum/utils/thread\, \ferrum/utils/event\, etc.) to manage concurrency and error reporting more locally and safely within the library itself.
lib · high confidence
Rewritten network request and response handling with interception support
The network layer has been refactored to provide a more robust and feature-rich API for inspecting and controlling HTTP traffic. A new \Exchange\ class now pairs requests with their responses, errors, and interception status, exposing methods like \navigation\_request?\, \blocked?\, \redirect?\, and \ping?\ to help users understand the lifecycle of each request. Request interception is now fully supported via the \InterceptedRequest\ class, allowing users to fulfill requests with fake responses, continue them with overrides, or abort them before they reach the network. Authentication challenges are handled through a dedicated \AuthRequest\ class, enabling users to provide credentials or cancel auth prompts. The \Request\ and \Response\ classes have been expanded with additional attributes such as \type\, \frame\_id\, \loader\_id\, \content\_type\, and \to\_h\, while the \Response\#body\ method now safely returns \nil\ instead of raising an error if the body is unavailable.
lib/ferrum/network · high confidence
Stability fixes and improved process cleanup
This release addresses several critical stability issues: Ferrum's background threads no longer crash the host process on errors, in-flight commands are released immediately when the browser dies, and raising event callbacks no longer kill the event dispatch thread. Process termination and user-data-directory cleanup have been improved to prevent hanging and resource leaks. Additionally, the \:host\ option is now correctly respected when spawning Chrome, and the cyclic reference check in \\#evaluate\ has been optimized to reduce CDP round trips.
(repo-wide) · high confidence
Fixes
Improved stability for WebSocket connections and event subscriptions
The client now handles malformed or deeply nested JSON responses gracefully by dropping them instead of crashing the reader thread, and ensures that a failing event callback does not terminate the entire dispatch process. Additionally, the WebSocket connection is now forcibly closed if the browser dies unexpectedly, preventing file descriptor leaks during browser restarts.
lib/ferrum/client · high confidence
Robust browser process termination and user data cleanup
A new \Killer\ module handles OS-level process termination and user-data-directory removal, ensuring the browser process is killed before its data directory is deleted to prevent file locks from blocking cleanup. The implementation escalates from TERM to KILL signals if the process does not exit within a timeout, handles process groups to avoid orphaning child processes, and uses bounded polling instead of blocking waits to prevent deadlocks during garbage collection finalization. Directory removal is retried with exponential backoff to handle transient file locks, and the logic is structured as free functions to avoid reference cycles that would prevent the finalizer from running.
lib/ferrum/browser/process · high confidence
Test coverage
1 commit adding/updating tests in spec/accessibility, spec/unit/browser; 18 commits adding/updating tests in spec/frame; 3 commits adding/updating tests in spec/unit/client; 3 commits adding/updating tests in spec/unit/frame; Added comprehensive test coverage for network request and response objects; Added test coverage for Ferrum::Cookies::Cookie; Added test coverage for core browser automation features; Added test coverage for page animation, screencast, screenshot, stream, and tracing features; Added test support infrastructure and updated test server configuration; Added tests for Chrome browser options and version detection; Added tests for browser binary resolution, protocol timeout options, and version info parsing; Added unit tests for thread safety, timeout handling, and process management; Updated test fixtures for accessibility, animations, and iframe scenarios.
Dependencies
Update runtime dependencies and raise minimum Ruby version
The gem now requires Ruby 3.1 or higher, dropping support for older versions. Runtime dependencies have been updated to include base64 (\~\> 0.2) and concurrent-ruby (\~\> 1.1), while addressable has been relaxed to \~\> 2.5. Development dependencies such as rubocop, sinatra, and puma have been moved to the Gemfile with updated version constraints, and the project homepage and metadata have been updated to reflect the rubycdp organization.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
This is the PUBLIC form of this artifact. Findings are listed in full, but the details of SECURITY findings — which rule fired, in which file, on which line, and how to fix it — are deliberately withheld, and any secret-scanner results are excluded entirely. Where detail is absent here it was REMOVED FOR PUBLICATION; it is not missing from the analysis. The complete artifact is available from the repository owner.
Score
- CAI 55 → 61 (+6.2)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 65 → 65 (+0.1)
- Architecture 92 → 90 (-1.9)
- Maturity 40 → 64 (+23.6)
- Readiness 65 → 55 (-9.4)
- Security 75 → 65 (-10.1)
Resolved (18)
- Documentation: no project overview (README.md)
- FixmeComment (lib/ferrum/frame/runtime.rb)
- FixmeComment (lib/ferrum/node.rb)
- High IaC: DS-0029 (docker/Dockerfile)
- High IaC: DS-0029 (docker/Dockerfile)
- High: security finding (details withheld)
- Inconsistent naming for blocking vs non-blocking or parameterized vs default operations. The '!' suffix usually implies a dangerous or side-effect-heavy operation in Ruby, but here it appears to be a no-argument convenience method for the same logical operation as the parameterized version. This is inconsistent with the explicit parameter version.
- Inconsistent use of '!' suffix. In Ruby, '!' often denotes a mutating or dangerous method, but here it seems to indicate a method that raises an error if the execution context is not ready, whereas the non-'!' version might return nil or handle it gracefully. This is a subtle but significant inconsistency in error handling semantics.
- Low IaC: DS-0010 (.devcontainer/Dockerfile)
- Low IaC: DS-0017 (.devcontainer/base.Dockerfile)
- Low IaC: DS-0029 (.devcontainer/Dockerfile)
- Low IaC: WD-DOCKER-0003 (.devcontainer/Dockerfile)
- Low IaC: WD-DOCKER-0003 (.devcontainer/base.Dockerfile)
- Low IaC: WD-DOCKER-0014 (.devcontainer/Dockerfile)
- Low cohesion: Frame (LCOM4 8) (lib/ferrum/frame.rb)
- Off-boarding risk: anonymized user #1
- Redundant methods for retrieving all cookies. each() is an iterator, while all() likely returns an array. While distinct, having both without clear distinction in documentation or naming convention (e.g., all_cookies() vs each_cookie()) can be confusing. More importantly, Cookies. retrieves a single cookie, but there is no Cookies.find(name) or similar, making the API inconsistent in how single items are retrieved.
- Semantic ambiguity in 'restart'. Browser.restart() likely resets the browser state (clears cookies, caches, etc.) and reuses the process, whereas Process.restart() likely kills the existing process and spawns a new one. Using the same name for distinct lifecycle operations (state reset vs. process lifecycle) is confusing.
New (12)
- Duplicated block (6 lines × 2) (lib/ferrum/network/auth_request.rb)
- High IaC: DS-0029 (docker/Dockerfile)
- High IaC: DS-0029 (docker/Dockerfile)
- High: security finding (details withheld)
- High: security finding (details withheld)
- High: security finding (details withheld)
- Low cohesion: Frame (LCOM4 10) (lib/ferrum/frame.rb)
- Low cohesion: Options (LCOM4 4) (lib/ferrum/browser/options.rb)
- Medium: security finding (details withheld)
- Off-boarding risk: anonymized user #1
- Repeated repair: lib/ferrum/context.rb (lib/ferrum/context.rb)
- Workflow holding a long-lived secret is unscoped (.github/workflows/docs.yml)
Changes since last survey
- 59 commits — 37 feature/other, 22 fixes
By area
- lib/ferrum — 22 commits
- (root) — 19 commits
- .github/workflows — 3 commits
- docs/18-node.md — 2 commits
- spec/browser_spec.rb — 2 commits
- spec/network — 2 commits
- .devcontainer/Dockerfile — 1 commit
- docker/Dockerfile — 1 commit
- docs/7-network.md — 1 commit
- lib/ferrum.rb — 1 commit
- sig/ferrum — 1 commit
- spec/contexts_spec.rb — 1 commit
- spec/node_spec.rb — 1 commit
- spec/support — 1 commit
- spec/unit — 1 commit
Notable commits
- fix: fix(client): write websocket frames from a writer thread, fixing the JRuby deadlock (#680)
- fix: fix(context): reuse the session of an attached target in attach_target (#668)
- fix: fix(context): skip workers without a session and raise a clear error from Target#worker (#669)
- fix: fix(contexts): detach nested service worker sessions so Chrome can stop them (#666)
- fix: fix(docker): retry snapshot.debian.org downloads for about 2.5 minutes in the chromium backfill
- fix: fix(headers): clear the headers and the user agent they set in Chrome right away
- fix: fix(headers): leave the user agent override alone unless given one
- fix: fix(log): serialize writes to an IO logger so lines from several threads don't mix on JRuby (#683)
- fix: fix(mouse): scroll instantly regardless of scroll-behavior
- fix: fix(network): remove the user agent override once every emulate option is nil
- fix: fix(node): give focus back after focusable? checks the node
- fix: fix(node): give moving? a delay long enough to see slow movement
- fix: fix(node): read moving?'s default delay from FERRUM_NODE_MOVING_CHECK
- fix: fix(node): return true from focusable? when focus can't go back to the previous element
- fix: fix(node): return true from moving? when the node is moving
- fix: fix(node): search within the node's own frame
- fix: fix(page): return the byte count from pdf(path:) like screenshot and mhtml
- fix: fix(page): wake navigation when a loading frame detaches (#672)
- fix: fix(runtime): keep a node first seen inside a Map or Set when it is referenced again (#693)
- fix: fix(runtime): raise JavaScriptError for any thrown value, not only Error instances (#675)
- …and 39 more
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
rubycdp/ferrum was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 6543f618f03eadbcbccd8146758612add46f00bd — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.2+preprod-5c4e66d9318b.