playwright-ruby-client 1.61.0 → 1.62.0

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

@@ -531,6 +531,7 @@
 * type
 * uncheck
 * wait_for
+* wait_for_function
 
 ## FrameLocator
 
@@ -561,6 +562,7 @@
 * status
 * status_text
 * text
+* timing
 * url
 
 ## APIRequestContext

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"
   }
 }