Capybara Playwright Driver

https://github.com/yusukeiwaki/capybara-playwright-driver
Admin
A Capybara driver that integrates Playwright, making it easy to introduce Playwright for browser...
Tokens:62,327
Snippets:495
Trust Score:9.2
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example: open, switch, resize, and close a new window

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Shows a typical workflow: open a new window, switch to it, get its size, resize it, and close it. Uses the driver's window methods with the page GUID.

```ruby
new_window = session.open_new_window(:window)
session.driver.switch_to_window(new_window.guid)
session.driver.window_size(new_window.guid)      # => [width, height]
session.driver.resize_window_to(new_window.guid, 1024, 768)
session.driver.close_window(new_window.guid)

```

--------------------------------

### Prepare to run tests

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/README.md

Install dependencies and install the Playwright browser with dependencies.

```bash
bundle install
export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'require "playwright"; puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION.strip')
npm install playwright@${PLAYWRIGHT_CLI_VERSION}
./node_modules/.bin/playwright install --with-deps
```

--------------------------------

### Example: including TmpdirOwner and calling tmpdir

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/tmpdir-owner.md

Shows how to include the TmpdirOwner mixin in a class and call tmpdir to get a temporary directory path. The comment shows an example return value.

```ruby
class MyRecorder
  include Capybara::Playwright::TmpdirOwner
end

recorder = MyRecorder.new
recorder.tmpdir # => "/tmp/d20241014-..."
```

--------------------------------

### Frame stack usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Shows how to get the current frame and navigate. Note: driven by Browser#switch_to_frame; rarely called directly.

```ruby
# Driven by Browser#switch_to_frame; rarely called directly.
page.capybara_current_frame.goto(url)
```

--------------------------------

### Example: Get shadow root node from host element

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/shadow-root-node.md

Shows how to obtain a ShadowRootNode from a host element using page.find and shadow_root.

```ruby
host = page.find('#my-component')
shadow = host.shadow_root
# shadow is a Capybara::Playwright::ShadowRootNode
```

--------------------------------

### Raw screenshot and video path example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Shows how to get the raw screenshot binary and video path using the browser's public helpers. Note that 'browser' is private on Driver; the canonical public path is via with_playwright_page or on_save_* callbacks.

```ruby
# Raw binary + video path (user-facing helpers)
binary = page.driver.browser.raw_screenshot
path = page.driver.browser.video_path

```

--------------------------------

### Script execution example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Example usage of evaluate_script, execute_script, and evaluate_async_script with their return values.

```ruby
page.driver.evaluate_script('document.title')                 # => String
page.driver.execute_script('document.body.style.background = "red"')  # => nil
page.driver.evaluate_async_script('(done) => setTimeout(() => done(42), 100)') # => 42
```

--------------------------------

### PageOptions usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/options.md

Shows how to instantiate PageOptions and filter options. The output includes acceptDownloads: true.

```ruby
opts = Capybara::Playwright::PageOptions.new(viewport: { width: 800, height: 600 }, locale: 'en-US')
opts.value
# => { viewport: { width: 800, height: 600 }, locale: 'en-US', acceptDownloads: true }
```

--------------------------------

### BrowserOptions usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/options.md

Shows how to instantiate BrowserOptions and filter options. The output is { headless: false, slowMo: 50 }.

```ruby
opts = Capybara::Playwright::BrowserOptions.new(headless: false, slowMo: 50, unknown_key: 1)
opts.value # => { headless: false, slowMo: 50 }
```

--------------------------------

### Example: accept_modal and dismiss_modal usage

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Shows how to use the driver's accept_modal and dismiss_modal methods with blocks that trigger the dialog.

```ruby
page.driver.accept_modal(:prompt, with: 'answer', text: /Enter name/) do
  click_button 'Show prompt'
end

page.driver.dismiss_modal(:confirm) do
  click_button 'Remove'
end
```

--------------------------------

### BrowserRunner#start

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Initializes the Playwright execution and returns the launched or connected Playwright::Browser instance.

```APIDOC
## BrowserRunner#start

### Description
Initializes the Playwright execution and returns the launched or connected `Playwright::Browser` instance.

### Method
start

### Signature
```ruby
def start
```

### Return Value
- **::Playwright::Browser** - The launched or connected browser instance.

### Example
```ruby
browser = runner.start   # => Playwright::Browser
```
```

--------------------------------

### BrowserRunner usage example through Driver lifecycle

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Shows how BrowserRunner is normally used indirectly via Driver#create_playwright_browser and Driver#quit. Creates a runner with browser_type and headless options, starts it to get a Playwright::Browser, then stops it.

