playwright-ruby-client 1.39.0 → 1.40.0

data/documentation/docs/api/page.md

@@ -12,21 +12,12 @@ instance might have multiple [Page](./page) instances.
 
 This example creates a page, navigates it to a URL, and then saves a screenshot:
 
-```python sync title=example_94e620cdbdfd41e2c9b14d561052ffa89535fc346038c4584ea4dd8520f5401c.py
-from playwright.sync_api import sync_playwright, Playwright
-
-def run(playwright: Playwright):
-    webkit = playwright.webkit
-    browser = webkit.launch()
-    context = browser.new_context()
-    page = context.new_page()
-    page.goto("https://example.com")
-    page.screenshot(path="screenshot.png")
-    browser.close()
-
-with sync_playwright() as playwright:
-    run(playwright)
-
+```ruby
+playwright.webkit.launch do |browser|
+  page = browser.new_page
+  page.goto('https://example.com/')
+  page.screenshot(path: 'screenshot.png')
+end
 ```
 
 The Page class emits various events (described below) which can be handled using any of Node's native
@@ -161,7 +152,7 @@ When all steps combined have not finished during the specified `timeout`, this m
 ## close
 
 ```
-def close(runBeforeUnload: nil)
+def close(reason: nil, runBeforeUnload: nil)
 ```
 
 
@@ -249,13 +240,16 @@ default.
 
 Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial
 properties:
+- [DeviceMotionEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceMotionEvent/DeviceMotionEvent)
+- [DeviceOrientationEvent](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/DeviceOrientationEvent)
 - [DragEvent](https://developer.mozilla.org/en-US/docs/Web/API/DragEvent/DragEvent)
+- [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
 - [FocusEvent](https://developer.mozilla.org/en-US/docs/Web/API/FocusEvent/FocusEvent)
 - [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent)
 - [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/MouseEvent)
 - [PointerEvent](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/PointerEvent)
 - [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent/TouchEvent)
-- [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event)
+- [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent/WheelEvent)
 
 You can also specify [JSHandle](./js_handle) as the property value if you want live objects to be passed into the event:
 
@@ -471,29 +465,18 @@ See [BrowserContext#expose_binding](./browser_context#expose_binding) for the co
 
 An example of exposing page URL to all frames in a page:
 
-```python sync title=example_4f7d99a72aaea957cc5678ed8728965338d78598d7772f47fbf23c28f0eba52d.py
-from playwright.sync_api import sync_playwright, Playwright
-
-def run(playwright: Playwright):
-    webkit = playwright.webkit
-    browser = webkit.launch(headless=false)
-    context = browser.new_context()
-    page = context.new_page()
-    page.expose_binding("pageURL", lambda source: source["page"].url)
-    page.set_content("""
-    <script>
-      async function onClick() {
-        document.querySelector('div').textContent = await window.pageURL();
-      }
-    </script>
-    <button onclick="onClick()">Click me</button>
-    <div></div>
-    """)
-    page.click("button")
-
-with sync_playwright() as playwright:
-    run(playwright)
-
+```ruby
+page.expose_binding("pageURL", ->(source) { source[:page].url })
+page.content = <<~HTML
+<script>
+  async function onClick() {
+    document.querySelector('div').textContent = await window.pageURL();
+  }
+</script>
+<button onclick="onClick()">Click me</button>
+<div></div>
+HTML
+page.click("button")
 ```
 
 An example of passing an element handle:
