Skip to content

Playwright in Ruby: Setup, Scraping, and Rails System Tests

Microsoft does not publish a Ruby Playwright client. Ruby teams use the community-maintained playwright-ruby-client gem, which drives the Node.js Playwright engine through a Ruby API. This guide walks through installing that gem and its Node driver, scraping a JavaScript-rendered product listing, saving and reloading browser state, handling errors, and switching Rails system tests from Selenium to the Capybara Playwright driver. It also explains when a managed scraping API is a better fit than running your own browser fleet.

What Playwright in Ruby actually is

Playwright itself is a browser automation library. The Ruby client is a wrapper: your Ruby code calls the gem, and the gem talks to the Node.js Playwright driver, which launches and controls Chromium, Firefox, or WebKit. That architecture has two practical consequences. First, Node.js is normally required on the machine that runs the Ruby code, because the gem does not bundle the driver. Second, the gem targets a specific Playwright release, so the npm package version must match the gem's expected version or the driver will fail at runtime.

The gem is maintained by Yusuke Iwaki and tracks upstream Playwright releases. It is not an official Microsoft package. For local automation, Rails system tests, and moderate scraping, it is a reliable option. For long-lived critical systems, weigh the single-maintainer risk before adopting it.

A quick decision checklist:

  • Need direct browser control, Rails system tests, or small-to-medium scraping? Use playwright-ruby-client.
  • Cannot install browsers on the app host? Run a Playwright server elsewhere and connect over WebSocket.
  • Need large-scale collection with proxy rotation and anti-bot handling? Use a managed scraping API instead of maintaining a browser fleet.
  • Replacing Selenium in an existing Capybara suite? Use capybara-playwright-driver and keep your Capybara DSL.

Install the gem and the Node driver

Assume Ruby 2.4+ and a current Node.js LTS release are available. Add the gem to your Gemfile, install it, add the Node Playwright package, and download the browser binaries. The Ruby client needs to know where the Playwright CLI lives; pass that path through playwright_cli_executable_path when creating the Playwright instance.

A minimal smoke test launches Chromium, opens a page, prints the title, and closes the browser. If the title matches the target page, the wiring is correct.

The exact Gemfile line, bundle command, npm command, browser-install command, and smoke-test script are provided as protected code modules (code0001 through code0006). Use them verbatim; do not substitute package names or paths.

Note on the manual driver-download path: as of July 2026, the documented method for avoiding a local Node.js install was reported not to work. Treat Node.js as a required local dependency unless you use the remote-server approach below.

Alternative: connect to a remote Playwright server

If browsers cannot be installed where your Ruby code runs, start a Playwright server on a separate machine or container and connect to it over WebSocket. The Ruby side needs the websocket-driver gem in addition to playwright-ruby-client. When you connect this way, you do not set playwright_cli_executable_path; the Ruby client talks to the remote server instead of a local driver.

Node.js still has to run on the server that hosts the Playwright server. The remote approach removes Node from the Ruby host, not from the system as a whole.

The server-start commands, Gemfile addition, bundle command, and WebSocket connection script are provided as protected code modules (code0007 through code0010).

Pin the compatible Playwright version

The most common setup failure is a mismatch between the gem's expected Playwright release and the npm package you installed. The gem exposes Playwright::COMPATIBLE_PLAYWRIGHT_VERSION; read that constant and install the matching npm version, then download the browsers. Doing this in CI prevents a new upstream Playwright release from breaking builds overnight.

The pinning commands are provided as protected code module code0011. Keep the gem version and the npm version locked together in your lockfiles and CI cache keys.

Scrape a JavaScript-rendered page step by step

The walkthrough uses a public Zara product listing as the target. Check the site's terms of service and scrape only public data responsibly.

A Playwright script has three layers: a browser process, a browser context (an isolated session with its own cookies, storage, and settings), and a page (a tab). The launch, context, and page steps are shown in protected code module code0012. By default, chromium.launch() runs headless; the example runs headful because the target site is known to block headless sessions.

page.goto() accepts waitUntil. Setting it to domcontentloaded makes Playwright wait for the DOMContentLoaded event, which fires after the initial HTML is parsed. That is usually the right choice for pages that keep loading data after the document is ready.

Locators and auto-waiting

A locator is a lazy reference to a selector. Playwright resolves it when an action or read is performed, which is why locators survive asynchronous rendering better than eager element handles. The product cards in the example are selected with li.product-grid-product (protected code module code0013). If you need every matching element immediately, query_selector_all() returns ElementHandle objects (code0014).

