capybara-lightpanda 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c46e211cf39dfb4b533c59ec88106fd9d4c72d59ed8ef11d99af0d9488885f9e
-  data.tar.gz: 00f22e0a391ccc5c015291d72fa2d53f1d10062c0413f1fb62298a13a7006307
+  metadata.gz: 42246ea44b80c592e6779cf2aa95890c7635fb057b0061064b63bf15004dcde6
+  data.tar.gz: 63131038538438b32d39d8e46a36005df0306e8daadaa38ff88540874c6c46aa
 SHA512:
-  metadata.gz: e3d08ffeb41acac97492d9c1cdf0aaca8499487b38afa6f1b8a1598f5c060cead1f0b4d5572f23ffeee0a49afc555f790a6e358c88816e143494619bd1f88128
-  data.tar.gz: 7a2bfcafc663cba5614bd4385db9957f68d58255f6cfe4ee4a3090a447a5302f2a09db6dc2bcea9ce56795cb2e8739d1f440143e0c8da4d393e7078d76d9b229
+  metadata.gz: 1728491bdd3d3dac24559cc663ee250af16f90d7944d2c27be0b879ddbfc23a2a00181f39970d7622fd1b640449d97c7d373c4f6a414aae9073dc0f3cf92d1f8
+  data.tar.gz: 47e0408c55b5150347656d8136b6dc993b39d38a051a39efec480e2d913cf799f45c18242fd031bbb6962f79b7a39d63cc2eec8d2c14e2f42f34ed3b029af867

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.2.1] - 2026-05-05
+
+### Fixed
+
+- Turbo Frame links now correctly swap the frame instead of falling through to a full-page navigation. Affects any test that clicks a link or submits a form inside a `<turbo-frame>`.
+- Internal driver errors (`NoMethodError`, `NameError`, `Errno::*`) inside `extract_node_object_ids` and `page_ready?` are no longer swallowed and silently downgraded to `[]` / `false` — they surface as real exceptions so bugs are visible.
+
+### Internal
+
+- Local test suite migrated from RSpec to Minitest::Spec. The Capybara shared-spec battery (`spec/features/session_spec.rb`) still runs on RSpec.
+
+## [0.2.0] - 2026-05-04
+
+Reliability and feature polish as Lightpanda matured. **Update Lightpanda before upgrading**: this release requires a current nightly (the gem will tell you if yours is too old).
+
+### Added
+
+- `Driver#wait_for_network_idle(timeout:, connections:)` — wait until in-flight HTTP requests drop to a threshold. Useful for SPAs and pages with deferred XHR.
+- `handshake_timeout` driver option — cap how long the gem waits for the browser process to come up, separate from per-command timeouts.
+- `Cookies` is now `Enumerable` — `cookies.find`, `cookies.select`, etc. work directly.
+- `set_cookie` now infers the domain from the current URL (or `Capybara.app_host`) when you don't pass one.
+
+### Changed
+
+- `accept_modal(:confirm)` and `accept_modal(:prompt)` now actually drive the JS return value. Previously they only captured the dialog message; the page-side `confirm()` / `prompt()` always saw the dismiss outcome.
+- `prompt` dialogs now respect the `defaultText` argument when you call `accept_modal(:prompt)` without `with:`.
+- Form interactions are noticeably more reliable on Turbo Drive pages, redirects, and JS-heavy SPAs — many subtle navigation/form-submit edge cases are now handled natively.
+- All transient CDP errors inherit from `BrowserError`. A single `rescue Capybara::Lightpanda::BrowserError` catches the lot.
+
+### Fixed
+
+- Capybara's `node #send_keys should generate key events`, `#has_field with valid`, `#fill_in` with range/date/time inputs, `#refresh reposts`, `attach_file` (most cases), `accept_confirm`, label clicks, image-button submits, and `<summary>` clicks all pass against the new nightly floor.
+- A subscription leak in `Page.loadEventFired` after navigation could slowly accumulate listeners on long-running suites.
+- `visibleText` no longer inserts a stray newline between adjacent empty block elements.
+- A clearer error message when `lsof` isn't installed and the gem can't reclaim a stuck port.
+
+### Removed
+
+- Most of the gem's JS polyfills — Lightpanda implements these natively now: the `#id` selector rewriter, the form-submission fetch+swap, the label/image-button/summary click handlers, and large parts of the visibility/disabled-state polyfills. No code change required on your end; tests should just pass.
+
+### Internal
+
+- 91-case XPath 1.0 conformance battery (replaced ad-hoc specs).
+- README redesign.
+
 ## [0.1.0] - 2026-04-27
 
 Initial release. Capybara driver for the [Lightpanda](https://github.com/lightpanda-io/browser) headless browser.

data/README.md

@@ -1,200 +1,44 @@
-# Capybara::Lightpanda
+<div align="center">
 
-A [Capybara](https://github.com/teamcapybara/capybara) driver for [Lightpanda](https://lightpanda.io/), the fast headless browser built in Zig.
+# Capybara::Lightpanda
 
-This gem provides a **self-contained, production-ready** Capybara driver with a built-in CDP client. No external browser-client gem required — just install and go:
+[![Gem version](https://img.shields.io/gem/v/capybara-lightpanda?logo=rubygems&logoColor=white&label=gem)](https://rubygems.org/gems/capybara-lightpanda)
+[![Total downloads](https://img.shields.io/gem/dt/capybara-lightpanda?label=downloads)](https://rubygems.org/gems/capybara-lightpanda)
+[![Tests](https://img.shields.io/github/actions/workflow/status/navidemad/capybara-lightpanda/ci.yml?branch=main&logo=github&label=tests)](https://github.com/navidemad/capybara-lightpanda/actions/workflows/ci.yml)
+[![Rails compatible](https://img.shields.io/badge/Rails-compatible-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/)
+[![Turbo friendly](https://img.shields.io/badge/Turbo-friendly-CC0000?logo=hotwire&logoColor=white)](https://turbo.hotwired.dev/)
 
-- **Reliable navigation** — falls back to `document.readyState` polling when `Page.loadEventFired` doesn't fire (a known Lightpanda limitation on pages with complex JS)
-- **XPath polyfill** — auto-injected after each navigation so Capybara's internal XPath selectors work (`find`, `click_on`, `fill_in`, `assert_selector`, etc.)
-- **Cookie management** — `set_cookie`, `clear_cookies`, `remove_cookie` on the driver + graceful fallback when `Network.clearBrowserCookies` crashes the CDP connection
-- **Drop-in Capybara integration** — registers a `:lightpanda` driver, configure and go
+A [Capybara](https://github.com/teamcapybara/capybara) driver for [Lightpanda](https://lightpanda.io/), the fast headless browser built in Zig.<br>
+Self-contained — built-in CDP client, no external browser-client gem required.
 
-## Architecture
+<strong>Capybara</strong>&nbsp;&nbsp;→&nbsp;&nbsp;<code>capybara-lightpanda</code>&nbsp;&nbsp;→&nbsp;&nbsp;<a href="https://lightpanda.io/"><img src="docs/static/img/lightpanda-logo.svg" alt="Lightpanda" height="22" valign="middle"></a>&nbsp;<a href="https://github.com/lightpanda-io/browser/stargazers"><img src="https://img.shields.io/github/stars/lightpanda-io/browser?logo=github&label=stars" alt="GitHub stars" valign="middle"></a>
 
-Similar to how [Cuprite](https://github.com/rubycdp/cuprite) builds on [Ferrum](https://github.com/rubycdp/ferrum), but as a single gem:
+[![Capybara::Lightpanda — faster system tests for Rails, without Chromium](docs/static/img/banner.png)](https://navidemad.github.io/capybara-lightpanda/)
+<sub><em>Configuration · dual-driver setups · Turbo Rails · capability matrix · beta-testing guide</em></sub>
 
-```
-Capybara  →  capybara-lightpanda (driver + CDP client)  →  Lightpanda browser
-```
+[![Read the docs](https://img.shields.io/badge/https%3A%2F%2Fnavidemad.github.io%2Fcapybara--lightpanda-→%20Visit%20the%20website-1F2937?style=for-the-badge)](https://navidemad.github.io/capybara-lightpanda/)
 
-## Installation
+</div>
 
-### 1. Install the Lightpanda browser
-
-```bash
-# macOS
-brew install lightpanda-io/lightpanda/lightpanda
-
-# Linux (Debian/Ubuntu) — see https://lightpanda.io/docs/
-```
+## Install
 
-### 2. Add the gem
+Add this to your `Gemfile` and run `bundle install`:
 
 ```ruby
-# Gemfile
 group :test do
   gem "capybara-lightpanda"
 end
 ```
 
-```bash
-bundle install
-```
-
-## Usage
-
-### Basic setup
+In your test setup:
 
 ```ruby
-# test/support/capybara.rb or spec/support/capybara.rb
 require "capybara-lightpanda"
-
-Capybara::Lightpanda.configure do |config|
-  config.host = "127.0.0.1"
-  config.port = 9222
-  config.timeout = 15
-  config.browser_path = "/usr/local/bin/lightpanda" # optional, auto-detected
-end
-
-Capybara.default_driver = :lightpanda
 Capybara.javascript_driver = :lightpanda
 ```
 
-### Dual-driver setup (recommended)
-
-Run most tests with Chrome, use Lightpanda for fast DOM-only tests:
-
-```ruby
-if ENV["BROWSER"] == "lightpanda"
-  require "capybara-lightpanda"
-
-  Capybara::Lightpanda.configure do |config|
-    config.timeout = 15
-  end
-
-  Capybara.default_driver = :lightpanda
-  Capybara.javascript_driver = :lightpanda
-else
-  # Your existing Chrome/Cuprite setup
-  Capybara.default_driver = :cuprite
-end
-```
-
-```bash
-# Run with Lightpanda
-BROWSER=lightpanda bundle exec rails test test/system/
-
-# Run with Chrome (default)
-bundle exec rails test test/system/
-```
-
-### Setting cookies (e.g. login helper)
-
-```ruby
-class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
-  def login_as(user)
-    session = user.sessions.first_or_create!
-    cookie_jar = ActionDispatch::TestRequest.create({ "REQUEST_METHOD" => "GET" }).cookie_jar
-    cookie_jar.signed[:session_id] = { value: session.id }
-
-    page.driver.set_cookie(
-      "session_id",
-      cookie_jar[:session_id],
-      domain: "127.0.0.1",
-      httpOnly: true,
-      secure: false,
-    )
-  end
-end
-```
-
-## What works
-
-- Navigation (`visit`, `click_link`, `go_back`, `go_forward`, `refresh`)
-- JavaScript execution (V8 engine) — `evaluate_script`, `execute_script`, `evaluate_async_script`
-- Forms — `fill_in`, `click_button`, `select`, `choose`, `check`, `uncheck`
-- Finding — `find`, `all`, `within`, CSS and XPath selectors
-- Matchers — `assert_selector`, `assert_text`, `assert_current_path`, `has_field?`, `has_select?`
-- Cookies — set/get/clear/remove via CDP
-- Frames — `within_frame`, scoped finding
-- Keyboard — `send_keys` with modifiers and special keys
-- Network — traffic tracking, custom headers, idle waiting
-
-### Turbo Rails support
-
-The gem handles Turbo-enabled Rails apps transparently:
-
-| Feature | Status | How |
-|---------|--------|-----|
-| **Turbo Frames** | Works natively | Lazy-loading (`src=`), scoped link navigation |
-| **Turbo Drive** | Auto-disabled | Gem disables Drive (body replacement fails in Lightpanda) — standard link navigation restored |
-| **Form submission** | Auto-handled | When Turbo is present, forms submit via `fetch()` + `document.write()` to bypass Turbo's interception |
-| **Turbo Streams** | Not supported | Depends on Turbo's fetch pipeline which Lightpanda can't render |
-
-**Root cause**: Lightpanda's `document.body` is read-only — Turbo Drive's body replacement and frame form responses can't be applied. The gem works around this automatically.
-
-## Known limitations
-
-These are Lightpanda browser limitations, not driver limitations:
-
-| Feature | Status |
-|---------|--------|
-| Screenshots | Not supported (no rendering engine) |
-| `window.getComputedStyle()` | Returns defaults (no CSS engine) |
-| `scroll_to`, `resize` | No layout engine |
-| Complex Stimulus controllers | Some may not execute fully |
-| XPath axes/functions | Polyfill covers ~80% of Capybara usage |
-| File uploads | Not yet supported |
-| Turbo Streams | Not supported (Turbo's fetch-then-render pipeline) |
-
-## Benchmark
-
-Tested on a Rails 8.1 app (Turbo + Stimulus), 24 DOM-only tests:
-
-| Driver | Tests | Time | Speed |
-|--------|-------|------|-------|
-| **Lightpanda** | 24/24 pass | 6.89s | 3.48 tests/s |
-| **Chrome** | 24/24 pass | 7.09s | 3.38 tests/s |
-
-Lightpanda's advantage is expected to grow on larger suites due to faster startup and lower memory usage.
-
-## Configuration
-
-```ruby
-Capybara::Lightpanda.configure do |config|
-  config.host = "127.0.0.1"       # Lightpanda bind host
-  config.port = 9222              # Lightpanda CDP port
-  config.timeout = 15             # Navigation/command timeout (seconds)
-  config.process_timeout = 10     # Browser process startup timeout
-  config.browser_path = nil       # Path to lightpanda binary (auto-detected)
-end
-```
-
-### Dynamic port (parallel tests)
-
-```ruby
-def available_port
-  server = TCPServer.new("127.0.0.1", 0)
-  port = server.addr[1]
-  server.close
-  port
-end
-
-Capybara::Lightpanda.configure do |config|
-  config.port = ENV.fetch("LIGHTPANDA_PORT", available_port).to_i
-end
-```
-
-## How it works
-
-| Component | Description |
-|-----------|-------------|
-| `Browser` | High-level API with readyState polling fallback when `Page.loadEventFired` never fires |
-| `Cookies` | Catches `BrowserError` from unsupported `Network.clearBrowserCookies`, deletes cookies individually |
-| `XPathPolyfill` | Provides `document.evaluate` + `XPathResult` shim for Capybara's XPath selectors |
-| `Client` | CDP command dispatch over WebSocket with timeout and event subscription |
-| `Driver` | Complete Capybara driver with `set_cookie`, `clear_cookies`, `remove_cookie` |
-| `Node` | DOM interactions via JavaScript evaluation |
+> [!TIP]
+> The Lightpanda binary is auto-downloaded on first use — no separate install step needed.
 
 ## Credits
 
@@ -202,13 +46,12 @@ end
 - [Capybara](https://github.com/teamcapybara/capybara) — the test framework
 - Inspired by the [Cuprite](https://github.com/rubycdp/cuprite) / [Ferrum](https://github.com/rubycdp/ferrum) architecture and [`lightpanda-ruby`](https://github.com/marcoroth/lightpanda-ruby)
 
-Patterns adapted from these MIT-licensed projects (cookies API, frame switching,
-node call/error conventions, retry/event utilities) are acknowledged with the
-original copyright notices in [NOTICE.md](NOTICE.md).
+Patterns adapted from these MIT-licensed projects (cookies API, frame switching, node call/error conventions, retry/event utilities) are acknowledged with the original copyright notices in [NOTICE.md](NOTICE.md).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/navidemad/capybara-lightpanda).
+Bug reports and pull requests are welcome on [GitHub](https://github.com/navidemad/capybara-lightpanda).<br>
+For beta-testing tips and how to file useful feedback, see [BETA_TESTING.md](BETA_TESTING.md).
 
 ## License
 

data/lib/capybara/lightpanda/binary.rb

@@ -73,7 +73,7 @@ module Capybara
         end
 
         def find
-          env_path = ENV.fetch("LIGHTPANDA_PATH", nil)
+          env_path = ENV.fetch("LIGHTPANDA_BIN", nil)
           return env_path if env_path && File.executable?(env_path)
 
           path_binary = find_in_path