```ruby
# Normally never used directly — Driver#create_playwright_browser calls
# @browser_runner.start, and Driver#quit calls @browser_runner.stop at exit.
runner = Capybara::Playwright::BrowserRunner.new(browser_type: :firefox, headless: true)
browser = runner.start   # => Playwright::Browser
runner.stop
```

--------------------------------

### trace usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Example of using the trace method with screenshots, snapshots, and a path to save the trace zip.

```ruby
page.driver.trace(name: 'my_trace', screenshots: true, snapshots: true, path: 'tmp/trace.zip') do
  visit '/'
  click_on 'Go'
end
```

--------------------------------

### drop usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Shows how to drop a file path or a hash-array of data items onto a drop target.

```ruby
drop_target.drop('/tmp/a.txt')
drop_target.drop([{ 'text/plain' => 'hello' }])
```

--------------------------------

### BrowserRunner#start

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Initializes the Playwright execution and returns the launched or connected Playwright::Browser.

```ruby
# @return [::Playwright::Browser]
def start
  @playwright_execution = @runner.playwright_execution
  @runner.playwright_browser
end
```

--------------------------------

### Register and use Playwright driver with Capybara

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/README.md

Complete setup and usage example: registers the :playwright driver with Firefox, sets Capybara defaults, visits GitHub, searches for 'Capybara', and demonstrates both Capybara DSL and Playwright-native selectors/actions.

```ruby
require 'capybara-playwright-driver'

# setup
Capybara.register_driver(:playwright) do |app|
  Capybara::Playwright::Driver.new(app, browser_type: :firefox, headless: false)
end
Capybara.default_max_wait_time = 15
Capybara.default_driver = :playwright
Capybara.save_path = 'tmp/capybara'

# run
Capybara.app_host = 'https://github.com'
visit '/'
find('button[aria-label^="Search or jump to"]').click
search_field = find('input[aria-label="Search or jump to"]')
search_field.fill_in(with: 'Capybara')

## [REMARK] We can use Playwright-native selector and action, instead of Capybara DSL.
# search_field.send_keys(:enter)
page.driver.with_playwright_page do |page|
  page.get_by_label('Search or jump to', exact: true).press('Enter')
end

all('[data-testid="results-list"] h3').each do |li|
  #puts "#{li.all('a').first.text} by Capybara"
  puts "#{li.with_playwright_element_handle { |handle| handle.text_content }} by Playwright"
end
```

--------------------------------

### Example: Using all_text and visible_text

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/shadow-root-node.md

Shows how to call all_text and visible_text on a ShadowRootNode, with expected return values.

```ruby
shadow = page.find('#my-component').shadow_root
shadow.all_text          # => "All text inside the shadow DOM"
shadow.visible_text      # => visible text or ""
```

--------------------------------

### PutsLogger usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver.md

Shows how to instantiate PutsLogger and call info and warn methods, with expected output shown in comments.

```ruby
logger = Capybara::Playwright::Driver::PutsLogger.new
logger.info('starting')  # => "[INFO] starting"
logger.warn('careful')   # => "[WARNING] careful"
```

--------------------------------

### Example: on_save_raw_screenshot_before_reset usage

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Example usage of on_save_raw_screenshot_before_reset to save the raw screenshot binary to a file. The block receives the raw screenshot data as a String.

```ruby
page.driver.on_save_raw_screenshot_before_reset do |raw|
  File.binwrite("screenshots/#{Time.now.to_i}.png", raw)
end
```

--------------------------------

### Example: trigger('input') on element

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Example usage of the trigger method to dispatch an 'input' event on a found element.

```ruby
page.find('#my-input').trigger('input')
```

--------------------------------

### Example: calling remove_tmpdir

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/tmpdir-owner.md

Example call to remove_tmpdir on a recorder instance, with a comment noting the directory is deleted and the finalizer is cleared.

```ruby
recorder.remove_tmpdir   # directory deleted, finalizer cleared
```

--------------------------------

### Example of setting values on different input types

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Shows how to use `set` on various elements: text fields, date inputs, file inputs, and multi-selects. The comments indicate the strategy used for each type.

```ruby
field = page.find('#name')
field.set('Alice')
field.set('Bob', clear: :backspace)
date_input.set(Date.new(2024, 1, 15))     # DateInput → iso8601
file_input.set('/path/to/file.txt')        # FileUpload
select.set(['a', 'b'])                     # multi-select → Array
```