Locators are preferred for dynamic pages. When you call an action such as products.first.click (code0015), Playwright runs actionability checks first: the element must be visible, stable, able to receive pointer events, and enabled. Those checks remove many of the explicit waits that Selenium scripts need, and they are a major reason Playwright scripts tend to be less flaky.

Scroll to load dynamic content

Infinite-scroll pages fetch more data after the initial load. You can trigger that with page.evaluate running window.scrollTo(0, document.body.scrollHeight) (code0016), then wait for the new content to appear. In the example, newly loaded cards carry a data-pagenum attribute set to the fetched page number; waiting for li.product-grid-product[data-pagenum='2'] with a 5-second timeout (code0017) is more reliable than a fixed sleep.

Avoid page.wait_for_load_state("networkidle") as a general strategy. Modern sites keep background requests open, so networkidle can take much longer than expected or never resolve. Waiting for the specific selector your scraper needs is more reliable. The scroll-and-wait loop is provided as protected code module code0018.

Extract fields and export to CSV

Each product card exposes three useful fields. The field map below reflects the selectors used in the walkthrough.

  • Product URL: href attribute of a.product-link
  • Product name: text of the <h3> element
  • Current price: text of .price-current__amount

The extraction loop builds one Ruby hash per product (protected code module code0019), prints them for inspection (code0020), and writes them to a CSV using Ruby's built-in csv library (code0021). The combined scraper is code0022. That combined script collects only the first page of results; add the scroll loop from the previous section to reach more products.

Running headless against this target is likely to be blocked immediately. The approach works for small jobs but is not suitable for large-scale scraping. If you need scale without orchestrating browsers and proxies yourself, a managed scraping API is the usual recommendation.

Take screenshots

page.screenshot with a path captures the visible viewport (code0023). Add fullPage: true to capture the whole document, including content outside the viewport (code0024). Screenshots are useful for visual regression checks, competitor monitoring, and debugging failed runs.

Reuse a session with saved browser state

A browser context holds cookies, local storage, and other session data. Saving that state lets later runs skip setup steps, including dismissing pop-ups that only appear on first visit.

The example target shows a text-message signup modal inside an iframe. Regular locators search only the main document, so the close button is reached with page.frame_locator("#attentive_creative").locator("#closeIconContainer") (code0025). Wrapping the dismissal in begin/rescue keeps the scraper running when the modal does not appear, since pop-ups can depend on cookies, prior sessions, location, or timing.

After dismissal, context.storage_state(path: "zara-session.json") writes the state to disk (code0026). On later runs, pass storageState: "zara-session.json" to browser.new_context (code0027). The same pattern works for authenticated apps and cookie-consent flows.

Handle errors without stopping the job

When scraping many pages, wrap navigation and extraction in error handling so a single timeout or page change does not end the run. Rescue Playwright::Error to catch navigation timeouts and failed browser operations, log the failure, and continue (code0028). For temporary failures, add a retry loop with a short backoff (code0029).

For production runs, also consider blocking unnecessary resources such as images and fonts, and running multiple browser sessions in parallel. Those techniques reduce time and cost but add operational complexity.

Use Playwright for Rails system tests

Most Capybara setups use Selenium as the browser driver. capybara-playwright-driver lets you swap in Playwright while keeping your existing Capybara test suite. Playwright's actionability checks remove many sources of flaky system tests; one widely shared Ruby developer report describes a drop from roughly 30% failures under Selenium to under 5% after switching. Treat that figure as a single reported experience, not a guarantee.

Add capybara-playwright-driver to the :test group (code0030), run bundle install (code0031), and register the driver in spec/support/capybara.rb (code0032). Rails 6.1+ reserves the :playwright driver name for its built-in integration, so register the Capybara Playwright driver under a custom name such as :customized_playwright. Then load the support file from spec/rails_helper.rb and set driven_by :customized_playwright for system specs (code0033).

With the driver configured, system tests are written in ordinary Capybara style (code0034) and run with bundle exec rspec spec/system/ (code0035).

Limitations of capybara-playwright-driver

The driver is a Capybara wrapper, not the full Playwright API. Three limitations matter in practice:

  • Rails 5.x and 6.0 still expect the selenium-webdriver gem to be installed even when Playwright is the active driver. If setup fails on dependencies, keep selenium-webdriver in the Gemfile but keep using the Playwright driver for tests.
  • Most Capybara DSL methods are supported, but low-level page APIs and Playwright-native methods are only reachable through with_playwright_page or by using playwright-ruby-client directly.
  • Playwright enforces stricter actionability rules than Selenium. It will not click hidden or disabled elements, and some Selenium-specific patterns, such as handling a dialog after the click that opens it, must be rewritten to follow Playwright's execution model.

