# Capybara::Lightpanda [![Gem version](https://img.shields.io/gem/v/capybara-lightpanda?logo=rubygems&logoColor=white&label=gem)](https://rubygems.org/gems/capybara-lightpanda) [![Total downloads](https://img.shields.io/gem/dt/capybara-lightpanda?label=downloads)](https://rubygems.org/gems/capybara-lightpanda) [![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) [![Rails compatible](https://img.shields.io/badge/Rails-compatible-CC0000?logo=rubyonrails&logoColor=white)](https://rubyonrails.org/) [![Turbo friendly](https://img.shields.io/badge/Turbo-friendly-CC0000?logo=hotwire&logoColor=white)](https://turbo.hotwired.dev/) A [Capybara](https://github.com/teamcapybara/capybara) driver for [Lightpanda](https://lightpanda.io/), the fast headless browser built in Zig.
Self-contained — built-in CDP client, no external browser-client gem required. Capybara  →  capybara-lightpanda  →  Lightpanda GitHub stars [![Capybara::Lightpanda — faster system tests for Rails, without Chromium](docs/static/img/banner.png)](https://navidemad.github.io/capybara-lightpanda/) Configuration · dual-driver setups · Turbo Rails · capability matrix · beta-testing guide [![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/)

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

[!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. By design it does not fetch external <link rel="stylesheet">, evaluate @media rules, or implement window.matchMedia(). Any spec whose visibility depends on responsive CSS — for example a mobile/desktop CTA pair hidden via @media (min-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

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