capybara-lightpanda 0.19.1 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a454f0dd0d53f9f791377a4e7c268d577970f101d8130c2f08244808952e9075
4
- data.tar.gz: 9f1d2088b26a9be0d7b10e0e650dd93dd95b099378404ce62e5d7e19c4d9ede2
3
+ metadata.gz: 85c34a939aac4ec0af4d86f7f3269829bafdfc8b738fc74b0c0d571f33c6b5c9
4
+ data.tar.gz: 73f3d256e61fbaea568f651fa02a8d889a7e84152f9cf1c000b27d34db7cc4a4
5
5
  SHA512:
6
- metadata.gz: c266fe7161d1a975986effc8c4fcb775b51589a40039acb829523217ea20cb90b9569c1c75e469402782b936673feeb4392298b61350118823732fe958327b9a
7
- data.tar.gz: 37f28c43ded7af3c81ec17aeebdccf230f7bd95870ca11febdfcf88a6f338a031b953e5e1bec496f254c861ea6e5e98a85c2041ba85eb98485fe37eb981f652f
6
+ metadata.gz: fc767d39e68f00f30fd00f0f70165075dd4f57b0ee0180330100a37c7a9f6f6b549d0f55678c42916bed0cc2773866323901bf80570053fe8e5b730922a581db
7
+ data.tar.gz: 819cb05a4786ee56626fced0c2aa270c2ddfc1c59146c4d08565f5b450200facf60ca80f6760c265b261f1411e139731168954c9abf75b51367fa67336364adc
data/CHANGELOG.md CHANGED
@@ -1,5 +1,37 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.20.0] - 2026-11-19
4
+
5
+ > **Migrating from Cuprite or Selenium?** Keep your driver name with `Capybara::Lightpanda.register_cuprite_driver`, and your Selenium helpers (`manage.cookie_named`, `logs.get(:browser)`, `action.send_keys`, `download_path=`) now work as they are. **Already on `:lightpanda`?** Four defaults changed, listed under Changed: `evaluate_async_script` now times out at Capybara's wait, `wait_for_network_idle` waits for response bodies, `right_click` / `double_click` press the target first, and `logs.get(:browser)` includes uncaught errors.
6
+
7
+ ### Added
8
+
9
+ - **`timezone` driver option.** `timezone: "America/New_York"` makes `Date` and `Intl` in the page report that zone, whatever the host or CI runner is set to. Lightpanda accepts `Emulation.setTimezoneOverride` but ignores it, so the zone is given to the browser process alone: your test process and your app keep theirs. It is one zone per browser process, not per test, and has no effect with `ws_url`.
10
+ - **`page.driver.resize(width, height)` and `page.driver.browser.downloads.set_behavior(save_path:, behavior:)`**, the Cuprite and Ferrum spellings, so a suite ported from Cuprite no longer stops on `NoMethodError` in its setup. `resize` drives the same viewport as `current_window.resize_to`; `set_behavior` points downloads at another directory (`:allow`) or turns them off (`:deny`) until the next `reset!`.
11
+ - **`page.driver.user_agent=`** sets the `User-Agent` request header and `navigator.userAgent` together, until the next `reset!`. A `User-Agent` passed to `headers=` only changes the request header.
12
+ - **A Cuprite suite can keep its driver name.** `Capybara::Lightpanda.register_cuprite_driver(:better_cuprite, window_size: [1200, 800])` registers a Lightpanda driver under the name your `driven_by` already uses, so specs and shared hooks stay as they are. Options the browser can't honor (a Chrome HTTP `url:`, a `wss://` endpoint, Chrome flags, headed mode, `inspector: true`, unknown keys) raise before a browser starts; an empty `browser_options: {}`, `pending_connection_errors: false`, `slowmo: 0`/`nil` and `inspector: nil`/`false` are accepted. On this driver a `visit` the browser can't complete (refused connection, DNS failure) raises `Ferrum::StatusError` when Ferrum is loaded and `Capybara::Lightpanda::StatusError` otherwise. The driver also answers `wait_for_reload`, `network_traffic`, `clear_network_traffic`, `clear_memory_cache`, `cookies` and `set_cookie`. Both `:cuprite` and `:lightpanda` stay registered whichever gem loads first.
13
+ - **Cuprite and Ferrum helpers on `page.driver.browser`.** `headers.get/set/add/clear` (with Ferrum's navigation-only Referer for `add(..., permanent: false)`); `cookies.set(url:)` and `cookies.remove(url:)`; `network.traffic` entries answer `request.url`, `response.status` and `finished?` while keeping their hash keys; `network.status`, `network.response`, `network.clear(:traffic)` / `clear(:cache)` and `wait_for_idle(duration:)`; `downloads.wait { click_link "Report" }`, which runs the block and waits for the download it starts; `wait_for_reload(seconds)`; and `page.command(...)` for raw CDP on the page. Under the opt-in registration, cookies follow Cuprite: `cookies.set` without a domain uses the current host, `cookies.remove(name:)` removes the name at every path, and `cookies.all` is a hash keyed by name.
14
+ - **Runtime timezone switching where the browser supports it.** `page.driver.browser.page.command("Emulation.setTimezoneOverride", timezoneId: zone)` checks that the page really reports the zone. Lightpanda 1.0.4 and current nightlies ignore the command, so it raises `Capybara::NotSupportedByDriverError` there instead of letting a spec run in the wrong zone; use the `timezone:` option for a fixed zone.
15
+ - **Click modifiers reach the page.** `click(:shift)`, `click(:control, :alt)`, `click(:meta)` set `shiftKey`/`ctrlKey`/`altKey`/`metaKey` on the mouse events, for `click`, `right_click` and `double_click`.
16
+ - **Selenium helpers shared by Rails suites.** `page.driver.browser.manage.all_cookies`, `cookie_named(name)` and `delete_all_cookies` (scoped to the current document, as WebDriver is); `manage.window.resize_to(w, h)`; `browser.download_path = dir`; `browser.action.send_keys(:arrow_right).perform` for the arrow keys and Enter, sent to the focused element; and `element.native.attribute("validationMessage")`, which reads live properties as strings. `logs.get(:browser)` entries gain `time` and `as_json`.
17
+ - **Coordinate mouse calls say what to do.** `page.driver.browser.mouse` and a non-HTML5 `drag_to` raise with a message pointing the example to Cuprite (Chrome), since Lightpanda has no rendered layout. `respond_to?(:mouse)` stays false, so suites that already check for it keep falling back.
18
+ - **`Capybara::Lightpanda::ScriptTimeoutError`** and **`NoSuchCookieError`** error classes.
19
+
20
+ ### Changed
21
+
22
+ - **`evaluate_async_script` waits as long as Capybara does.** The callback now has `Capybara.default_max_wait_time` (2 seconds unless you changed it), as on Selenium and Cuprite, and a late callback raises `Capybara::Lightpanda::ScriptTimeoutError`. It used to have the driver's 15-second `timeout` and returned the late value. Wrap a slow script in `using_wait_time(15) { ... }` to keep the old budget.
23
+ - **`wait_for_network_idle` waits for response bodies.** A request now counts as in flight until its body has arrived, not just its headers, as in Chrome and Cuprite. A page holding a stream open (`EventSource`, a long download) therefore never goes idle: `wait_for_network_idle` returns `false` after its timeout where it used to return `true`. Pass `connections: 1` (or the number of streams) on such pages. Redirect hops and failed requests still close at once.
24
+ - **`right_click` and `double_click` send the whole press.** They now dispatch `mousedown` and `mouseup` around the `contextmenu` or `click`, and move focus, as a pointer does. `double_click` also activates its target once before `dblclick`, as Chrome and Cuprite do: a double-clicked link is followed and a double-clicked checkbox is toggled. They used to dispatch `contextmenu` or `dblclick` alone.
25
+ - **`logs.get(:browser)` reports uncaught errors.** Uncaught exceptions and unhandled promise rejections now appear as `SEVERE` entries next to console messages, as in Chrome's browser log, so a teardown that fails on `SEVERE` entries catches them. Entry timestamps are wall-clock milliseconds (Lightpanda's own event clock counts seconds since the host booted) and `to_s` reads `"<time> <LEVEL>: <message>"`. `console_logs` and `page_errors` entries gain `received_at` (epoch milliseconds).
26
+ - **Typing sends key events.** `send_keys("NT")` now fires `keydown`, `keypress` and `keyup` for each character a US keyboard types, as a user's typing does; it used to fire `input` alone. `fill_in` still writes the value in one step, and now fires one `keydown` and one `keyup` around it. A table filter, autocomplete or counter bound to `keyup` or `keydown` runs as it does on Selenium and Cuprite. A page that cancels `keydown` to refuse a character now refuses it under `send_keys` too.
27
+ - **A user agent the browser refuses is no longer silent.** Lightpanda ignores any user agent containing `Mozilla` and answers as if it had applied it, so the suite ran on `Lightpanda/1.0` with no signal. `user_agent=` raises on such a value and `headers=` / `add_headers` print a warning. Drop the `Mozilla/5.0` prefix and keep the device tokens: the `browser` and `device_detector` gems read `Lightpanda/1.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) Mobile` as an iPhone.
28
+
29
+ ### Fixed
30
+
31
+ - **Clicking a select2 that can be cleared no longer clears it.** With `allowClear` and a value, select2 4 puts its "×" just before the selected text. The click landed on the "×", so the value was emptied and `change` fired before the list opened; a page that reloads on change then lost the list, and the option was never found. The click now lands on the text, as a pointer in the middle of the field does.
32
+ - **Table rows read like your previous driver's.** The two Chrome drivers disagree on the text of a table row: Cuprite separates cells with a tab (`"Total due\t$0.00"`), Selenium with a space (`"Total due $0.00"`). The `register_cuprite_driver` registration now keeps the tab, as Cuprite does; the stock `:lightpanda` driver keeps the space, as Selenium and every earlier release do.
33
+ - **`send_keys` reaches a rich-text editor in an iframe.** When the iframe's `<body>` is the editable area (TinyMCE, CKEditor 4), the keys were dropped, or typed into whatever field the top page had focused. They now go to the editor, after its existing text. `send_keys` on a paragraph inside an editor types into that editor.
34
+
3
35
  ## [0.19.1] - 2026-11-18
