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 · setup recipes · Turbo Rails · known limitations · beta-testing guide

Requirements

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.

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), 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] For reproducible CI, pin the browser: Capybara::Lightpanda::Binary.required_version = "1.0.3" (the tagged release the gem's current floor is pinned to — nightly build 11647 is that release's commit). Without a pin the driver tracks Lightpanda's rolling nightly tag, which moves under you. See Pinning the browser version.

Credits

• 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.

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