playwright-ruby-client 1.60.0 → 1.62.0

data/documentation/docs/api/playwright.md

@@ -11,7 +11,7 @@ to drive automation:
 ```ruby
 require 'playwright'
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   chromium = playwright.chromium # or "firefox" or "webkit".
   chromium.launch do |browser|
     page = browser.new_page
@@ -36,7 +36,7 @@ Returns a dictionary of devices to be used with [Browser#new_context](./browser#
 ```ruby
 require 'playwright'
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   iphone = playwright.devices["iPhone 6"]
   playwright.webkit.launch do |browser|
     context = browser.new_context(**iphone)

data/documentation/docs/api/touchscreen.md

@@ -19,4 +19,4 @@ def tap_point(x, y)
 
 Dispatches a `touchstart` and `touchend` event with a single touch at the position (`x`,`y`).
 
-**NOTE**: [Page#tap_point](./page#tap_point) the method will throw if `hasTouch` option of the browser context is false.
+**NOTE**: [Touchscreen#tap_point](./touchscreen#tap_point) will throw if the `hasTouch` option of the browser context is false.

data/documentation/docs/api/web_storage.md

@@ -0,0 +1,65 @@
+---
+sidebar_position: 10
+---
+
+# WebStorage
+
+
+WebStorage exposes the page's `localStorage` or `sessionStorage` for the current origin via an async,
+[browser-consistent](https://developer.mozilla.org/en-US/docs/Web/API/Storage) API.
+
+Instances are accessed through [Page#local_storage](./page#local_storage) and [Page#session_storage](./page#session_storage).
+
+```ruby
+page.goto("https://example.com")
+page.local_storage.set_item("token", "abc")
+token = page.local_storage.get_item("token")
+all = page.local_storage.items
+page.local_storage.remove_item("token")
+page.local_storage.clear
+```
+
+## items
+
+```
+def items
+```
+
+
+Returns all items in the storage as name/value pairs.
+
+## get_item
+
+```
+def get_item(name)
+```
+
+
+Returns the value for the given `name` if present.
+
+## set_item
+
+```
+def set_item(name, value)
+```
+
+
+Sets the value for the given `name`. Overwrites any existing value for that name.
+
+## remove_item
+
+```
+def remove_item(name)
+```
+
+
+Removes the item with the given `name`. No-op if the item is absent.
+
+## clear
+
+```
+def clear
+```
+
+
+Removes all items from the storage.

data/documentation/docs/article/getting_started.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 0
+description: Install playwright-ruby-client with a compatible Playwright driver and run a first Ruby browser automation script.
 ---
 
 # Getting started
@@ -11,15 +12,17 @@ gem 'playwright-ruby-client'
 Add the line above and then `bundle install`.
 
 
-Since `playwright-ruby-client` doesn't include Playwright driver nor its downloader, **we have to install Playwright in advance**
+Since `playwright-ruby-client` doesn't include Playwright, **we have to install Node.js and a compatible `playwright-core` version in advance**.
 
 ```shell
-$ npx playwright install
+$ PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'require "playwright/version"; puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION')
+$ npm install "playwright-core@$PLAYWRIGHT_CLI_VERSION"
+$ ./node_modules/.bin/playwright-core install
 ```
 
-and then set `playwright_cli_executable_path: "npx playwright"` into `Playwright.create`.
+Then set `playwright_cli_executable_path: './node_modules/.bin/playwright-core'` in `Playwright.create`.
 
-Other methods of installation are also available. See the detail in [Download Playwright driver](./guides/download_playwright_driver)
+See [Install Playwright CLI](./guides/download_playwright_driver) for details.
 
 ## Enjoy with examples
 
@@ -30,7 +33,7 @@ Navigate pages with `page.goto(url)` and save the screenshot with `page.screensh
 ```rb {6-7}
 require 'playwright'
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   playwright.chromium.launch(headless: false) do |browser|
     page = browser.new_page
     page.goto('https://github.com/YusukeIwaki')
@@ -52,7 +55,7 @@ Extract data from a site.
 ```rb {12-14,17-21}
 require 'playwright'
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   playwright.chromium.launch(headless: false) do |browser|
     page = browser.new_page
     page.goto('https://github.com/')
@@ -96,7 +99,7 @@ As an experimental feature, we can automate Chrome for Android.
 ```rb
 require 'playwright'
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   devices = playwright.android.devices
   unless devices.empty?
     device = devices.last
@@ -130,12 +133,10 @@ end
 We have to download android-driver for Playwright in advance.
 
 ```shell
-$ wget https://github.com/microsoft/playwright/raw/master/bin/android-driver-target.apk -O /path/to/playwright-driver/package/bin/android-driver-target.apk
-$ wget https://github.com/microsoft/playwright/raw/master/bin/android-driver.apk -O /path/to/playwright-driver/package/bin/android-driver.apk
+$ wget https://github.com/microsoft/playwright/raw/master/bin/android-driver-target.apk -O ./node_modules/playwright-core/bin/android-driver-target.apk
+$ wget https://github.com/microsoft/playwright/raw/master/bin/android-driver.apk -O ./node_modules/playwright-core/bin/android-driver.apk
 ```
 
-(If you downloaded Playwright via npm, replace /path/to/playwright-driver/package/ with ./node_modules/playwright/ above.)
-
 ```rb
 require 'playwright'
 

data/documentation/docs/article/guides/download_playwright_driver.md

@@ -2,15 +2,11 @@
 sidebar_position: 1
 ---
 
-# Download Playwright driver
+# Install Playwright CLI
 
-`playwright-ruby-client` doesn't include Playwright driver nor its downloader. **We have to install Playwright in advance**, and set the proper CLI path like `Playwright.create(playwright_cli_executable_path: /path/to/playwright)`
+`playwright-ruby-client` doesn't include Playwright. Install Node.js and the compatible `playwright-core` npm package in advance, then pass its CLI path to `Playwright.create`.
 
-Choose any of the three ways as you prefer to download the driver:
-
-- `npx`: suitable for playground use, and not suitable for continuous usage.
-- `npm install`: the best choice for most use cases, with existing Node.js environment.
-- Direct download: maybe a good choice for Docker :whale: integration.
+The npm package version must match `Playwright::COMPATIBLE_PLAYWRIGHT_VERSION`. Using an unversioned `npx playwright` command can install an incompatible version.
 
 :::note
 
@@ -21,35 +17,18 @@ Also the article [Playwright on Alpine Linux](./playwright_on_alpine_linux) woul
 
 :::
 
-## Using `npx`
-
-```shell
-$ npx playwright install
-```
-
-and then set `playwright_cli_executable_path: "npx playwright"` at `Playwright.create`.
-
 ## Using `npm install`
 
-Actually `npx playwright` is a bit slow. We can also use `npm install` to setup.
-
-Instead of `npx playwright install`:
-
 ```shell
-$ export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION.strip')
-$ npm install playwright@$PLAYWRIGHT_CLI_VERSION || npm install playwright@next
-$ ./node_modules/.bin/playwright install
+$ export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'require "playwright/version"; puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION')
+$ npm install "playwright-core@$PLAYWRIGHT_CLI_VERSION"
+$ ./node_modules/.bin/playwright-core install
 ```
 
-and then set `playwright_cli_executable_path: './node_modules/.bin/playwright'`
-
-## Directly download driver without Node.js installation.
+Then use the installed CLI when creating the Ruby client:
 
-Instead of npm, you can also directly download playwright driver from playwright.azureedge.net. (The URL can be easily detected from [here](https://github.com/microsoft/playwright-python/blob/cfc1030a69d1e934cac579687a680eac53d4b9ee/setup.py#L75))
-
-```shell
-$ export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION.strip')
-$ wget https://playwright.azureedge.net/builds/driver/playwright-$PLAYWRIGHT_CLI_VERSION-linux.zip
+```ruby
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
+  # ...
+end
 ```
-
-and then extract it, and set `playwright_cli_executable_path: '/path/to/playwright-$PLAYWRIGHT_CLI_VERSION-linux/node /path/to/playwright-$PLAYWRIGHT_CLI_VERSION-linux/package/cli.js'`

data/documentation/docs/article/guides/launch_browser.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 2
+description: Launch Chromium, Firefox, or WebKit from Ruby and configure browser launch options.
 ---
 
 # Launch Browser
@@ -13,7 +14,7 @@ In order to launch browser, it is required to create Playwright session.
 In previous examples,
 
 ```rb
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   # Play with `playwright` here
 end
 ```
@@ -23,7 +24,7 @@ this is the exact procedure for creating Playwright session. Choose either metho
 ### Define scoped Playwright session with block
 
 ```rb
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   # Play with `playwright` here
 end
 ```
@@ -41,7 +42,7 @@ class SomeClass
 
   def start_playwright
     # Start Playwright driver (runs `playwright run-driver` internally)
-    @playwright_exec = Playwright.create(playwright_cli_executable_path: 'npx playwright')
+    @playwright_exec = Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core')
   end
 
   def stop_playwright!
@@ -102,7 +103,7 @@ Use `Browser#new_context` to prepare a new browser window and use `BrowserContex
 Also we can use `Browser#new_page` to create a new window and new tab at once.
 
 ```rb
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   playwright.chromium.launch(headless: false) do |browser| # Chromium task icon appears.
     context = browser.new_context # Prepare new window.
     page = context.new_page # Open new window and new tab here. (about:blank)

data/documentation/docs/article/guides/playwright_on_alpine_linux.md

@@ -35,7 +35,7 @@ Playwright server is running on a container of [official Docker image](https://h
 
 ![overview](https://user-images.githubusercontent.com/11763113/124934448-ad4d0700-e03f-11eb-942e-b9f3282bb703.png)
 
-- Server can be launched with `npx playwright run-server` CLI command.
+- Server can be launched with the `playwright-core run-server` CLI command.
 - Client can connect to server with [BrowserType#connect](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). In playwright-ruby-client, `BrowserType#connect` and not implemented yet and use `Playwright#connect_to_browser_server()` instead.
 
 ### Client code
@@ -75,7 +75,7 @@ end
 
 ### Server code
 
-With the [official Docker image](https://hub.docker.com/_/microsoft-playwright) or in the local development environment with Node.js, just execute `npx playwright install && npx playwright run-server --port $PORT --path /ws`. (`$PORT` is a port number of the server)
+With the [official Docker image](https://hub.docker.com/_/microsoft-playwright) or in the local development environment with Node.js, install a matching `playwright-core` package and use its local CLI. (`$PORT` is a port number of the server.)
 
 If custom Docker image is preferred, build it as follows:
 
@@ -83,10 +83,11 @@ If custom Docker image is preferred, build it as follows:
 FROM mcr.microsoft.com/playwright
 
 WORKDIR /root
-RUN npm install playwright && ./node_modules/.bin/playwright install
+ARG PLAYWRIGHT_CORE_VERSION=1.62.1
+RUN npm install "playwright-core@$PLAYWRIGHT_CORE_VERSION" && ./node_modules/.bin/playwright-core install
 
 ENV PORT 8888
-CMD ["./node_modules/.bin/playwright", "run-server", "--port", "$PORT", "--path", "/ws"]
+CMD ["./node_modules/.bin/playwright-core", "run-server", "--port", "$PORT", "--path", "/ws"]
 ```
 
 ## Debugging for connection
@@ -106,7 +107,7 @@ DEBUG=1 bundle exec ruby some-automation-with-playwright.rb
 Just set an environment variable `DEBUG=pw:*` or `DEBUG=pw:server`
 
 ```
-DEBUG=pw:* npx playwright run-server --browser chromium
+DEBUG=pw:* ./node_modules/.bin/playwright-core run-server --browser chromium
 ```
 
 See [the official documentation](https://playwright.dev/docs/debug/#verbose-api-logs) for details.

data/documentation/docs/article/guides/rails_integration.md

@@ -45,7 +45,7 @@ If Playwright is running in an independent container, with docker-compose.yaml c
   playwright: # this is our PLAYWRIGHT_HOST value
     image: mcr.microsoft.com/playwright:v1.57.0-noble
     command: >
-      /bin/sh -c "npx -y playwright@1.57.0 run-server --port 3000 --host 0.0.0.0 --path /ws"
+      /bin/sh -c "npm install --no-save playwright-core@1.57.0 && ./node_modules/.bin/playwright-core run-server --port 3000 --host 0.0.0.0 --path /ws"
     init: true
     restart: unless-stopped
 ```
@@ -144,8 +144,8 @@ These parameters can be passed into `Capybara::Playwright::Driver.new`
 
 ```ruby
 driver_opts = {
-  # `playwright` command path.
-  playwright_cli_executable_path: './node_modules/.bin/playwright',
+  # `playwright-core` command path.
+  playwright_cli_executable_path: './node_modules/.bin/playwright-core',
 
   # Use firefox for testing.
   browser_type: :firefox,
@@ -264,7 +264,7 @@ This example code would attach the trace zip file to Allure report for each test
 We can download and show the trace with `playwright show-trace` command.
 
 ```
-npx playwright show-trace ababcdcdefef.zip
+./node_modules/.bin/playwright-core show-trace ababcdcdefef.zip
 ```
 
 ![show-trace image](https://user-images.githubusercontent.com/11763113/282307098-a4167c32-d5e7-4631-a3b6-62d278efbeef.png)
@@ -276,3 +276,71 @@ Instead of the easy configuration using `on_save_trace`, we can also use `page.d
 - Playwright doesn't allow clicking invisible DOM elements or moving elements. `click` sometimes doesn't work as Selenium does. See the detail in https://playwright.dev/docs/actionability/
 - `current_window.maximize` and `current_window.fullscreen` work only on headful (non-headless) mode, as selenium driver does.
 - `Capybara::Node::Element#drag_to` does not accept `html5` parameter. HTML5 drag and drop is not fully supported in Playwright.
+
+#### Selenium migration incompatibilities
+
+Some Selenium-backed Capybara behavior depends on WebDriver implementation details or accepts patterns outside Capybara's documented API. `capybara-playwright-driver` does not try to emulate these Selenium-specific behaviors when they conflict with Playwright's actionability, dialog, or rendered text model.
+
+##### Modal dialogs must be handled before the action that opens them
+
+Use Capybara's block-oriented modal API:
+
+```ruby
+accept_alert('message') do
+  click_button 'Open alert'
+end
+
+accept_confirm('Are you sure?') do
+  click_button 'Delete'
+end
+```
+
+Selenium-backed Capybara may sometimes handle an already-open modal after the action has returned:
+
+```ruby
+click_button 'Delete'
+accept_confirm('Are you sure?')
+```
+
+This pattern is not portable to Playwright. In Playwright, the action that opens a JavaScript dialog does not complete until the dialog is handled, so the driver cannot wait for later Ruby code to call `accept_alert`, `accept_confirm`, or another modal helper.
+
+Wrap the action that opens the dialog in `accept_alert`, `accept_confirm`, `dismiss_confirm`, `accept_prompt`, or `dismiss_prompt`.
+
+##### Clicking a disabled element waits for actionability
+
+Selenium-backed Capybara may return from a second click on an already-disabled button without changing the page. Playwright waits for the element to become actionable, then times out. This is expected Playwright behavior, and commonly appears in migration work around double-submit prevention tests.
+
+Instead of attempting a second click on a disabled control, assert the disabled state and the expected result:
+
+```ruby
+expect(button).to be_disabled
+expect(page).to have_text('submitted')
+```
+
+Alternatively, assert the relevant server or client state directly.
+
+##### Visible text follows rendered `innerText` behavior
+
+When a `<br>` is hidden with CSS, Selenium-backed Capybara may still preserve a newline in text extraction. Playwright follows the browser's rendered `innerText` behavior: a hidden `<br>` does not create a rendered line break.
+
+For example:
+
+```html
+<p>not submitted.<br class="hidden">click submit.</p>
+```
+
+If the `<br>` is hidden with `display: none`, Playwright-style visible text is:
+
+```ruby
+"not submitted.click submit."
+```
+
+not:
+
+```ruby
+"not submitted.\nclick submit."
+```
+
+Avoid newline-sensitive expectations around responsive or hidden line break elements, or assert the browser-rendered text that users actually see.
+
+These examples are not exhaustive. If you find another Capybara/Selenium migration incompatibility, please open an issue at [capybara-playwright-driver issues](https://github.com/YusukeIwaki/capybara-playwright-driver/issues) with the reproduction HTML and the Ruby/Capybara code that reproduces it.

data/documentation/docs/article/guides/rails_integration_with_null_driver.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 4
+description: Use native Playwright APIs in Rails system tests while retaining Capybara only for test server lifecycle management.
 ---
 
 # Use Capybara without DSL
@@ -56,7 +57,7 @@ RSpec.configure do |config|
     # Rails server is launched here, at the first time of accessing Capybara.current_session.server
     base_url = Capybara.current_session.server.base_url
 
-    Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+    Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
       # pass any option for Playwright#launch and Browser#new_page as you prefer.
       playwright.chromium.launch(headless: false) do |browser|
         @playwright_page = browser.new_page(baseURL: base_url)
@@ -98,7 +99,7 @@ module PlaywrightBrowser
 
     def start!
       @fiber = Fiber.new do
-        Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+        Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
           playwright.chromium.launch(headless: false) do |browser|
             Fiber.yield(browser)
           end
@@ -152,7 +153,7 @@ class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
   driven_by :null
 
   def self.playwright
-    @playwright ||= Playwright.create(playwright_cli_executable_path: Rails.root.join("node_modules/.bin/playwright"))
+    @playwright ||= Playwright.create(playwright_cli_executable_path: Rails.root.join("node_modules/.bin/playwright-core"))
   end
   
   def before_setup

data/documentation/docs/article/guides/semi_automation.md

@@ -54,7 +54,7 @@ We have to enable it for installing Chrome extension, by passing these 3 paramet
 require 'playwright'
 require 'pry'
 
-Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   launch_params = {
     acceptDownloads: true,
     channel: 'chrome',

data/documentation/docs/article/guides/use_storage_state.md

@@ -24,7 +24,7 @@ require 'pry'
 
 force_login = !File.exist?('github_state.json')
 
-Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright-core') do |playwright|
   if force_login
     # Use headful mode for manual operation.
     playwright.chromium.launch(headless: false, channel: 'chrome') do |browser|

data/documentation/docs/include/api_coverage.md

@@ -365,6 +365,8 @@
 * ~~wait_for_event~~
 * clock
 * keyboard
+* local_storage
+* session_storage
 * mouse
 * request
 * screencast
@@ -405,6 +407,7 @@
 * expect_page
 * ~~wait_for_event~~
 * clock
+* credentials
 * ~~debugger~~
 * request
 * tracing
@@ -528,6 +531,7 @@
 * type
 * uncheck
 * wait_for
+* wait_for_function
 
 ## FrameLocator
 
@@ -553,9 +557,12 @@
 * headers_array
 * json
 * ok
+* security_details
+* server_addr
 * status
 * status_text
 * text
+* timing
 * url
 
 ## APIRequestContext
@@ -638,3 +645,18 @@
 * not_to_match_aria_snapshot
 * to_have_title
 * to_have_url
+
+## WebStorage
+
+* items
+* get_item
+* set_item
+* remove_item
+* clear
+
+## Credentials
+
+* install
+* create
+* delete
+* get

data/documentation/docusaurus.config.js

@@ -9,6 +9,37 @@ module.exports = {
   favicon: 'img/playwright-logo.svg',
   organizationName: 'YusukeIwaki', // Usually your GitHub org/user name.
   projectName: 'playwright-ruby-client', // Usually your repo name.
+  plugins: [
+    [
+      'docusaurus-plugin-llms',
+      {
+        generateLLMsTxt: true,
+        generateLLMsFullTxt: false,
+        generateMarkdownFiles: true,
+        docsDir: 'docs',
+        title: 'playwright-ruby-client',
+        description: 'Ruby client for Playwright, including API reference and integration guides.',
+        rootContent: `This is a community-maintained Ruby client for Playwright.
+
+Important usage notes:
+- The gem does not include Node.js or Playwright. Install the compatible \`playwright-core\` npm package separately and pass \`node_modules/.bin/playwright-core\` to \`Playwright.create\`.
+- Determine the compatible Playwright version from \`Playwright::COMPATIBLE_PLAYWRIGHT_VERSION\`; do not assume the newest npm package is compatible.
+- Use playwright-ruby-client for native Playwright APIs. Use capybara-playwright-driver when compatibility with the Capybara DSL is more important.
+- Prefer the Ruby examples and signatures in this documentation over examples for other Playwright language bindings.`,
+        includeOrder: [
+          'article/getting_started.md',
+          'article/guides/**/*.md',
+          'api/playwright.md',
+          'api/**/*.md',
+          'article/api_coverage.mdx',
+        ],
+        includeUnmatchedLast: true,
+        ignoreFiles: ['include/**'],
+        excludeImports: true,
+        removeDuplicateHeadings: true,
+      },
+    ],
+  ],
   themeConfig: {
     image: 'img/playwright-ruby-client.png',
     navbar: {

data/documentation/package.json

@@ -35,5 +35,8 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "devDependencies": {
+    "docusaurus-plugin-llms": "0.5.0"
   }
 }