Reduce blocking when scraping

A Playwright-controlled headless browser exposes automation signals: default viewport and locale, a distinctive User-Agent, and other environment differences. To reduce those cues, set a realistic user-agent, viewport, locale, and timezone on the browser context (code0036). Prefer persistent contexts over a fresh session per request, and add realistic delays between actions. More protected sites may require rotating residential proxies.

No DIY technique guarantees bypass of every anti-bot system. Modern defenses analyze mouse behavior, network patterns, and IP reputation, and they can still block requests or serve CAPTCHAs. Maintaining browser instances, the Node driver, proxies, and detection adaptations is significant operational overhead at scale.

A managed web scraping API handles JavaScript rendering, anti-bot challenges, and proxy rotation behind a single endpoint that any Ruby HTTP client can call. That is a practical alternative when scale or maintenance cost outweighs the need for direct browser control.

Playwright Ruby or a scraping API: which to use

Playwright is not the only way to drive a browser from Ruby, so the choice is really about how much control you need versus how much runtime you want to own.

Among the Ruby headless browser automation tools, Ferrum stands out as a native Ruby option: because it does not depend on Node.js, its setup is simpler. What you give up is capability — it does not reach Playwright's level of features. Selenium, meanwhile, remains a popular and well-documented choice in Ruby, but it asks you to handle waits and actionability checks more manually, which is a common source of flaky tests.

Against those options, playwright-ruby-client is the strongest fit when you want direct browser control for local automation, Rails system tests, or small-to-medium scraping, and you are willing to manage the Node runtime, browser binaries, and Playwright updates. A managed scraping API wins when you need to collect data at scale or would rather not run browsers, proxies, and anti-bot handling yourself. In that model, your Ruby app sends HTTP requests and the scraping infrastructure runs separately.

Product card field map used in the walkthrough
FieldSelector / attributeRead method
Product URLa.product-linkget_attribute("href")
Product name<h3>text_content.strip
Current price.price-current__amounttext_content.strip

Selectors reflect the target page at the time of the walkthrough; verify against the live DOM before reuse.

Common failure signatures and first checks
SymptomLikely causeFirst check
Driver fails at startupGem and npm Playwright versions differRead Playwright::COMPATIBLE_PLAYWRIGHT_VERSION and reinstall npm package
Browser cannot launchplaywright_cli_executable_path missing or wrongConfirm path to ./node_modules/.bin/playwright
Immediate block on target siteHeadless session detectedTry headful mode; review anti-bot guidance
Selector never resolvesContent not loaded or selector changedWait for a specific selector; inspect DOM
Close button not foundElement inside an iframeUse page.frame_locator on the iframe
Dependency error in Rails testsOlder Rails expects selenium-webdriverKeep selenium-webdriver in Gemfile; use Playwright driver

Diagnostic guidance derived from the walkthrough; not a substitute for reading the actual error message.

Frequently asked questions

Is Playwright available in Ruby?

Not officially. Microsoft maintains Playwright clients for Node.js, Python, Java, and .NET, and has not announced a native Ruby library. Ruby support comes from the community-maintained playwright-ruby-client gem, which provides a Ruby API over the Node.js Playwright engine.

Is playwright-ruby-client official?

No. It is a community gem maintained by Yusuke Iwaki that tracks Playwright releases and provides Ruby bindings. Because it is a single-maintainer project, consider that when choosing it for long-lived critical systems.

Do I need Node.js to use Playwright in Ruby?

Usually yes. The gem does not bundle the Playwright driver, so you install the Node.js Playwright package and browser binaries separately. You can keep Node.js off the Ruby host by connecting to a remote Playwright server, but Node.js still runs on that server.

Playwright vs Selenium in Ruby: which is better?

For new Ruby browser-automation projects, Playwright is generally the better choice because built-in auto-waiting and actionability checks reduce stale-element flakiness. Selenium is officially supported and widely documented in Ruby, so it remains a reasonable default for existing suites.

Can I use Playwright for Rails system tests?

Yes, through capybara-playwright-driver, which provides a Capybara driver for RSpec or Minitest system tests. Because it is a Capybara wrapper, some Playwright features require using playwright-ruby-client directly, and some older Rails setups still require the selenium-webdriver gem to be present.

How do I keep the gem and Node driver versions in sync?

Pin them together. The gem targets a specific Playwright release, and installing a different npm version can cause compatibility problems. Use Playwright::COMPATIBLE_PLAYWRIGHT_VERSION to install the matching npm package, especially in CI/CD pipelines.