@@ -537,35 +520,24 @@ See [BrowserContext#expose_function](./browser_context#expose_function) for cont
 
 An example of adding a `sha256` function to the page:
 
-```python sync title=example_0f68a39bdff02a3df161c74e81cabb8a2ff1f09f0d09f6ef9b799a6f2f19a280.py
-import hashlib
-from playwright.sync_api import sync_playwright, Playwright
-
-def sha256(text):
-    m = hashlib.sha256()
-    m.update(bytes(text, "utf8"))
-    return m.hexdigest()
-
-
-def run(playwright: Playwright):
-    webkit = playwright.webkit
-    browser = webkit.launch(headless=False)
-    page = browser.new_page()
-    page.expose_function("sha256", sha256)
-    page.set_content("""
-        <script>
-          async function onClick() {
-            document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
-          }
-        </script>
-        <button onclick="onClick()">Click me</button>
-        <div></div>
-    """)
-    page.click("button")
+```ruby
+require 'digest'
 
-with sync_playwright() as playwright:
-    run(playwright)
+def sha256(text)
+  Digest::SHA256.hexdigest(text)
+end
 
+page.expose_function("sha256", method(:sha256))
+page.content = <<~HTML
+<script>
+  async function onClick() {
+    document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
+  }
+</script>
+<button onclick="onClick()">Click me</button>
+<div></div>
+HTML
+page.locator("button").click
 ```
 
 ## fill
@@ -1355,14 +1327,13 @@ Triggers a `change` and `input` event once all the provided options have been se
 
 **Usage**
 
-```python sync title=example_8260034c740933903e5a39d30a4f4e388bdffa9e82acd9a5fe1fb774752a505a.py
-# Single selection matching the value or label
-page.select_option("select#colors", "blue")
+```ruby
+# single selection matching the value
+page.select_option("select#colors", value: "blue")
 # single selection matching both the label
-page.select_option("select#colors", label="blue")
+page.select_option("select#colors", label: "blue")
 # multiple selection
-page.select_option("select#colors", value=["red", "green", "blue"])
-
+page.select_option("select#colors", value: ["red", "green", "blue"])
 ```
 
 ## set_checked
@@ -1676,20 +1647,9 @@ Returns when the `expression` returns a truthy value. It resolves to a JSHandle
 
 The [Page#wait_for_function](./page#wait_for_function) can be used to observe viewport size change:
 
-```python sync title=example_83eed1f1f00ad73f641bf4a49f672e81c4faf1ca098a4a5070afeeabb88312f5.py
-from playwright.sync_api import sync_playwright, Playwright
-
-def run(playwright: Playwright):
-    webkit = playwright.webkit
-    browser = webkit.launch()
-    page = browser.new_page()
-    page.evaluate("window.x = 0; setTimeout(() => { window.x = 100 }, 1000);")
-    page.wait_for_function("() => window.x > 0")
-    browser.close()
-
-with sync_playwright() as playwright:
-    run(playwright)
-
+```ruby
+page.evaluate("window.x = 0; setTimeout(() => { window.x = 100 }, 1000);")
+page.wait_for_function("() => window.x > 0")
 ```
 
 To pass an argument to the predicate of [Page#wait_for_function](./page#wait_for_function) function:
@@ -1857,22 +1817,12 @@ function will throw.
 
 This method works across navigations:
 
-```python sync title=example_903c7325fd65fcdf6f22c77fc159922a568841abce60ae1b7c54ab5837401862.py
-from playwright.sync_api import sync_playwright, Playwright
-
-def run(playwright: Playwright):
-    chromium = playwright.chromium
-    browser = chromium.launch()
-    page = browser.new_page()
-    for current_url in ["https://google.com", "https://bbc.com"]:
-        page.goto(current_url, wait_until="domcontentloaded")
-        element = page.wait_for_selector("img")
-        print("Loaded image: " + str(element.get_attribute("src")))
-    browser.close()
-
-with sync_playwright() as playwright:
-    run(playwright)
-
+```ruby
+%w[https://google.com https://bbc.com].each do |current_url|
+  page.goto(current_url, waitUntil: "domcontentloaded")
+  element = page.wait_for_selector("img")
+  puts "Loaded image: #{element["src"]}"
+end
 ```
 
 ## wait_for_timeout

data/documentation/docs/api/playwright.md

@@ -8,20 +8,19 @@ sidebar_position: 10
 Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright
 to drive automation:
 
-```python sync title=example_6647e5a44b0440884026a6142606dfddad75ba1e643919b015457df4ed2e198f.py
-from playwright.sync_api import sync_playwright, Playwright
+```ruby
+require 'playwright'
 
-def run(playwright: Playwright):
-    chromium = playwright.chromium # or "firefox" or "webkit".
-    browser = chromium.launch()
-    page = browser.new_page()
-    page.goto("http://example.com")
-    # other actions...
-    browser.close()
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  chromium = playwright.chromium # or "firefox" or "webkit".
+  chromium.launch do |browser|
+    page = browser.new_page
+    page.goto('https://example.com/')
 
-with sync_playwright() as playwright:
-    run(playwright)
+    # other actions
 
+  end
+end
 ```
 
 ## chromium
@@ -34,22 +33,20 @@ This object can be used to launch or connect to Chromium, returning instances of
 
 Returns a dictionary of devices to be used with [Browser#new_context](./browser#new_context) or [Browser#new_page](./browser#new_page).
 
-```python sync title=example_14d627977a4ad16a605ec5472d768a3324812fa8e7c57685561408fa6601e352.py
-from playwright.sync_api import sync_playwright, Playwright
+```ruby
+require 'playwright'
 
-def run(playwright: Playwright):
-    webkit = playwright.webkit
-    iphone = playwright.devices["iPhone 6"]
-    browser = webkit.launch()
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  iphone = playwright.devices["iPhone 6"]
+  playwright.webkit.launch do |browser|
     context = browser.new_context(**iphone)
-    page = context.new_page()
-    page.goto("http://example.com")
-    # other actions...
-    browser.close()
+    page = context.new_page
+    page.goto('https://example.com/')
 
-with sync_playwright() as playwright:
-    run(playwright)
+    # other actions
 
+  end
+end
 ```
 
 ## firefox

data/documentation/docs/api/selectors.md

@@ -21,38 +21,33 @@ Selectors must be registered before creating the page.
 
 An example of registering selector engine that queries elements based on a tag name:
 
-```python sync title=example_3e739d4f0e30e20a6a698e0e17605a841c35e65e75aa3c2642f8bfc368b33f9e.py
-from playwright.sync_api import sync_playwright, Playwright
-
-def run(playwright: Playwright):
-    tag_selector = """
-      {
-          // Returns the first element matching given selector in the root's subtree.
-          query(root, selector) {
-              return root.querySelector(selector);
-          },
-          // Returns all elements matching given selector in the root's subtree.
-          queryAll(root, selector) {
-              return Array.from(root.querySelectorAll(selector));
-          }
-      }"""
-
-    # Register the engine. Selectors will be prefixed with "tag=".
-    playwright.selectors.register("tag", tag_selector)
-    browser = playwright.chromium.launch()
-    page = browser.new_page()
-    page.set_content('<div><button>Click me</button></div>')
-
-    # Use the selector prefixed with its name.
-    button = page.locator('tag=button')
-    # Combine it with built-in locators.
-    page.locator('tag=div').get_by_text('Click me').click()
-    # Can use it in any methods supporting selectors.
-    button_count = page.locator('tag=button').count()
-    print(button_count)
-    browser.close()
-
-with sync_playwright() as playwright:
-    run(playwright)
-
+```ruby
+tag_selector = <<~JAVASCRIPT
+{
+    // Returns the first element matching given selector in the root's subtree.
+    query(root, selector) {
+        return root.querySelector(selector);
+    },
+    // Returns all elements matching given selector in the root's subtree.
+    queryAll(root, selector) {
+        return Array.from(root.querySelectorAll(selector));
+    }
+}
+JAVASCRIPT
+
+# Register the engine. Selectors will be prefixed with "tag=".
+playwright.selectors.register("tag", script: tag_selector)
+playwright.chromium.launch do |browser|
+  page = browser.new_page
+  page.content = '<div><button>Click me</button></div>'
+
+  # Use the selector prefixed with its name.
+  button = page.locator('tag=button')
+  # Combine it with other selector engines.
+  page.locator('tag=div').get_by_text('Click me').click
+
+  # Can use it in any methods supporting selectors.
+  button_count = page.locator('tag=button').count
+  button_count # => 1
+end
 ```

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

@@ -33,7 +33,7 @@ end
 
 ### Update timeout
 
-Capybara sets the default value of timeout to *2 seconds*. Generally it is too short to wait for HTTP responses.
+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.
 
@@ -56,50 +56,50 @@ It is not mandatry. Without changing the default driver, you can still use Playw
 
 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
+- `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 = {
@@ -119,14 +119,13 @@ driver_opts = {
 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`
+- `Capybara::Node::Element#drop`
 
 ### Playwright-native scripting
 
@@ -181,7 +180,6 @@ end
 
 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.
@@ -201,8 +199,39 @@ before do |example|
 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.
+- 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/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::RSpec::Matchers, type: :feature
+end
+```
+
+If you want to use web-first assertions only for some specs, you can include `Playwright::RSpec::Matchers` in the spec file directly.
+
+```ruby title=spec/system/example_spec.rb
+require 'rails_helper'
+require 'playwright/test'
+
+describe 'example' do
+  include Playwright::RSpec::Matchers
+
+  it 'should work' do
+    ...
+```
+
+## Matchers
+
+Please refer to [API doc](/docs/api/locator_assertions).

data/documentation/docs/include/api_coverage.md

@@ -527,6 +527,49 @@
 
 * ~~new_context~~
 
+## LocatorAssertions
+
+* not_to_be_attached
+* not_to_be_checked
+* not_to_be_disabled
+* not_to_be_editable
+* not_to_be_empty
+* not_to_be_enabled
+* not_to_be_focused
+* not_to_be_hidden
+* not_to_be_in_viewport
+* not_to_be_visible
+* not_to_contain_text
+* not_to_have_attribute
+* not_to_have_class
+* not_to_have_count
+* not_to_have_css
+* not_to_have_id
+* not_to_have_js_property
+* not_to_have_text
+* not_to_have_value
+* not_to_have_values
+* to_be_attached
+* to_be_checked
+* to_be_disabled
+* to_be_editable
+* to_be_empty
+* to_be_enabled
+* to_be_focused
+* to_be_hidden
+* to_be_in_viewport
+* to_be_visible
+* to_contain_text
+* to_have_attribute
+* to_have_class
+* to_have_count
+* to_have_css
+* to_have_id
+* to_have_js_property
+* to_have_text
+* to_have_value
+* to_have_values
+
 ## Android
 
 * ~~connect~~

data/documentation/docusaurus.config.js

@@ -81,7 +81,7 @@ module.exports = {
           ],
         },
       ],
-      copyright: `Copyright © ${new Date().getFullYear()} @YusukeIwaki. <p>Built with <a href="https://v2.docusaurus.io/">Docusaurus</a>.</p>`,
+      copyright: `Copyright © ${new Date().getFullYear()} @YusukeIwaki. <p>Built with <a href="https://docusaurus.io/">Docusaurus</a>.</p>`,
     },
     prism: {
       additionalLanguages: ['bash', 'ruby'],

data/documentation/package.json

@@ -14,14 +14,14 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.1",
-    "@docusaurus/preset-classic": "^2.0.1",
-    "@mdx-js/react": "^1.6.22",
-    "@svgr/webpack": "^6.3.1",
-    "clsx": "^1.2.1",
+    "@docusaurus/core": "^3.0.0",
+    "@docusaurus/preset-classic": "^3.0.0",
+    "@mdx-js/react": "^3.0.0",
+    "@svgr/webpack": "^8.1.0",
+    "clsx": "^2.0.0",
     "file-loader": "^6.2.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
     "url-loader": "^4.1.1"
   },
   "browserslist": {