--------------------------------

### Click actions example usage

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Shows how to use click, right_click, and double_click with modifier keys and options such as x, y, and offset.

```ruby
page.find('button').click
page.find('a').click(:shift)                  # shift+click
page.find('div').click(x: 10, y: 10, offset: :center)
page.find('li').right_click
page.find('li').double_click
```

--------------------------------

### Example: on_save_screenrecord usage

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Example usage of on_save_screenrecord to move the recorded video file to a videos directory. The block receives the video path as a String.

```ruby
page.driver.on_save_screenrecord do |video_path|
  FileUtils.mv(video_path, "videos/#{Time.now.to_i}.webm")
end
```

--------------------------------

### Direct construction example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Example of directly constructing a Capybara::Playwright::Browser instance. Normally only the Driver does this. It passes a driver, logger, playwright_browser, page_options, and optional timeouts.

```ruby
browser = Capybara::Playwright::Browser.new(
  driver: driver,
  internal_logger: logger,
  playwright_browser: playwright_browser,
  page_options: Capybara::Playwright::PageOptions.new({}).value,
  default_timeout: 3000,
  default_navigation_timeout: 5000
)
```

--------------------------------

### PlaywrightCreate usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Shows how to instantiate PlaywrightCreate with custom options (browser_type: :webkit, custom CLI path, headless: false) and then obtain the execution and browser objects.

```ruby
runner = Capybara::Playwright::BrowserRunner::PlaywrightCreate.new(
  browser_type: :webkit,
  playwright_cli_executable_path: './node_modules/.bin/playwright',
  headless: false
)
execution = runner.playwright_execution
browser = runner.playwright_browser
```

--------------------------------

### Example: using delegated methods through the driver

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver.md

Demonstrates using delegated methods on a Capybara session, including visit, execute_script, save_screenshot, and open_new_window.

```ruby
session = Capybara::Session.new(:playwright, MyApp)
session.visit('/')
session.execute_script('window.scrollTo(0, document.body.scrollHeight)')
session.save_screenshot('tmp/shot.png')
session.open_new_window(:tab)
```

--------------------------------

### clear_browser_contexts usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Example call to clear_browser_contexts. Closes all contexts and saves/reports any active traces.

```ruby
browser.clear_browser_contexts  # closes all contexts; saves + reports any active traces

```

--------------------------------

### Example: Using shadow_root to find inner element

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Example usage of shadow_root to access elements inside a shadow DOM.

```ruby
host = page.find('#my-component')
shadow = host.shadow_root
shadow.find_css('.inner-button')
```

--------------------------------

### Frame switching example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Demonstrates switching to the top frame, to a specific iframe node, and back to the parent frame.

```ruby
page.driver.switch_to_frame(:top)
page.driver.switch_to_frame(frame_node)   # frame_node is a Capybara node of an <iframe>
page.driver.switch_to_frame(:parent)

```

--------------------------------

### Response tracking usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Shows how to access response headers (case-insensitive) and status code from the driver.

```ruby
page.driver.response_headers['content-type']   # case-insensitive lookup
page.driver.status_code                        # => 200
```

--------------------------------

### DialogEventHandler usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Shows how to create a handler, set a default, add a handler, handle a dialog, remove the handler, and fall back to the default.

```ruby
handler = Capybara::Playwright::DialogEventHandler.new
handler.default_handler = ->(dialog) { dialog.dismiss }
id = handler.add_handler(->(dialog) { dialog.accept })
handler.handle_dialog(dialog)          # invokes the added handler
handler.remove_handler(id)
handler.handle_dialog(dialog)          # falls back to default_handler
```

--------------------------------

### on_save_trace usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Example of using on_save_trace to move the saved trace.zip file to a traces directory with a timestamped filename.

```ruby
page.driver.on_save_trace do |trace_zip|
  FileUtils.mv(trace_zip, "traces/#{Time.now.to_i}.zip")
end
```

--------------------------------

### Example: mixing TmpdirOwner into a recorder class

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/tmpdir-owner.md

Complete example of mixing TmpdirOwner into a custom recorder class. The capture method lazily creates the tmpdir, yields it for writing artifacts, and ensures remove_tmpdir is called for eager cleanup.

```ruby
class Recorder
  include Capybara::Playwright::TmpdirOwner

  def capture
    dir = tmpdir           # lazily created, finalizer registered
    begin
      # write files under dir, e.g. video or trace artifacts
      yield dir
    ensure
      remove_tmpdir        # eager cleanup; safe to call even if tmpdir never used
    end
  end
end

Recorder.new.capture { |dir| File.write(File.join(dir, 'out.txt'), 'data') }
```

