Self-contained — built-in CDP client, no external browser-client gem required. Capybara →
capybara-lightpanda → 
[](https://navidemad.github.io/capybara-lightpanda/)
Configuration · dual-driver setups · Turbo Rails · capability matrix · beta-testing guide
[](https://navidemad.github.io/capybara-lightpanda/)
Install
Add this to your Gemfile and run bundle install:
group :test do
gem "capybara-lightpanda"
end
In your test setup:
require "capybara-lightpanda"
Capybara.javascript_driver = :lightpanda
# Rails system tests don't read Capybara.javascript_driver — use driven_by:
driven_by :lightpanda
[!TIP] 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), but@mediarules andwindow.matchMedia()evaluate against a fixed 1920×1080 viewport — there is no resize emulation. Any spec whose visibility depends on a non-desktop viewport — for example a mobile-only CTA shown via@media (max-width: …)— should stay on Cuprite (or whichever full-browser driver you were already using). The dual-driver setup routes the layout-sensitive minority to Cuprite and the structural majority to Lightpanda for speed.
Credits
- Lightpanda — the headless browser
- Capybara — the test framework
- Inspired by the Cuprite / 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.
Contributing
Bug reports and pull requests are welcome on GitHub.
For beta-testing tips and how to file useful feedback, see BETA_TESTING.md.