capybaralightpanda Capybara driver · headless
v0.16.0 open beta

v0.16.0 · public beta we want your feedback

Open source

Faster system tests for , without Chromium.

A Capybara driver that speaks CDP to Lightpanda, a headless browser built for automation. Same Capybara DSL, same page.driver surface; only the binary at the other end of the WebSocket changes.

Run your system tests on capybara-lightpanda. Stop fighting flaky Turbo Drive specs. Only the driver changes.

Source on GitHub gem on RubyGems Join the beta ↘
scroll
01

Why this engine

Not a Chromium fork. Not a WebKit patch. A new browser. lightpanda-io/browser —

Built from scratch new
Designed for the work tests actually do — automation, not browsing. No legacy of human-facing assumptions.
Zig V8 stack
Low-level systems language paired with Chrome's JavaScript engine. Native cold-start, native concurrency.
Headless by design pure
No rendering engine, no compositor — every byte spent on what your tests actually need.

Benchmarks · lightpanda.io · 933 pages · AWS m5.large

02

Drop it in

One Gemfile line, one driven_by, one env var to switch over — and you roll back by unsetting BROWSER=lightpanda. Honest numbers from a real Rails 8 suite below.

capybara-lightpanda is a Capybara driver, not a new way to write tests: same DSL, same Capybara semantics, same page.driver surface. Your specs stay as they are.

# Gemfile
group :test do
  gem "capybara-lightpanda"
end

Wire the driver in your test setup. In Rails 7+ / Rails 8 with system tests:

require "capybara-lightpanda"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :lightpanda
end

Install the browser once:

# macOS
brew install lightpanda-io/lightpanda/lightpanda

# Linux x86_64
curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
chmod +x lightpanda

Switch with BROWSER=lightpanda

Gate the driver on an env var while you try it out. Your current setup stays the default, nothing gets rewritten:

# spec/support/capybara.rb (or test/support/...)
if ENV["BROWSER"] == "lightpanda"
  require "capybara-lightpanda"

  Capybara.default_driver    = :lightpanda
  Capybara.javascript_driver = :lightpanda
else
  # your existing driver setup
end

BROWSER=lightpanda bundle exec rails test test/system/

In GitHub Actions, drop the binary in once and set the env var:

# .github/workflows/system_tests.yml
jobs:
  headless:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ruby/setup-ruby@v1
        with: { ruby-version: "3.3", bundler-cache: true }
      - name: Install Lightpanda
        run: |
          curl -sSL -o /usr/local/bin/lightpanda \
            https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
          chmod +x /usr/local/bin/lightpanda
      - run: bundle exec rails test test/system/
        env: { BROWSER: lightpanda }

page.driver — same surface

If your specs already call into page.driver (cookies, network, debug, headers), most of those calls work as you’d expect from a CDP driver:

# Cookies — same names, same shape
page.driver.set_cookie("session_id", value, domain: "127.0.0.1", httpOnly: true)
page.driver.clear_cookies
page.driver.remove_cookie("session_id")
page.driver.browser.cookies["session_id"]  # typed Cookie; the collection is Enumerable

# Navigation
page.driver.go_back
page.driver.go_forward
page.driver.refresh

# JS — Capybara's standard methods route through the V8 engine
execute_script "window.example = 'hi'"
evaluate_script "document.title"

In your test suite

Honest numbers from a Rails 8.1 app — Turbo + Stimulus, 24 DOM-only system tests on an M-series laptop:

DriverTestsTimeRSS / worker
Lightpanda24 / 246.89s ~17 MB
Chrome24 / 247.09s ~280 MB

Identical results. On a 24-test suite the wall-clock margin is small — Capybara’s own wait time dominates, just as it does on Chrome — so don’t read the 3% as “the speed claim.” The win that pays for itself is the right column:

  • Memory headroom. A 2 GB CI runner that hosts one Chromium can host 8–10 lightpanda processes. Parallelism scales where it didn’t before.
  • Cold start. No Skia, no Blink, no GPU process, no compositor — the binary is resident in milliseconds.
  • Less flake. Removing the Chromium boot removes one of the loudest sources of CI noise.

The upstream 9× / 16× numbers on this page are reproduced from lightpanda.io — a 933-page synthetic crawl on AWS m5.large. They show the ceiling at scale; the table above shows the floor on a real Rails suite.

03

Help us ship 1.0

capybara-lightpanda is in public beta. Real Rails suites are how we find the edges. The cost to try it is one Gemfile line and one env var — the cost to abandon it is unsetting that env var.

Try it in 5 minutes

  1. Add to your Gemfile, in the :test group.

    gem "capybara-lightpanda"

  2. Gate it on an env var so your existing driver stays the default.

    # spec/support/capybara.rb · or test/support/...
if ENV["BROWSER"] == "lightpanda"
  require "capybara-lightpanda"
  Capybara.javascript_driver = :lightpanda
end

  3. Run one suite. Decide.

    $ BROWSER=lightpanda bundle exec rails test test/system/

Rollback in 30 s. Drop the env var — your suite goes back to your current driver. Gemfile.lock is the only persistent change.