--------------------------------

### drag_to usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Shows how to drag an element to a target, optionally with a delay and drop modifiers.

```ruby
page.find('#source').drag_to(page.find('#target'))
page.find('#source').drag_to(page.find('#target'), delay: 0.5, drop_modifiers: [:shift])
```

--------------------------------

### PlaywrightConnectToBrowserServer usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Shows how to instantiate PlaywrightConnectToBrowserServer with a WebSocket endpoint and browser type, then obtain the already-connected browser.

```ruby
runner = Capybara::Playwright::BrowserRunner::PlaywrightConnectToBrowserServer.new(
  'ws://localhost:8000/browser',
  browser_type: :firefox
)
browser = runner.playwright_browser   # already connected
```

--------------------------------

### trace method implementation

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Starts tracing, runs the given block, and stops tracing in an ensure block. Raises ArgumentError if no block is given. Source: driver_extension.rb:70.

```ruby
# Trace execution of the given block. The tracing is automatically stopped when the block is finished.
def trace(name: nil, screenshots: false, snapshots: false, sources: false, title: nil, path: nil, &block)
  raise ArgumentError.new('block must be given') unless block

  start_tracing(name: name, screenshots: screenshots, snapshots: snapshots, sources: sources, title: title)
  block.call
ensure
  stop_tracing(path: path)
end
```

--------------------------------

### Element identity and predicates usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Demonstrates checking element properties like checked, visible, disabled, path, and equality.

```ruby
el = page.find('#checkbox')
el.checked?   # => true/false
el.visible?
el.disabled?
el.path
page.find('#box') == page.find('#box')   # => true
```

--------------------------------

### start_tracing(name: nil, screenshots: false, snapshots: false, sources: false, title: nil)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Starts Playwright tracing on the current page's context. Accepts optional parameters to configure the trace.

```APIDOC
## start_tracing(name: nil, screenshots: false, snapshots: false, sources: false, title: nil)

### Description
Starts Playwright tracing on the current page's context. Ensures a page exists before starting tracing.

### Method
N/A (Ruby method)

### Parameters
#### Keyword Parameters
- **name:** (String/nil) - Optional - Trace name. Default: nil.
- **screenshots:** (Boolean) - Optional - Capture screenshots. Default: false.
- **snapshots:** (Boolean) - Optional - Capture DOM snapshots. Default: false.
- **sources:** (Boolean) - Optional - Capture source scripts. Default: false.
- **title:** (String/nil) - Optional - Trace title. Default: nil.

### Example
```ruby
page.driver.start_tracing(name: 'my_trace', screenshots: true, snapshots: true)
```
```

--------------------------------

### Scrolling usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Shows how to scroll an element to the bottom, scroll by pixel offsets, and scroll to explicit coordinates.

```ruby
page.find('#long-list').scroll_to(:bottom)
page.find('#long-list').scroll_by(0, 200)
page.find('#long-list').scroll_to(0, 0, [10, 20])
```

--------------------------------

### PlaywrightConnectToPlaywrightServer usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Shows how to instantiate PlaywrightConnectToPlaywrightServer with a WebSocket endpoint and browser type, then obtain the execution and browser.

```ruby
runner = Capybara::Playwright::BrowserRunner::PlaywrightConnectToPlaywrightServer.new(
  'ws://localhost:8000/playwright',
  browser_type: :chromium
)
execution = runner.playwright_execution
browser = runner.playwright_browser
```

--------------------------------

### Example: Using Capybara::Playwright::Node

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Shows how nodes are normally produced and used. The comment explains that nodes are what Capybara's find returns.

```ruby
# Normally produced by Browser#find_xpath / find_css / wrap_node.
# Nodes are what Capybara's find returns:
el = page.find('button')
el.class # => Capybara::Playwright::Node
```

--------------------------------

### Run focused RSpec example with rbenv

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/AGENTS.md

Use this command to run a focused Playwright compatibility check locally, using the Ruby version specified in .ruby-version.

```shell
RBENV_VERSION=$(cat .ruby-version) ~/.rbenv/shims/bundle exec rspec spec/capybara/playwright_spec.rb --example fill_in
```

--------------------------------

### start_tracing method definition

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Defines start_tracing which starts Playwright tracing on the current page's context. It forces browser initialization to ensure a page exists, then calls tracing.start with the given options.

