A Capybara driver for Lightpanda, the fast headless browser built in Zig.
Self-contained — built-in CDP client, no external browser-client gem required.
Capybara → capybara-lightpanda →
Configuration · setup recipes · Turbo Rails · known limitations · beta-testing guide
| Ruby | ≥ 3.3 — CI covers 3.3 and 4.0 |
| Capybara | ≥ 3.0, < 5 |
| Platforms | Linux x86_64 · Linux aarch64 · macOS Apple Silicon · macOS Intel · Windows through WSL2 (no native Windows build upstream) |
An unsupported host raises UnsupportedPlatformError at boot, naming what it detected — it never fails halfway through a suite.
Add this to your Gemfile and run bundle install:
group :test do
gem "capybara-lightpanda"
endIn your test setup:
require "capybara-lightpanda"
Capybara.javascript_driver = :lightpanda
# Rails system tests don't read Capybara.javascript_driver — use driven_by:
driven_by :lightpandaTip
The Lightpanda binary is auto-downloaded on first use — no separate install step needed.
Important
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.
Tip
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.
- Lightpanda — the headless browser
- Capybara — the test framework
- Inspired by the Ferrum architecture and
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.
Bug reports and pull requests are welcome on GitHub.
For beta-testing tips and how to file useful feedback, see BETA_TESTING.md.