playwright-ruby-client 0.0.8 → 1.58.1.alpha1

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

@@ -0,0 +1,278 @@
+---
+sidebar_position: 3
+---
+
+# Capybara driver for Ruby on Rails application
+
+`playwright-ruby-client` is a client library just for browser automation, while Rails uses [Capybara](https://github.com/teamcapybara/capybara) for system testing.
+
+`capybara-playwright-driver` provides a [Capybara](https://github.com/teamcapybara/capybara) driver based on playwright-ruby-client and makes it easy to integrate into Ruby on Rails applications.
+
+## Installation
+
+Add the line below into Gemfile:
+
+```rb
+gem 'capybara-playwright-driver'
+```
+
+and then `bundle install`.
+
+Note that capybara-playwright-driver does not depend on Selenium. But `selenium-webdriver` is also required [on Rails 5.x, 6.0](https://github.com/rails/rails/pull/39179)
+
+## Register and configure Capybara driver
+
+```rb
+Capybara.register_driver(:customized_playwright) do |app|
+  Capybara::Playwright::Driver.new(app,
+    browser_type: :chromium, # :chromium (default) or :firefox, :webkit
+    headless: false, # true for headless mode (default), false for headful mode.
+  )
+end
+```
+
+:::note
+
+Rails itself (since Rails 6.1) reserves the driver name `:playwright` for its built‑in integration (see [rails/rails#39987](https://github.com/rails/rails/issues/39987) and [YusukeIwaki/capybara-playwright-driver#93](https://github.com/YusukeIwaki/capybara-playwright-driver/issues/93)). **If you call `Capybara.register_driver(:playwright) { ... }` and then use `driven_by :playwright`, Rails' built‑in Playwright driver will be selected** instead of the one defined by `Capybara.register_driver(:playwright) { ... }`. Therefore, when you want to use the driver from this gem with custom options, register it with another name such as `:customized_playwright`.
+
+:::
+
+### When running Playwright in a container
+
+If Playwright is running in an independent container, with docker-compose.yaml config like this
+
+```
+  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"
+    init: true
+    restart: unless-stopped
+```
+
+Configure capybara to use the `browser_server_endpoint_url`
+
+```rb
+Capybara.register_driver(:playwright_remote) do |app|
+  Capybara::Playwright::Driver.new(
+    app,
+    browser_type: :chromium,
+    headless: true,
+    browser_server_endpoint_url: "ws://#{ENV.fetch('PLAYWRIGHT_HOST')}:3000/ws"
+  )
+end
+```
+
+### Update timeout
+
+Capybara sets the default value of timeout to _2 seconds_. Generally it is too short to wait for HTTP responses.
+
+It is recommended to set the timeout to 15-30 seconds for Playwright driver.
+
+```rb
+Capybara.default_max_wait_time = 15
+```
+
+### (Optional) Update default driver
+
+By default, Capybara driver is set to `:rack_test`, which works only with non-JS contents. If your Rails application has many JavaScript contents, it is recommended to change the default driver to `:playwright`.
+
+```rb
+Capybara.default_driver = :playwright
+Capybara.javascript_driver = :playwright
+```
+
+If you registered a customized driver (e.g. `:customized_playwright` as above) and want that to be the default, set:
+
+```rb
+Capybara.default_driver = :customized_playwright
+Capybara.javascript_driver = :customized_playwright
+```
+
+Remember: choosing `:playwright` here will use Rails' built‑in driver, not the customized one from this gem.
+
+It is not mandatory. Without changing the default driver, you can still use the customized Playwright driver by specifying `Capybara.current_driver = :customized_playwright` (or `driven_by :customized_playwright` in system spec) explicitly. Use `:playwright` only if you intend to run against Rails' built‑in Playwright driver (see issues: https://github.com/YusukeIwaki/capybara-playwright-driver/issues/93, https://github.com/rails/rails/issues/39987).
+
+### (reference) Available driver options
+
+These parameters can be passed into `Capybara::Playwright::Driver.new`
+
+- `playwright_cli_executable_path`
+  - Refer [this article](./download_playwright_driver) to understand what to specify.
+- `browser_type`
+  - `:chromium` (default), `:firefox`, or `:webkit`
+- Parameters for [Playwright::BrowserType#launch](/docs/api/browser_type#launch)
+  - args
+  - channel
+    - `chrome`, `msedge`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge-beta`, `msedge-dev` Browser distribution channel. Read more about using [Google Chrome & Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge)
+  - devtools
+  - downloadsPath
+  - env
+  - executablePath
+  - firefoxUserPrefs
+  - headless
+  - ignoreDefaultArgs
+  - proxy
+  - slowMo
+  - timeout
+- Parameters for [Playwright::Browser#new_context](/docs/api/browser#new_context)
+  - bypassCSP
+  - colorScheme
+  - deviceScaleFactor
+  - extraHTTPHeaders
+  - geolocation
+  - hasTouch
+  - httpCredentials
+  - ignoreHTTPSErrors
+  - isMobile
+  - javaScriptEnabled
+  - locale
+  - noViewport
+  - offline
+  - permissions
+  - proxy
+  - record_har_omit_content
+  - record_har_path
+  - record_video_dir
+  - record_video_size
+  - screen
+  - serviceWorkers
+  - storageState
+  - timezoneId
+  - userAgent
+  - viewport
+
+```ruby
+driver_opts = {
+  # `playwright` command path.
+  playwright_cli_executable_path: './node_modules/.bin/playwright',
+
+  # Use firefox for testing.
+  browser_type: :firefox,
+
+  # Headful mode.
+  headless: false,
+
+  # Slower operation
+  slowMo: 50, # integer. (50-100 would be good for most cases)
+}
+
+Capybara::Playwright::Driver.new(app, driver_opts)
+```
+
+## Available functions and Limitations
+
+### Capybara DSL
+
+Most of the methods of `Capybara::Session` and `Capybara::Node::Element` are available. However the following method is not yet implemented.
+
+- `Capybara::Node::Element#drop`
+
+### Playwright-native scripting
+
+We can also describe Playwright-native automation script using `with_playwright_page` and `with_playwright_element_handle`.
+
+```ruby
+# With Capybara DSL
+find('a[data-item-type="global_search"]').click
+
+# With Playwright-native Page
+Capybara.current_session.driver.with_playwright_page do |page|
+  # `page` is an instance of Playwright::Page.
+  page.click('a[data-item-type="global_search"]')
+end
+```
+
+```ruby
+all('.list-item').each do |li|
+  # With Capybara::Node::Element method
+  puts li.all('a').first.text
+
+  # With Playwright-native ElementHandle
+  puts li.with_playwright_element_handle do |handle|
+    # `handle` is an instance of Playwright::ElementHandle
+    handle.query_selector('a').text_content
+  end
+end
+```
+
+Generally, Capybara DSL seems simple, but Playwright-native scripting are more precise and efficient. Also `waitForNavigation`, `waitForSelector`, and many other Playwright functions are available with Playwright-native scripting.
+
+### Screen recording
+
+NO NEED to keep sitting in front of screen during test. Just record what happened with video.
+
+For example, we can store the video for [Allure report](https://github.com/allure-framework/allure-ruby) as below:
+
+```ruby
+before do |example|
+  Capybara.current_session.driver.on_save_screenrecord do |video_path|
+    Allure.add_attachment(
+      name: "screenrecord - #{example.description}",
+      source: File.read(video_path),
+      type: Allure::ContentType::WEBM,
+      test_case: true,
+    )
+  end
+end
+```
+
+![screenrecord](https://user-images.githubusercontent.com/11763113/121126629-71b5f600-c863-11eb-8f88-7924ab669946.gif)
+
+For more details, refer [Recording video](./recording_video.md#using-screen-recording-from-capybara-driver)
+
+### Screenshot just before teardown
+
+In addition to `Capybara::Session#save_screenshot`, capybara-playwright-driver have another method for storing last screen state just before teardown.
+
+For example, we can attach the screenshot for [Allure report](https://github.com/allure-framework/allure-ruby) as below:
+
+```ruby
+before do |example|
+  Capybara.current_session.driver.on_save_raw_screenshot_before_reset do |raw_screenshot|
+    Allure.add_attachment(
+      name: "screenshot - #{example.description}",
+      source: raw_screenshot,
+      type: Allure::ContentType::PNG,
+      test_case: true,
+    )
+  end
+end
+```
+
+### Tracing for postmortem
+
+Playwright users often expect to see what happened in the browser when the test failed. `capybara-playwright-driver` provides a feature to store the trace easily.
+
+```ruby
+before do |example|
+  Capybara.current_session.driver.on_save_trace do |trace_zip_path|
+    Allure.add_attachment(
+      name: "trace - #{example.description}",
+      source: File.read(trace_zip_path),
+      type: 'application/zip',
+      test_case: true,
+    )
+  end
+end
+```
+
+This example code would attach the trace zip file to Allure report for each test case.
+
+![add trace image](https://user-images.githubusercontent.com/11763113/282307106-520d800b-67ac-4e14-98bb-75a8bbb98a1f.png)
+
+We can download and show the trace with `playwright show-trace` command.
+
+```
+npx playwright show-trace ababcdcdefef.zip
+```
+
+![show-trace image](https://user-images.githubusercontent.com/11763113/282307098-a4167c32-d5e7-4631-a3b6-62d278efbeef.png)
+
+Instead of the easy configuration using `on_save_trace`, we can also use `page.driver.start_tracing` / `page.driver.stop_tracing` or `page.driver.with_trace do { ... }` for storing the trace with detailed options. See [the PR](https://github.com/YusukeIwaki/capybara-playwright-driver/pull/66) for more details including example codes for RSpec.
+
+### Limitations
+
+- 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.

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

@@ -0,0 +1,145 @@
+---
+sidebar_position: 4
+---
+
+# Use Capybara without DSL
+
+:::note
+
+This article shows advanced-level configuration of Capybara and RSpec for more accurate automation/testing.
+If you want to just integrate Playwright into Rails application, refer the basic [configuration guide](./rails_integration)
+:::
+
+## Background
+
+[capybara-playwright-driver](./rails_integration) is easy to configure and migrate from Selenium or another Capybara driver, however it is a little **inaccurate** and would sometimes cause 'flaky test' problem originated from the internal implementation of Capybara DSL.
+
+Also **we cannot use most of useful Playwright features in Capybara driver**, such as auto-waiting, various kind of selectors, and some users would want to use Playwright features as it is without Capybara DSL.
+
+This article shows how to use playwright-ruby-client without Capybara DSL in Rails and RSpec.
+
+## Configure Capybara driver just for launching Rails server
+
+Capybara prepares the test server only when the configured driver returns true on `needs_server?` method. So we have to implement minimum driver like this:
+
+```ruby {5-7} title=spec/support/capybara_null_driver.rb
+RSpec.configure do |config|
+  require 'capybara'
+
+  class CapybaraNullDriver < Capybara::Driver::Base
+    def needs_server?
+      true
+    end
+  end
+
+  Capybara.register_driver(:null) { CapybaraNullDriver.new }
+
+  ...
+end
+```
+
+## Launch browser on each test
+
+Now Capybara DSL is unavailable with CapybaraNullDriver, we have to manually launch browsers using playwright-ruby-client.
+
+```rb
+RSpec.configure do |config|
+  require 'capybara'
+
+  ...
+
+  require 'playwright'
+
+  config.around(driver: :null) do |example|
+    Capybara.current_driver = :null
+
+    # 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|
+      # 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)
+        example.run
+      end
+    end
+  end
+end
+```
+
+With the configuration above, we can describe system-test codes with native Playwright methods like below:
+
+```rb
+require 'rails_helper'
+
+describe 'example', driver: :null do
+  let!(:user) { FactoryBot.create(:user) }
+  let(:page) { @playwright_page }
+
+  it 'can browse' do
+    page.goto("/tests/#{user.id}")
+    page.wait_for_selector('input').type('hoge')
+    page.keyboard.press('Enter')
+    expect(page.text_content('#content')).to include('hoge')
+  end
+end
+```
+
+## Minitest Usage
+
+We can do something similar with the default Rails setup using Minitest. Here's the same example written with Minitest:
+
+```rb
+# test/application_system_test_case.rb
+
+require 'playwright'
+
+class CapybaraNullDriver < Capybara::Driver::Base
+  def needs_server?
+    true
+  end
+end
+
+Capybara.register_driver(:null) { CapybaraNullDriver.new }
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  driven_by :null
+
+  def self.playwright
+    @playwright ||= Playwright.create(playwright_cli_executable_path: Rails.root.join("node_modules/.bin/playwright"))
+  end
+  
+  def before_setup
+    super    
+    base_url = Capybara.current_session.server.base_url
+    @playwright_browser = self.class.playwright.playwright.chromium.launch(headless: false)
+    @playwright_page = @playwright_browser.new_page(baseURL: base_url)
+  end
+
+  def after_teardown
+    super
+    @browser.close
+  end
+end
+```
+
+And here is the same test:
+
+```rb
+require "application_system_test_case"
+
+class ExampleTest < ApplicationSystemTestCase
+  def setup
+    @user = User.create!
+    @page = @playwright_page
+  end
+
+  test 'can browse' do
+    @page.goto("/tests/#{user.id}")
+    @page.wait_for_selector('input').type('hoge')
+    @page.keyboard.press('Enter')
+    
+    assert @page.text_content('#content').include?('hoge')
+  end
+end
+```

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

@@ -0,0 +1,79 @@
+---
+sidebar_position: 10
+---
+
+# Recording video
+
+Playwright allows us to record the browser screen during automation.
+https://playwright.dev/docs/videos
+
+With this awesome feature, NO NEED to keep our attention focused on the screen during the automation :)
+
+```ruby {7,11-12,15-16}
+require 'tmpdir'
+
+playwright.chromium.launch do |browser|
+  Dir.mktmpdir do |tmp|
+    video_path = nil
+
+    browser.new_context(record_video_dir: tmp) do |context|
+      page = context.new_page
+      # play with page
+
+      # NOTE: Page#video is available **only when browser context is alive.**
+      video_path = page.video.path
+    end
+
+    # NOTE: video is completely saved **only after browser context is closed.**
+    handle_video_as_you_like(video_path)
+  end
+```
+
+## Specify where to put videos
+
+Playwright puts videos on the directory specified at `record_video_dir`.
+
+The previous example uses [Dir#mktmpdir](https://docs.ruby-lang.org/ja/latest/method/Dir/s/mktmpdir.html) for storing videos into a temporary directory. Also we simply specify a relative or absolute path like `./my_videos/` or `/path/to/videos`.
+
+## Getting video path and recorded video
+
+This is really confusing for beginners, but in Playwright
+
+* We can get the video path **only when page is alive (before calling BrowserContext#close or Page#close)**
+* We can acquire the completely saved video **only after calling  BrowserContext#close**
+
+So in most cases, we have to store the video path in advance, and handle the saved video after BrowserContext is closed, as shown in the previous example code.
+
+### Using `video#save_as(path)`
+
+If you want to just save video to somewhere without handling the video using `File.open`, you can simply use `video#save_as(path_to_save)`.
+
+```ruby {5,8,12-13}
+require 'tmpdir'
+
+playwright.chromium.launch do |browser|
+  Dir.mktmpdir do |tmp|
+    page = nil
+
+    browser.new_context(record_video_dir: tmp) do |context|
+      page = context.new_page
+      # play with page
+    end
+
+    # NOTE: video is completely saved **only after browser context is closed.**
+    page.video.save_as('my-important-video.webm')
+  end
+```
+
+## Using screen recording from Capybara driver
+
+capybara-playwright-driver exposes a function to store the video.
+
+```ruby
+Capybara.current_session.driver.on_save_screenrecord do |video_path|
+  # Handling recorded video here.
+  # video_path is like '/var/folders/xx/xxxxxxxxxx_xxxxxxxx/T/xxxxxxx-xxxxx-xxxxxxxx/e6bde41c5d05b2a02344b058bf1bfea2.webm'
+end
+```
+
+With this callback registration, we can record the videos without specifying `record_video_dir` explicitly or preparing a temporary directory. capybara-playwright-driver automatically prepare and set `record_video_dir` internally.

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

@@ -0,0 +1,59 @@
+---
+sidebar_position: 5
+---
+
+# Web-First assertions for RSpec
+
+Playwright introduces clever assertions for E2E testing, so called [web-first assertions](https://playwright.dev/docs/test-assertions).
+
+```ruby
+it 'should show username after login' do
+  page.fill('input[name="username"]', 'playwright')
+  page.fill('input[name="password"]', 'password123')
+  page.expect_navigation do
+    page.locator('button[type="submit"]').click
+  end
+
+  dashboard_container = page.locator('.dashboard')
+
+  # Not web-first assertion
+  expect(dashboard_container.text_content).to include('Hi, playwright!')
+
+  # Web-first assertion
+  expect(dashboard_container).to have_text('Hi, playwright!')
+end
+```
+
+The spec above have 2 similar expectations. The first one is a normal assertion, which is not web-first. The second one is a web-first assertion, which is introduced by Playwright.
+
+Imagine the case that 'Hi, playwright!' is shown after loading some data from API server. In this case, the first assertion may fail because 'Hi, playwright!' is not present soon after login. On the other hand, the second assertion automatically waits for the 'Hi, playwright!' to be shown.
+
+## Configure
+
+For avoiding matcher name conflicts, web-first assertions are not loaded by default. To enable web-first assertions, we have to configure RSpec as below:
+
+```ruby title=spec/support/web_first_assertion.rb
+require 'playwright/test'
+
+RSpec.configure do |config|
+  # include web-first assertions just for feature specs.
+  config.include Playwright::Test::Matchers, type: :feature
+end
+```
+
+If you want to use web-first assertions only for some specs, you can include `Playwright::Test::Matchers` in the spec file directly.
+
+```ruby title=spec/system/example_spec.rb
+require 'rails_helper'
+require 'playwright/test'
+
+describe 'example' do
+  include Playwright::Test::Matchers
+
+  it 'should work' do
+    ...
+```
+
+## Matchers
+
+Please refer to [API doc](/docs/api/locator_assertions).

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

@@ -0,0 +1,71 @@
+---
+sidebar_position: 20
+---
+
+# Semi-automation
+
+Playwright Browser context is isolated and not persisted by default. But we can also use persistent browser context using [BrowserType#launch_persistent_context](/docs/api/browser_type#launch_persistent_context).
+This allows us to intervene in automation, for example
+
+* Authenticate with OAuth2 manually before automation
+* Testing a page after some chrome extensions are installed manually
+
+Keep in mind repeatedly that persistent browser context is NOT RECOMMENDED for most cases because it would bring many side effects. Consider [reusing cookie and local storage](./use_storage_state) when you just want to keep authenticated across browser contexts.
+
+## Pause automation for manual operation
+
+We can simply use `binding.pry`  (with `pry-byebug` installed).
+
+```ruby {4}
+playwright.chromium.launch_persistent_context('./data/', headless: false) do |context|
+  page = context.new_page
+  page.goto('https://example.com/')
+  binding.pry
+end
+```
+
+When script is executed, it is paused as below.
+
+```
+    3:
+    4: playwright.chromium.launch_persistent_context('./data/', headless: false) do |context|
+    5:   page = context.new_page
+    6:   page.goto('https://example.com/')
+ => 7:   binding.pry
+    8: end
+
+[1] pry(main)>
+```
+
+We can inspect using `page`, `context` and also we can operate something manually during the pause.
+
+See https://github.com/deivid-rodriguez/pry-byebug for more detailed debugging options.
+
+## Working with Chrome extensions
+
+**Playwright disables the Chrome extension feature by default.**
+We have to enable it for installing Chrome extension, by passing these 3 parameters on launch.
+
+* `acceptDownloads: true`
+* `headless: false`
+* `ignoreDefaultArgs: ['--disable-extensions']`
+
+```ruby
+require 'playwright'
+require 'pry'
+
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+  launch_params = {
+    acceptDownloads: true,
+    channel: 'chrome',
+    headless: false,
+    ignoreDefaultArgs: ['--disable-extensions'],
+  }
+
+  playwright.chromium.launch_persistent_context('./data/', **launch_params) do |context|
+    page = context.new_page
+    page.goto('https://example.com/')
+    binding.pry
+  end
+end
+```