4
36
 
5
37
  ### Fixed
data/NOTICE.md CHANGED
@@ -6,9 +6,15 @@ below in accordance with the MIT License.
6
6
 
7
7
  No verbatim source files from these projects are included; the work referenced
8
8
  here covers API shape, error-handling conventions, and architectural patterns
9
- re-implemented for Lightpanda's CDP surface (notably in `Cookies`, `Frame`,
10
- `Node`, `Driver`, and `Utils::Event`). Code-level pointers to the inspiring
11
- upstream patterns are kept as comments in the relevant files.
9
+ re-implemented for Lightpanda's CDP surface (notably in `Cookies`, `Node`,
10
+ `Driver`, `Client`, and `Utils::Event`). Comments in the relevant files point at
11
+ the Ferrum and Cuprite patterns they follow; lightpanda-ruby informed the
12
+ overall design, without file-level pointers.
13
+
14
+ A few public API names (`with_lightpanda_browser`, `with_lightpanda_node`, the
15
+ case-insensitive `Headers`) follow
16
+ [capybara-playwright-driver](https://github.com/YusukeIwaki/capybara-playwright-driver)'s;
17
+ no code is adapted from it, so it is credited here rather than listed below.
12
18
 
13
19
  ---
14
20
 
data/README.md CHANGED
@@ -1,76 +1,265 @@
1
- <div align="center">
2
-
3
1
  # Capybara::Lightpanda
4
2
 
5
3
  [![Gem version](https://img.shields.io/gem/v/capybara-lightpanda?logo=rubygems&logoColor=white&label=gem)](https://rubygems.org/gems/capybara-lightpanda)
6
4
  [![Total downloads](https://img.shields.io/gem/dt/capybara-lightpanda?label=downloads)](https://rubygems.org/gems/capybara-lightpanda)
7
5
  [![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)
8
- [![Rails compatible](https://img.shields.io/badge/Rails-compatible-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/)
9
- [![Turbo friendly](https://img.shields.io/badge/Turbo-friendly-CC0000?logo=hotwire&logoColor=white)](https://turbo.hotwired.dev/)
6
+ [![Lightpanda stars](https://img.shields.io/github/stars/lightpanda-io/browser?logo=github&label=Lightpanda%20stars)](https://github.com/lightpanda-io/browser/stargazers)
10
7
 
11
- A [Capybara](https://github.com/teamcapybara/capybara) driver for [Lightpanda](https://lightpanda.io/), the fast headless browser built in Zig.<br>
12
- Self-contained — built-in CDP client, no external browser-client gem required.
8
+ A [Capybara](https://github.com/teamcapybara/capybara) driver for [Lightpanda](https://lightpanda.io/), a headless browser made with Zig.
13
9
 
14
- <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>
10
+ - You write the same Capybara tests as before.
11
+ - You do not need Chromium.
12
+ - Each test worker needs about 17 MB of memory.<br>
13
+ With Chrome, each one needs about 280 MB.
14
+ - The gem comes with its own CDP client.<br>
15
+ You do not need another browser gem.
15
16
 
16
- [![Capybara::Lightpanda — faster system tests for Rails, without Chromium](docs/static/img/banner.png)](https://navidemad.github.io/capybara-lightpanda/)
17
- <sub><em>Configuration · setup recipes · Turbo Rails · known limitations · beta-testing guide</em></sub>
17
+ We saw these numbers on a Rails 8.1 app with 24 system tests.<br>
18
+ The two drivers took the same time, about 7 seconds.
18
19
 
19
- [![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/)
20
+ Each week, we run the driver on the tests of [seven real Rails apps](https://navidemad.github.io/capybara-lightpanda/docs/#validation).
20
21
 
21
- </div>
22
+ **[Read the docs on the website →](https://navidemad.github.io/capybara-lightpanda/docs/)**<br>
23
+ You will find all the options there, setup recipes, Turbo, and help with errors.
22
24
 
23
- ## Requirements
25
+ ## Install
24
26
 
25
- | | |
26
- |---|---|
27
- | **Ruby** | ≥ 3.3 — CI covers 3.3 and 4.0 |
28
- | **Capybara** | ≥ 3.0, < 5 |
29
- | **Platforms** | Linux `x86_64` · Linux `aarch64` · macOS Apple Silicon · macOS Intel · Windows through WSL2 (no native Windows build upstream) |
27
+ Add the gem to your `Gemfile`, then run `bundle install`:
30
28
 
31
- An unsupported host raises `UnsupportedPlatformError` at boot, naming what it detected — it never fails halfway through a suite.
29
+ ```ruby
30
+ gem "capybara-lightpanda", group: :test
31
+ ```
32
32
 
33
- ## Install
33
+ Then name the driver. Choose the part that fits your tests.
34
34
 
35
- Add this to your `Gemfile` and run `bundle install`:
35
+ ### Minitest
36
36
 
37
37
  ```ruby
38
- group :test do
39
- gem "capybara-lightpanda"
38
+ # test/application_system_test_case.rb
39
+ require "capybara-lightpanda"
40
+
41
+ class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
42
+ driven_by :lightpanda
40
43
  end
41
44
  ```
42
45
 
43
- In your test setup:
46
+ ### RSpec
44
47
 
45
48
  ```ruby
49
+ # spec/support/capybara.rb
46
50
  require "capybara-lightpanda"
47
- Capybara.javascript_driver = :lightpanda
48
51
 
49
- # Rails system tests don't read Capybara.javascript_driver — use driven_by:
50
- driven_by :lightpanda
52
+ RSpec.configure do |config|
53
+ config.before(:each, type: :system) { driven_by :lightpanda }
54
+ end
51
55
  ```
52
56
 
53
- > [!TIP]
54
- > The Lightpanda binary is auto-downloaded on first use — no separate install step needed.
57
+ ### Capybara without Rails
58
+
59
+ ```ruby
60
+ require "capybara-lightpanda"
55
61
 
56
- > [!IMPORTANT]
57
- > Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), and `@media` / `window.matchMedia()` evaluate against the `window_size` you configure — so a mobile-only CTA gated by `@media (max-width: …)` resolves at the width you ask for. What's missing is *layout*: nothing reflows, `getBoundingClientRect` stays synthetic, and there is no real scroll. Specs that assert on pixel geometry, scrolling, or screenshots can't pass here, nor can the two that catch people out: a second browser tab and a menu revealed purely by CSS `:hover`. See [known limitations](https://navidemad.github.io/capybara-lightpanda/docs/#limits).
62
+ Capybara.default_driver = :lightpanda
63
+ Capybara.javascript_driver = :lightpanda
64
+ ```
65
+
66
+ The first time you run a test, the gem gets the Lightpanda browser for you.
58
67
 
59
68
  > [!TIP]
60
- > The gem downloads the Lightpanda release it was validated against (currently 1.0.4), so the browser only changes when you upgrade the gem. If your suite stubs HTTP (VCR/WebMock), run `bundle exec capybara-lightpanda install` in `bin/setup` and in CI before the tests. To pick another release or the rolling nightly, see [Choosing the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
69
+ > Do your tests block HTTP calls with VCR or WebMock?<br>
70
+ > Then get the browser before the tests start.<br>
71
+ > Run `bundle exec capybara-lightpanda install` in `bin/setup` and in CI.
72
+
73
+ You can try the gem next to your current driver.<br>
74
+ [BETA_TESTING.md](BETA_TESTING.md) shows how to turn it on with one env var.<br>
75
+ To go back, drop the env var.
76
+
77
+ ## Test it with your AI agent
78
+
79
+ Do you use an AI coding agent, such as Claude Code or Codex?<br>
80
+ Give it the prompt below.
81
+
82
+ - The agent tries the gem on your app.
83
+ - It keeps your current driver as the default.
84
+ - It writes a bug report with no private data.
85
+ - You read each report before the agent posts it.
86
+
87
+ Are you an AI agent? Then follow the same steps.
88
+
89
+ ```text
90
+ Goal: find out if this Rails app can run its system tests with the
91
+ capybara-lightpanda gem, and report each real problem to the gem's authors.
92
+
93
+ Rules
94
+ - Work on a new git branch. Do not commit, push or open a pull request.
95
+ - Do not change the default driver. Lightpanda runs only when BROWSER=lightpanda.
96
+ - Do not post anything on GitHub until I say yes.
97
+ - Never copy secrets, customer data or private names into a report.
98
+
99
+ Step 1. Look
100
+ - Find the test framework (Minitest or RSpec), the current Capybara driver and
101
+ the command that runs the system tests.
102
+ - If the full run takes more than 10 minutes, ask me which folder to run.
103
+
104
+ Step 2. Set up
105
+ - Add `gem "capybara-lightpanda"` to the test group of the Gemfile, then run
106
+ `bundle install` and `bundle exec capybara-lightpanda install`.
107
+ - Minitest, in test/application_system_test_case.rb:
108
+ driven_by ENV["BROWSER"] == "lightpanda" ? :lightpanda : <current driver>
109
+ - RSpec, in the support file that sets the driver:
110
+ config.before(:each, type: :system) do
111
+ driven_by ENV["BROWSER"] == "lightpanda" ? :lightpanda : <current driver>
112
+ end
113
+ - More cases: https://github.com/navidemad/capybara-lightpanda/blob/main/BETA_TESTING.md
114
+
115
+ Step 3. Run
116
+ - Run the system tests with the current driver. Save the results and the time.
117
+ - Run them again with BROWSER=lightpanda. Save the results and the time.
118
+ - Keep only the tests that pass with the current driver and fail with
119
+ Lightpanda. Run each one alone, one more time. Drop it if it now passes.
120
+
121
+ Step 4. Sort the failures
122
+ - Known limit, do not report: the test needs a screenshot, pixel positions,
123
+ real scrolling, a second tab or window, or a menu that only CSS :hover opens.
124
+ Full list: https://navidemad.github.io/capybara-lightpanda/docs/#limits
125
+ - Everything else is a real problem. For each one:
126
+ - read the error, `page.driver.browser.console_logs` and
127
+ `page.driver.browser.page_errors`;
128
+ - cut the page and the test down to the smallest HTML and test that still fail;
129
+ - check that this small test passes with the current driver.
130
+
131
+ Step 5. Write the reports, but do not post them
132
+ - One draft per real problem, with the fields of this form:
133
+ https://github.com/navidemad/capybara-lightpanda/issues/new?template=beta-feedback.yml
134
+ - Give: what broke, the small repro, the error, the result with the current
135
+ driver, and the versions of Rails, Ruby, Capybara, capybara-lightpanda and
136
+ Lightpanda (`bundle exec capybara-lightpanda version`).
137
+ - Make each draft anonymous. Remove the app name, company name, names of
138
+ people, emails, domains, URLs, tokens, keys and business data. Use
139
+ placeholder names such as `Post`, `User` and `example.test`.
140
+ - No real problem? Then write one draft for this form instead, with the numbers:
141
+ https://github.com/navidemad/capybara-lightpanda/issues/new?template=it-worked.yml
142
+
143
+ Step 6. Tell me
144
+ - A short table: tests run, passed with both drivers, failed only with
145
+ Lightpanda (known limits and real problems), and the time for each driver.
146
+ - The drafts, ready to read.
147
+ - The files you changed, and the commands to undo everything.
148
+ Then wait for my answer.
149
+ ```
150
+
151
+ ## What to expect
152
+
153
+ Lightpanda runs your JavaScript, reads your CSS and works with Turbo.<br>
154
+ On the real Rails apps we test each week, almost all tests pass with no change.
155
+
156
+ Lightpanda has no layout engine.<br>
157
+ So a few kinds of tests still need your old driver:
158
+
159
+ - tests with screenshots
160
+ - tests with pixel positions or real scrolling
161
+ - tests with a second tab
162
+ - tests with a menu that only CSS `:hover` can open
163
+
164
+ You can keep both drivers in the same app.<br>
165
+ The docs have the [full list](https://navidemad.github.io/capybara-lightpanda/docs/#limits).
166
+
167
+ ## Examples
168
+
169
+ The [`examples/`](examples/) folder has small Rails apps.<br>
170
+ Each app is one file that you can run:
171
+
172
+ - [Minitest](examples/rails_minitest_example.rb) and [RSpec](examples/rails_rspec_example.rb)
173
+ - Turbo Drive and Turbo Frames, with [Minitest](examples/rails_turbo_minitest_example.rb) and [RSpec](examples/rails_turbo_rspec_example.rb)
174
+ - [A menu](examples/rails_dropdown_minitest_example.rb) that you open with a click.
175
+ It shows a bug, so one of its tests fails on purpose.
176
+
177
+ ## Upgrading
178
+
179
+ A new gem version can need a new Lightpanda version.<br>
180
+ If your browser is too old, the driver will stop.<br>
181
+ It will tell you which version you have.
182
+
183
+ Read [CHANGELOG.md](CHANGELOG.md) before you change the gem version.
61
184
 
62
185
  ## Credits
63
186
 
64
- - [Lightpanda](https://lightpanda.io/) — the headless browser
65
- - [Capybara](https://github.com/teamcapybara/capybara) — the test framework
66
- - Inspired by the [Ferrum](https://github.com/rubycdp/ferrum) architecture and [`lightpanda-ruby`](https://github.com/marcoroth/lightpanda-ruby)
187
+ - [Lightpanda](https://lightpanda.io/) is the headless browser.
188
+ - [Capybara](https://github.com/teamcapybara/capybara) is the test framework.
189
+ - [Ferrum](https://github.com/rubycdp/ferrum) and [`lightpanda-ruby`](https://github.com/marcoroth/lightpanda-ruby) gave us ideas for the design.
67
190
 
68
- 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).
191
+ We took some code ideas from these projects.<br>
192
+ They use the MIT license.<br>
193
+ [NOTICE.md](NOTICE.md) has the list and the copyright notices.
69
194
 
70
195
  ## Contributing
71
196
 
72
- Bug reports and pull requests are welcome on [GitHub](https://github.com/navidemad/capybara-lightpanda).<br>
73
- For beta-testing tips and how to file useful feedback, see [BETA_TESTING.md](BETA_TESTING.md).
197
+ Please send bug reports and pull requests on [GitHub](https://github.com/navidemad/capybara-lightpanda).<br>
198
+ [BETA_TESTING.md](BETA_TESTING.md) shows how to try the gem and how to tell us what you find.
199
+
200
+ Where to find things in this repo:
201
+
202
+ - `lib/` has the driver and its CDP client.
203
+ - `test/` has our tests.
204
+ - `spec/` runs the tests that come with the Capybara gem.
205
+ - `examples/` has the Rails apps from the list above.
206
+ - `docs/` has the website. It is not part of the gem.
207
+ - `script/real-app/` lets you run a real-app test from CI on your own computer.
208
+ - [STATE_MACHINES.md](STATE_MACHINES.md) shows how the driver follows the browser, the connection and each page load.
209
+
210
+ Run `bundle exec rake readme:readability` after you change this file.<br>
211
+ It checks that the text is still easy to read.
212
+
213
+ ## Migrate a test suite
214
+
215
+ ### From Cuprite
216
+
217
+ Keep your application's driver name and register it with Lightpanda in test setup.
218
+
219
+ ```ruby
220
+ require "capybara-lightpanda"
221
+
222
+ Capybara::Lightpanda.register_cuprite_driver(:store_system, window_size: [1200, 800])
223
+ # In Rails system tests
224
+ # driven_by :store_system
225
+ ```
226
+
227
+ The registration checks copied options before a browser starts. Use `ws_url:` for a remote Lightpanda
228
+ WebSocket endpoint. A Cuprite HTTP `url:`, Chrome flags and proxy settings raise an option error.
229
+ So does `inspector: true`. Keep a Chrome driver for the inspector, or pass `inspector: ENV["INSPECTOR"]`.
230
+ Both `:cuprite` and `:lightpanda` remain available when you load both gems.
231
+
232
+ With this registration, existing helpers can call `browser.headers.set/add/get/clear`,
233
+ `browser.cookies.all.fetch("session")`, and `browser.network.traffic.first.request.url`.
234
+ Cookie enumeration includes entries that share a name across paths. Network entries also support
235
+ Lightpanda’s existing hash access. Use `network.clear(:traffic)` to forget observations and
236
+ `network.clear(:cache)` to clear the HTTP cache.
237
+
238
+ For downloads, set `save_path:` on the driver or configure `Capybara.save_path`, then use
239
+ `page.driver.browser.downloads.wait { click_link("Download report") }`. The block runs once.
240
+ Lightpanda’s `downloads.files` returns absolute paths. Existing click-then-wait calls still work.
241
+
242
+ Run the shared compatibility examples with `bundle exec ruby test/compatibility/cuprite_contract.rb`.
243
+ Run them again with `CONTRACT_DRIVER=cuprite` for the Chrome reference. Set `CHROME_BIN` or
244
+ `LIGHTPANDA_BIN` to select a local executable.
245
+
246
+
247
+ ### From Selenium
248
+
249
+ If your Rails tests say `driven_by :selenium`, change it to `driven_by :lightpanda`.
250
+ If they already use an app-owned name, keep the name and change its setup.
251
+
252
+ ```ruby
253
+ require "capybara-lightpanda"
254
+
255
+ Capybara.register_driver(:store_system) do |app|
256
+ Capybara::Lightpanda::Driver.new(app, window_size: [1200, 800])
257
+ end
258
+ ```
259
+
260
+ Keep a Chrome driver for tests that need screenshots, live layout changes, or more than one tab.
261
+ The [migration audit](CUPRITE_COMPATIBILITY.md) lists the helpers that pass on both drivers,
262
+ the original app specs we ran, and the edits those suites still need.
74
263
 
75
264
  ## License
76
265
 
@@ -9,10 +9,12 @@ module Capybara
9
9
  module Console
10
10
  # Console messages captured from `Runtime.consoleAPICalled` since the
11
11
  # last `reset` (Turbo-tracker sentinels excluded). Loose hashes, like
12
- # Network#traffic: `{type:, text:, timestamp:, args:}` where `type` is
13
- # the console method name ("log", "error", "warning", ...), `text` joins
14
- # the arguments' primitive values/descriptions, and `args` keeps the raw
15
- # CDP RemoteObjects. Lets suites assert on JS console errors
12
+ # Network#traffic: `{type:, text:, timestamp:, received_at:, args:}`
13
+ # where `type` is the console method name ("log", "error", "warning",
14
+ # ...), `text` joins the arguments' primitive values/descriptions, and
15
+ # `args` keeps the raw CDP RemoteObjects. `timestamp` is the browser's
16
+ # own value (see .received_at_ms); `received_at` is wall-clock epoch
17
+ # ms. Lets suites assert on JS console errors
16
18
  # (`browser.console_logs.select { |m| m[:type] == "error" }`) the way
17
19
  # peer drivers do via custom Ferrum loggers.
18
20
  def console_logs
@@ -25,7 +27,8 @@ module Capybara
25
27
 
26
28
  # Uncaught page exceptions and unhandled promise rejections since the
27
29
  # last `reset`: `{kind:, message:, url:, line:, column:, stack:,
28
- # timestamp:}`, where `kind` is "error" or "unhandledrejection".
30
+ # timestamp:, received_at:}`, where `kind` is "error" or
31
+ # "unhandledrejection".
29
32
  #
30
33
  # Deliberately NOT folded into #console_logs. Chrome reports an
31
34
  # uncaught exception through Runtime.exceptionThrown rather than
@@ -86,6 +89,15 @@ module Capybara
86
89
  }
87
90
  end
88
91
 
92
+ # Wall-clock epoch milliseconds when the driver took the event. CDP's
93
+ # `timestamp` is not that on Lightpanda: 1.0.4 sends whole seconds since
94
+ # the host booted (verified 2026-11-18: 474249 on a host up 5.5 days),
95
+ # where Chrome sends epoch milliseconds. Selenium-shaped log entries
96
+ # need a real time, so each entry carries this one as well.
97
+ def self.received_at_ms
98
+ ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
99
+ end
100
+
89
101
  def self.one_based(position)
90
102
  position + 1 if position
91
103
  end
@@ -93,7 +105,7 @@ module Capybara
93
105
  def self.page_error_message(exception, stack, rejection)
94
106
  return primitive_text(exception) unless stack
95
107
 
96
- summary = stack.split(/\n\s+at /, 2).first
108
+ summary = stack.split(/\n\s+at /, 2).first || exception["className"] || "Error"
97
109
  prefix = "#{exception['className']}: "
98
110
  rejection && summary.start_with?(prefix) ? summary.delete_prefix(prefix) : summary
99
111
  end
@@ -172,6 +184,7 @@ module Capybara
172
184
  type: params["type"],
173
185
  text: args.map { |a| console_arg_text(a) }.join(" "),
174
186
  timestamp: params["timestamp"],
187
+ received_at: Console.received_at_ms,
175
188
  args: args,
176
189
  }
177
190
  push_capped(@console_logs, @console_logs_mutex, entry, CONSOLE_LOGS_LIMIT)
@@ -184,7 +197,8 @@ module Capybara
184
197
 
185
198
  def subscribe_to_page_errors
186
199
  on("Runtime.exceptionThrown") do |params|
187
- push_capped(@page_errors, @page_errors_mutex, Console.page_error_entry(params), PAGE_ERRORS_LIMIT)
200
+ entry = Console.page_error_entry(params).merge(received_at: Console.received_at_ms)
201
+ push_capped(@page_errors, @page_errors_mutex, entry, PAGE_ERRORS_LIMIT)
188
202
  end
189
203
  end
190
204
 
@@ -26,17 +26,16 @@ module Capybara
26
26
 
27
27
  # Find child elements within a specific node.
28
28
  # Returns an array of remote object ID strings.
29
- #
30
- # Wrapped in `with_default_context_wait` so a click that triggered a
31
- # navigation immediately before the find (e.g. a fill_in following a
32
- # link that mutated the DOM) doesn't race against
33
- # `Runtime.executionContextCreated` and surface as
34
- # `NoExecutionContextError`. `find_in_document` and `find_in_frame`
35
- # already use the same wrapper; `find_within` was the odd one out.
36
29
  def find_within(remote_object_id, method, selector)
37
30
  find_within_hinted(remote_object_id, method, selector).map(&:first)
38
31
  end
39
32
 
33
+ # Wrapped in `with_default_context_wait` so a click that triggered a
34
+ # navigation immediately before the find (e.g. a fill_in following a
35
+ # link that mutated the DOM) doesn't race against
36
+ # `Runtime.executionContextCreated` and surface as
37
+ # `NoExecutionContextError` — the same wrapper `find_in_document` and
38
+ # `find_in_frame` use.
40
39
  def find_within_hinted(remote_object_id, method, selector, spec = nil)
41
40
  with_default_context_wait do
42
41
  result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, spec,
@@ -49,8 +48,8 @@ module Capybara
49
48
 
50
49
  # Ancestor chain of `remote_object_id` from parentNode up to (but
51
50
  # excluding) `document`, returned as an array of remote object IDs.
52
- # Same `with_default_context_wait` wrapping as `find_within` — same
53
- # race window applies.
51
+ # Same `with_default_context_wait` wrapping as `find_within_hinted` —
52
+ # same race window applies.
54
53
  def parents_of(remote_object_id)
55
54
  with_default_context_wait do
56
55
  result = call_function_on(remote_object_id, PARENTS_JS, return_by_value: false)
@@ -74,7 +73,7 @@ module Capybara
74
73
  # fix (e.g. a new XPath error case) can't silently miss a copy.
75
74
  #
76
75
  # XPath routes through native `Document.evaluate` + `XPathResult`
77
- # (Lightpanda PR #2305, in nightly >=6109); on parse error we return
76
+ # (Lightpanda PR #2305, in the floor); on parse error we return
78
77
  # [] silently to match Capybara's internal XPath generator, which
79
78
  # sometimes produces selectors with empty trailing predicates like
80
79
  # `(...)[]` that native rejects but `has_element?` expects to behave
@@ -24,12 +24,13 @@ module Capybara
24
24
  def go_to(url, wait: true)
25
25
  enable_page_events
26
26
 
27
- if wait
28
- wait_for_page_load(url)
29
- else
30
- page_command("Page.navigate", url: url)
31
- end
27
+ result = if wait
28
+ wait_for_page_load(url)
29
+ else
30
+ page_command("Page.navigate", **navigation_params(url))
31
+ end
32
32
  check_unhandled_modal!
33
+ yield result if block_given?
33
34
  end
34
35
  alias goto go_to
35
36
 
@@ -54,12 +55,28 @@ module Capybara
54
55
  end
55
56
  alias reload refresh
56
57
 
58
+ # Observe an outstanding or upcoming main-frame load, including a
59
+ # same-URL reload. Ferrum's return value is truthy even on expiry.
60
+ def wait_for_reload(timeout = 1) # rubocop:disable Naming/PredicateMethod
61
+ enable_page_events
62
+ with_main_frame_load("Page.navigatedWithinDocument") { |loaded| loaded.wait(timeout) }
63
+ true
64
+ end
65
+
57
66
  private
58
67
 
68
+ def navigation_params(url)
69
+ { url: url, referrer: headers&.referrer }.compact
70
+ end
71
+
59
72
  def wait_for_page_load(url, retried: false)
60
- deadline = await_navigation do
61
- @client.command("Page.navigate", { url: url }, async: true, session_id: @session_id)
73
+ deadline = nil
74
+ result = @client.observe_async_command("Page.navigate", navigation_params(url),
75
+ session_id: @session_id) do |send|
76
+ deadline = await_navigation(&send)
62
77
  end
78
+ return result unless @client.closed?
79
+
63
80
  handle_navigation_crash(url, deadline, retried: retried)
64
81
  end
65
82
 
@@ -77,7 +94,7 @@ module Capybara
77
94
  # bookkeeping into its public signature. enable_page_events is
78
95
  # needed again: reconnect's clear_session_state reset the flag.
79
96
  enable_page_events
80
- wait_for_page_load(url, retried: true)
97
+ return wait_for_page_load(url, retried: true)
81
98
  end
82
99
  rescue DeadBrowserError
83
100
  raise
@@ -135,24 +152,30 @@ module Capybara
135
152
  def await_navigation
136
153
  starting_url = safe_current_url
137
154
  deadline = monotonic_time + @options.timeout
138
- loaded = Utils::Event.new
139
- handler = proc { |params| loaded.set if params["frameId"] == @target_id }
140
- @client.on("Page.frameStoppedLoading", &handler)
141
-
142
- begin
155
+ with_main_frame_load do |loaded|
143
156
  yield
144
157
 
145
158
  unless loaded.wait([2, @options.timeout].min)
146
159
  remaining = deadline - monotonic_time
147
160
  poll_ready_state(remaining, loaded_event: loaded, starting_url: starting_url) if remaining.positive?
148
161
  end
149
- ensure
150
- @client.off("Page.frameStoppedLoading", handler)
151
162
  end
152
-
153
163
  deadline
154
164
  end
155
165
 
166
+ def with_main_frame_load(*additional_events)
167
+ loaded = Utils::Event.new
168
+ handler = proc { |params| loaded.set if params["frameId"] == @target_id }
169
+ client = @client
170
+ events = ["Page.frameStoppedLoading", *additional_events]
171
+ events.each { |event| client.on(event, &handler) }
172
+ begin
173
+ yield loaded
174
+ ensure
175
+ events.each { |event| client.off(event, handler) }
176
+ end
177
+ end
178
+
156
179
  # Poll document.readyState as a fallback when Page.loadEventFired
157
180
  # doesn't fire (CLAUDE.md rules call this out as load-bearing — do
158
181
  # not remove). When starting_url is provided, the poll ignores