Capybara::Lightpanda

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 · dual-driver setups · Turbo Rails · capability matrix · beta-testing guide}

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 @media rules and window.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.

License

MIT License