```ruby
# Start Playwright tracing (doc: https://playwright.dev/docs/api/class-tracing#tracing-start)
def start_tracing(name: nil, screenshots: false, snapshots: false, sources: false, title: nil)
  # Ensure playwright page is initialized.
  browser
  with_playwright_page do |playwright_page|
    playwright_page.context.tracing.start(name: name, screenshots: screenshots, snapshots: snapshots, sources: sources, title: title)
  end
end
```

--------------------------------

### trace(name: nil, screenshots: false, snapshots: false, sources: false, title: nil, path: nil, &block)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Traces execution of the given block. Starts tracing, runs the block, and stops tracing in an ensure block. Raises ArgumentError if no block is given.

```APIDOC
## trace(name: nil, screenshots: false, snapshots: false, sources: false, title: nil, path: nil, &block)

### Description
Traces execution of the given block. Starts tracing, runs the block, and stops tracing in an ensure block. Raises ArgumentError if no block is given.

### Method
trace

### Parameters
#### Keyword Arguments
- **name** (String) - Optional - The name of the trace.
- **screenshots** (Boolean) - Optional - Whether to capture screenshots. Defaults to false.
- **snapshots** (Boolean) - Optional - Whether to capture snapshots. Defaults to false.
- **sources** (Boolean) - Optional - Whether to capture sources. Defaults to false.
- **title** (String) - Optional - The title of the trace.
- **path** (String) - Optional - The path to write the trace `.zip` file to.

#### Block
- **&block** (Proc) - Required - The block to trace.

### Errors
- **ArgumentError** - Raised if no block is given. Message: "block must be given"

### Example
```ruby
page.driver.trace(name: 'my_trace', screenshots: true, snapshots: true, path: 'tmp/trace.zip') do
  visit '/'
  click_on 'Go'
end
```

### Error handling example
```ruby
begin
  page.driver.trace { visit '/' }
rescue ArgumentError => e
  # trace without a block never starts; e.message == "block must be given"
end
```

```

--------------------------------

### Good: Concise initialize parameters

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/AGENTS.md

Use concise parameter names that reflect the domain role without redundant prefixes.

```ruby
def initialize(node:, node_type:, locator:, checked:)
  @node = node
  @node_type = node_type
  @locator = locator
  @checked = checked
end
```

--------------------------------

### Install capybara-playwright-driver gem

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/README.md

Add the gem to your Gemfile to install capybara-playwright-driver.

```ruby
gem 'capybara-playwright-driver'
```

--------------------------------

### BrowserOptions#initialize

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/options.md

Initializes a BrowserOptions instance with the given options hash.

```ruby
def initialize(options)
  @options = options
end
```

--------------------------------

### with_playwright_page usage example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Example of using with_playwright_page to interact with the raw Playwright page, pressing Enter on a search field.

```ruby
page.driver.with_playwright_page do |playwright_page|
  playwright_page.get_by_label('Search or jump to', exact: true).press('Enter')
end
```

--------------------------------

### trace error handling example

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver-extension.md

Example of rescuing the ArgumentError raised when trace is called without a block. The error message is 'block must be given'.

```ruby
begin
  page.driver.trace { visit '/' }
rescue ArgumentError => e
  # trace without a block never starts; e.message == "block must be given"
end
```

--------------------------------

### window_handles and current_window_handle method signatures

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

These method signatures are defined in browser.rb. window_handles returns Playwright page GUIDs (pages.map(&:guid)), and current_window_handle returns @playwright_page&.guid.

```ruby
def window_handles
def current_window_handle

```

--------------------------------

### initialize(app, **options)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver.md

Creates a new Capybara::Playwright::Driver instance. It accepts a Rack application and optional keyword arguments for configuration, such as browser type, timeouts, and logger.

```APIDOC
## initialize(app, **options)

### Description
Creates a new Capybara::Playwright::Driver instance. It accepts a Rack application and optional keyword arguments for configuration, such as browser type, timeouts, and logger.

### Method
initialize

### Signature
```ruby
def initialize(app, **options)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `app` | Rack application | yes | — | The Rack app under test, supplied by Capybara. |
| `**options` | `Hash` (keyword args) | no | `{}` | Driver options. See [configuration.md](../configuration.md) for the full table. |

