Venetian

Want stable system tests with Playwright, but don't want a Heath Robinson/Rube Goldberg setup in CI to try to keep the Ruby gem and Node package in sync? This gem packages a Node executable plus the common Playwright package, in the same way Playwright is packaged for other languages.

Install the gem and add to the application's Gemfile by executing:

bundle add venetian --group test

In your system test case, choose the Playwright driver. Venetian will provide the base command to run Playwright, which you can still override by passing :playwright_cli_executable_path, and this plus any other options will be passed through to capybara-playwright-driver.

require "test_helper"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :playwright
end

Likewise, register the Playwright driver before using it later:

Capybara.register_driver :playwright do |app|
  Capybara::Playwright::Driver.new(app)
end

Require the Capybara-free entry point instead, either in your Gemfile if you use Bundler.require:

gem "venetian", require: "venetian/playwright"

Or directly:

require "venetian/playwright"

Then use Venetian.start in place of Playwright.create. It takes the same arguments, with the bundled executable as the default :playwright_cli_executable_path. Browsers aren't installed automatically here, so install them first, either with the Rake task or Venetian::BrowserInstaller.install:

Venetian::BrowserInstaller.install(:chromium)

Venetian.start do |playwright|
  playwright.chromium.launch do |browser|
    # ...
  end
end

With Capybara or Rails system tests, the gem will automatically install a browser and dependencies for you before attempting to use it. Browsers are installed to $XDG_CACHE_HOME/ms-playwright on Linux, ~/Library/Caches/ms-playwright on macOS, and %LOCALAPPDATA%\ms-playwright on Windows. In CI, you will want to cache this directory to avoid downloads on every run.

On Linux, Playwright currently only officially supports Debian and Ubuntu due to e.g. differences between package managers and package names across distros, so dependency installation happens only if a compatible package manager is found. Depending on what you're doing, you may not need to install dependencies, but if you do and your distro is unsupported, you will need to work out what you need and deal with that first. On Windows, Firefox also needs the Microsoft Visual C++ Redistributable, which Playwright doesn't install; you'll get a warning after installation if it's missing.

Browsers already installed (e.g. from a restored cache) are left alone. If the browsers directory (or PLAYWRIGHT_BROWSERS_PATH, if set) is read-only, as with a prepopulated cache, browsers aren't installed at all, since Playwright can't take its lock there, though dependencies still are if needed. When parallelizing tests, there's also the issue of multiple processes all trying to acquire the package manager lock, so installations are serialized across processes. On top of this, if you use Rails system tests with ActionDispatch::SystemTestCase, all required browsers are installed before disabling auto-installation and then forking.

Browsers aren't installed automatically if you pass your own :playwright_cli_executable_path, or connect to a server with :playwright_server_endpoint_url or :browser_server_endpoint_url, since the bundled executable won't be the one running them. Nor are they if you pass :executablePath, or a :channel for a system-wide browser like chrome or msedge (install these with e.g. playwright install chrome), but other channels are installed instead of the browser type. You can also turn installation off with Venetian.auto_install_browsers = false, or just dependency installation with Venetian.auto_install_dependencies = false.

If you can't rely on automatic installation, you can use the included Rake task to install browsers. With Rails this is included automatically when venetian is required (but not venetian/playwright).

$ RAILS_ENV=test rails venetian:install

# Or a specific browser
$ RAILS_ENV=test rails venetian:install[firefox]

Otherwise in your Rakefile add:

load "tasks/venetian.rake"

And then run:

$ rake venetian:install

The gem provides a playwright executable which you can use to run Playwright yourself.

$ playwright --version 
Version 1.61.1

The bundled Node has its own OpenSSL and certificate authorities, which can lag behind your system's, e.g. when a certificate authority is distrusted. So Venetian runs Node with --use-openssl-ca, pointing it at the certificate authorities Ruby's OpenSSL uses (OpenSSL::X509::DEFAULT_CERT_FILE and DEFAULT_CERT_DIR, or SSL_CERT_FILE and SSL_CERT_DIR if set). Playwright then trusts what e.g. Net::HTTP does, such as a corporate proxy's certificate authority installed on your system, and nothing more. To use Node's bundled certificate authorities instead, set VENETIAN_BUNDLED_CA=1. Venetian also leaves Node's certificate authorities alone if you've chosen them with --use-bundled-ca or --use-system-ca in NODE_OPTIONS, or with NODE_USE_SYSTEM_CA=1, as the bundled Node won't combine those with --use-openssl-ca. NODE_EXTRA_CA_CERTS works as usual either way.

Noisy output during a test run is often frustrating, so the gem is quiet by default. You can get more output with VENETIAN_DEBUG=1.

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/jmalcic/venetian. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Venetian project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.