### Behavior Notes
- Builds a `BrowserRunner.new(options)` and a `PageOptions.new(options)`.
- If `options[:timeout]` is `Numeric`: `@default_navigation_timeout = options[:timeout] * 1000` (compatibility with `capybara-selenium-driver`).
- If `options[:default_timeout]` is `Numeric`: `@default_timeout = options[:default_timeout] * 1000`.
- If `options[:default_navigation_timeout]` is `Numeric`: `@default_navigation_timeout = options[:default_navigation_timeout] * 1000`.
- `@internal_logger = options[:logger] || default_logger`, where `default_logger` returns `Rails.logger` when Rails is defined, otherwise a `PutsLogger`.

### Example: basic registration
```ruby
require 'capybara-playwright-driver'

Capybara.register_driver(:playwright) do |app|
  Capybara::Playwright::Driver.new(app, browser_type: :firefox, headless: false)
end
Capybara.default_max_wait_time = 15
Capybara.default_driver = :playwright
Capybara.save_path = 'tmp/capybara'
```

### Example: timeout options and logger
```ruby
Capybara.register_driver(:playwright) do |app|
  Capybara::Playwright::Driver.new(
    app,
    browser_type: :chromium,
    timeout: 2,                 # navigation timeout (seconds), Selenium-compatible alias
    default_timeout: 3,         # actionability timeout (seconds)
    default_navigation_timeout: 4, # navigation timeout (seconds)
    logger: Logger.new($stdout)
  )
end
```
```

--------------------------------

### switch_to_window(handle)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Brings the matching page to front and makes it current. Raises NoSuchWindowError if the handle is unknown.

```APIDOC
## switch_to_window(handle)

### Description
Brings the matching page to front and makes it current. Raises NoSuchWindowError if the handle is unknown.

### Parameters
- `handle` (String) - Required - The window handle (page GUID) to switch to.

### Errors
- `NoSuchWindowError` - Raised if the handle is unknown.
```

--------------------------------

### Install matching Playwright CLI version

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/configuration.md

Exports the PLAYWRIGHT_CLI_VERSION environment variable by reading the compatible version from the playwright gem, then installs the matching npm playwright package. This is used in the README development flow to ensure the CLI version matches the gem.

```bash
export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'require "playwright"; puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION.strip')
npm install playwright@${PLAYWRIGHT_CLI_VERSION}
```

--------------------------------

### DialogEventHandler#with_handler

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Runs a block with a handler installed and guarantees removal in an ensure block.

```APIDOC
## DialogEventHandler#with_handler

### Description
Runs a block with a handler installed and guarantees removal in an ensure block.

### Method
with_handler

### Endpoint
DialogEventHandler#with_handler

### Parameters
#### Request Body
- **callable** (Proc) - Required - The handler to install for the duration of the block.
- **&block** (Block) - Required - The block to execute with the handler installed.

### Request Example
```ruby
handler.with_handler(->(dialog) { dialog.accept }) do
  # perform actions that may trigger a dialog
end
```

### Response
#### Success Response
- **result** (Object) - The return value of the block.

#### Response Example
```ruby
nil
```
```

--------------------------------

### switch_to_window method signature

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Defined in browser.rb:322. Brings the matching page to front and makes it current; raises NoSuchWindowError if the handle is unknown.

```ruby
def switch_to_window(handle)

```

--------------------------------

### BrowserRunner#initialize

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Selects the browser-launch strategy based on the provided options. If playwright_server_endpoint_url is present, it connects to a Playwright server; if browser_server_endpoint_url is present, it connects to a browser server; otherwise it creates a new browser.

```APIDOC
## BrowserRunner#initialize

### Description
Selects the browser-launch strategy based on the provided options. If `playwright_server_endpoint_url` is present, it connects to a Playwright server; if `browser_server_endpoint_url` is present, it connects to a browser server; otherwise it creates a new browser.

### Method
initialize

### Signature
```ruby
def initialize(options)
```

### Parameters
- **options** (Hash) - Required - Options hash used to select the strategy. Recognized keys: `:playwright_server_endpoint_url`, `:browser_server_endpoint_url`, and any other driver options.

### Strategy Selection
| Option present | Strategy used |
|----------------|---------------|
| `playwright_server_endpoint_url` | `PlaywrightConnectToPlaywrightServer` |
| `browser_server_endpoint_url` | `PlaywrightConnectToBrowserServer` |
| neither | `PlaywrightCreate` (default) |

### Example
```ruby
runner = Capybara::Playwright::BrowserRunner.new(browser_type: :firefox, headless: true)
```
```

--------------------------------

### initialize(driver, internal_logger, page, element)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/shadow-root-node.md

Initializes a new ShadowRootNode instance. It wraps the given shadow host element and evaluates el.shadowRoot to obtain the shadow root handle.

```APIDOC
## initialize(driver, internal_logger, page, element)

### Description
Initializes a new ShadowRootNode instance. It wraps the given shadow host element and evaluates `el.shadowRoot` to obtain the shadow root handle.

### Parameters
- **driver** (Capybara::Playwright::Driver) - Required - Owning driver (inherited from Node).
- **internal_logger** (logger) - Required - Internal logger.
- **page** (Playwright::Page) - Required - Parent page.
- **element** (Playwright::ElementHandle) - Required - The shadow host element handle.

### Example
```ruby
host = page.find('#my-component')
shadow = host.shadow_root
# shadow is a Capybara::Playwright::ShadowRootNode
```
```

--------------------------------

### Default reset behavior with Capybara

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver.md

Shows how reset! is called automatically by Capybara between examples or via Capybara.reset_sessions!.

```ruby
# Called automatically by Capybara between examples / via Capybara.reset_sessions!
session.reset!
```

--------------------------------

### window_handles / current_window_handle

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Returns an array of window handles (Playwright page GUIDs) and the current window handle.

```APIDOC
## window_handles / current_window_handle

### Description
Returns an array of window handles (Playwright page GUIDs) and the current window handle.

### Method
- `window_handles`
- `current_window_handle`

### Returns
- `window_handles`: Array of strings (page GUIDs)
- `current_window_handle`: String (current page GUID) or nil
```

--------------------------------

### Run tests with Xvfb

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/README.md

Run the test suite in a virtual framebuffer (Xvfb) using the installed Playwright executable.

```bash
PLAYWRIGHT_CLI_EXECUTABLE_PATH=./node_modules/.bin/playwright xvfb-run bundle exec rspec
```

--------------------------------

### BrowserRunner#initialize strategy selection

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Selects the browser-launch strategy based on the presence of :playwright_server_endpoint_url or :browser_server_endpoint_url options. Defaults to PlaywrightCreate when neither is present.

```ruby
def initialize(options)
  @runner =
    if options[:playwright_server_endpoint_url]
      PlaywrightConnectToPlaywrightServer.new(options[:playwright_server_endpoint_url], options)
    elsif options[:browser_server_endpoint_url]
      PlaywrightConnectToBrowserServer.new(options[:browser_server_endpoint_url], options)
    else
      PlaywrightCreate.new(options)
    end
end
```

--------------------------------

### PlaywrightCreate#initialize

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser-runner.md

Initializes a new PlaywrightCreate instance with options for the Playwright CLI executable path, browser type, and browser options.

```APIDOC
## PlaywrightCreate#initialize

### Description
Initializes a new PlaywrightCreate instance. Sets the Playwright CLI executable path (default 'npx playwright'), the browser type (default :chromium, valid :chromium, :firefox, :webkit), and creates a BrowserOptions object from the given options.

### Method
initialize

### Parameters
- **options** (Hash) - Required - Options hash containing:
  - `:playwright_cli_executable_path` (String) - Optional - Path to the Playwright CLI executable. Default: 'npx playwright'.
  - `:browser_type` (Symbol) - Optional - Browser type to launch. Valid values: :chromium, :firefox, :webkit. Default: :chromium.
  - Additional options are passed to BrowserOptions.

### Raises
- `ArgumentError` - If `:browser_type` is not one of :chromium, :firefox, :webkit.

### Example
```ruby
runner = Capybara::Playwright::BrowserRunner::PlaywrightCreate.new(
  browser_type: :webkit,
  playwright_cli_executable_path: './node_modules/.bin/playwright',
  headless: false
)
```
```

--------------------------------

### Initialize ShadowRootNode with shadow root handle

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/shadow-root-node.md

Constructor that calls super and evaluates 'el => el.shadowRoot' on the host element to store a JSHandle in @shadow_root_element.

```ruby
def initialize(driver, internal_logger, page, element)
  super
  @shadow_root_element = element.evaluate_handle('el => el.shadowRoot')
end
```

--------------------------------

### initialize(driver:, internal_logger:, playwright_browser:, page_options:, record_video: false, callback_on_save_trace: nil, default_timeout: nil, default_navigation_timeout: nil)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Creates a new Capybara::Playwright::Browser instance. It creates a browser context and a page within it. This constructor is normally called by the Driver class.

```APIDOC
## initialize(driver:, internal_logger:, playwright_browser:, page_options:, record_video: false, callback_on_save_trace: nil, default_timeout: nil, default_navigation_timeout: nil)

### Description
Creates a new Capybara::Playwright::Browser instance. It creates a browser context via `create_browser_context` and immediately creates a page in it via `create_page`. This constructor is normally called by the Driver class.

### Method
Constructor

### Parameters

#### Keyword Parameters
- **driver:** (Capybara::Playwright::Driver) - Required - Owning driver, passed to Nodes.
- **internal_logger:** (logger responding to info/warn) - Required - Logger for internal warnings/info.
- **playwright_browser:** (Playwright::Browser) - Required - The already-launched Playwright browser.
- **page_options:** (Hash) - Required - Filtered PageOptions#value hash passed to new_context.
- **record_video:** (Boolean) - Optional, default: false - If truthy, sets @page_options[:record_video_dir] ||= tmpdir.
- **callback_on_save_trace:** (Proc) - Optional, default: nil - If set, starts tracing on the context with screenshots: true, snapshots: true.
- **default_timeout:** (Integer, ms) - Optional, default: nil - Assigned to browser_context.default_timeout.
- **default_navigation_timeout:** (Integer, ms) - Optional, default: nil - Assigned to browser_context.default_navigation_timeout.

### Example
```ruby
browser = Capybara::Playwright::Browser.new(
  driver: driver,
  internal_logger: logger,
  playwright_browser: playwright_browser,
  page_options: Capybara::Playwright::PageOptions.new({}).value,
  default_timeout: 3000,
  default_navigation_timeout: 5000
)
```
```

--------------------------------

### DialogEventHandler#with_handler

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Runs a block with a handler installed and guarantees removal in an ensure block. Returns the block's result.

```ruby
def with_handler(callable, &block)
  id = add_handler(callable)
  begin
    block.call
  ensure
    remove_handler(id)
  end
end
```

--------------------------------

### initialize(driver, internal_logger, page, element)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/node.md

Creates a new Node instance wrapping a Playwright::ElementHandle. This is typically called internally by the driver, but is documented for completeness.

```APIDOC
## initialize(driver, internal_logger, page, element)

### Description
Creates a new Node instance. Normally produced by Browser#find_xpath / find_css / wrap_node. Nodes are what Capybara's find returns.

### Method
initialize

### Parameters
- `driver` (Capybara::Playwright::Driver) - Required - Owning driver.
- `internal_logger` (logger) - Required - Logger for internal messages.
- `page` (Playwright::Page) - Required - Page the element belongs to.
- `element` (Playwright::ElementHandle) - Required - The wrapped handle.

### Example
```ruby
# Normally produced by Browser#find_xpath / find_css / wrap_node.
# Nodes are what Capybara's find returns:
el = page.find('button')
el.class # => Capybara::Playwright::Node
```
```

--------------------------------

### initialize(*args, **kwargs)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/page.md

Overrides the original initializer to call capybara_initialize, which registers dialog, download, and response listeners for Capybara integration.

```APIDOC
## initialize(*args, **kwargs)

### Description
Overrides the original initializer to call capybara_initialize, which registers dialog, download, and response listeners for Capybara integration.

### Method
initialize

### Parameters
- **args** (Array) - Required - Arguments passed to the original initializer.
- **kwargs** (Hash) - Optional - Keyword arguments passed to the original initializer.

### Request Example
```ruby
page = Playwright::Page.new(*args, **kwargs)
```

### Response
#### Success Response
- No return value (nil).

#### Response Example
```ruby
nil
```
```

--------------------------------

### needs_server?

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/driver.md

Returns true to indicate that the driver requires a running Rack server for the app.

```APIDOC
## `needs_server?`

### Description
Returns `true` to indicate that the driver requires a running Rack server for the app.

### Method
`needs_server?`

### Returns
- `true` (Boolean) - The driver requires a running Rack server.

### Source
`lib/capybara/playwright/driver.rb:25`
```

--------------------------------

### maximize_window(handle) / fullscreen_window(handle)

Source: https://github.com/yusukeiwaki/capybara-playwright-driver/blob/main/_autodocs/api-reference/browser.md

Maximize and fullscreen operations. Both log a warning that they are not supported, then approximate: maximize sets viewport size to screen size; fullscreen calls requestFullscreen.

```APIDOC
## maximize_window(handle) / fullscreen_window(handle)

### Description
Maximize and fullscreen operations. Both log a warning that they are not supported, then approximate: maximize sets viewport size to screen size; fullscreen calls requestFullscreen.

### Parameters
- `handle` (String) - Required - The window handle (page GUID).

### Notes
- Both methods log a warning via the internal logger.
```
Tokens:
Raw