playwright-ruby-client 1.26.0 → 1.28.0

data/documentation/docs/api/locator.md

@@ -25,6 +25,14 @@ def all_text_contents
 
 Returns an array of `node.textContent` values for all matching nodes.
 
+## blur
+
+```
+def blur(timeout: nil)
+```
+
+Calls [blur](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/blur) on the element.
+
 ## bounding_box
 
 ```
@@ -79,6 +87,20 @@ If the element is detached from the DOM at any moment during the action, this me
 When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
 zero timeout disables this.
 
+## clear
+
+```
+def clear(force: nil, noWaitAfter: nil, timeout: nil)
+```
+
+This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, clears it and triggers an
+`input` event after clearing.
+
+If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
+However, if the element is inside the `<label>` element that has an associated
+[control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared
+instead.
+
 ## click
 
 ```
@@ -190,6 +212,22 @@ def drag_to(
       trial: nil)
 ```
 
+This method drags the locator to another target locator or target position. It will first move to the source element,
+perform a `mousedown`, then move to the target element or position and perform a `mouseup`.
+
+```ruby
+source = page.locator("#source")
+target = page.locator("#target")
+
+source.drag_to(target)
+# or specify exact positions relative to the top-left corners of the elements:
+source.drag_to(
+  target,
+  sourcePosition: { x: 34, y: 7 },
+  targetPosition: { x: 10, y: 20 },
+)
+```
+
 
 
 ## element_handle
@@ -298,8 +336,8 @@ multiple times.
 row_locator = page.locator("tr")
 # ...
 row_locator.
-    filter(has_text="text in column 1").
-    filter(has=page.locator("tr", has_text="column 2 button")).
+    filter(hasText: "text in column 1").
+    filter(has: page.get_by_role("button", name: "column 2 button")).
     screenshot
 ```
 
@@ -331,7 +369,7 @@ When working with iframes, you can create a frame locator that will enter the if
 that iframe:
 
 ```ruby
-locator = page.frame_locator("iframe").locator("text=Submit")
+locator = page.frame_locator("iframe").get_by_text("Submit")
 locator.click
 ```
 
@@ -346,6 +384,150 @@ alias: `[]`
 
 Returns element attribute value.
 
+## get_by_alt_text
+
+```
+def get_by_alt_text(text, exact: nil)
+```
+
+Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
+
+```html
+<img alt='Castle'>
+```
+
+
+## get_by_label
+
+```
+def get_by_label(text, exact: nil)
+```
+
+Allows locating input elements by the text of the associated label. For example, this method will find the input by
+label text "Password" in the following DOM:
+
+```html
+<label for="password-input">Password:</label>
+<input id="password-input">
+```
+
+
+## get_by_placeholder
+
+```
+def get_by_placeholder(text, exact: nil)
+```
+
+Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
+"Country":
+
+```html
+<input placeholder="Country">
+```
+
+
+## get_by_role
+
+```
+def get_by_role(
+      role,
+      checked: nil,
+      disabled: nil,
+      exact: nil,
+      expanded: nil,
+      includeHidden: nil,
+      level: nil,
+      name: nil,
+      pressed: nil,
+      selected: nil)
+```
+
+Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
+[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
+[accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
+accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+
+Note that many html elements have an implicitly
+[defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
+can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
+recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
+
+## get_by_test_id
+
+```
+def get_by_test_id(testId)
+```
+
+Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
+[Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
+
+
+
+## get_by_text
+
+```
+def get_by_text(text, exact: nil)
+```
+
+Allows locating elements that contain given text. Consider the following DOM structure:
+
+```html
+<div>Hello <span>world</span></div>
+<div>Hello</div>
+```
+
+You can locate by text substring, exact string, or a regular expression:
+
+```ruby
+page.content = <<~HTML
+  <div>Hello <span>world</span></div>
+  <div>Hello</div>
+HTML
+
+# Matches <span>
+locator = page.get_by_text("world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<span>world</span>')
+
+# Matches first <div>
+locator = page.get_by_text("Hello world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+
+# Matches second <div>
+locator = page.get_by_text("Hello", exact: true)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches both <div>s
+locator = page.get_by_text(/Hello/)
+expect(locator.count).to eq(2)
+expect(locator.first.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+expect(locator.last.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches second <div>
+locator = page.get_by_text(/^hello$/i)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+```
+
+See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter
+by the text content.
+
+> NOTE: Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+one, turns line breaks into spaces and ignores leading and trailing whitespace.
+> NOTE: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
+
+## get_by_title
+
+```
+def get_by_title(text, exact: nil)
+```
+
+Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
+
+```html
+<button title='Place the order'>Order Now</button>
+```
+
+
 ## highlight
 
 ```
@@ -361,6 +543,7 @@ Highlight the corresponding element(s) on the screen. Useful for debugging, don'
 def hover(
       force: nil,
       modifiers: nil,
+      noWaitAfter: nil,
       position: nil,
       timeout: nil,
       trial: nil)
@@ -466,9 +649,11 @@ Returns locator to the last matching element.
 def locator(selector, has: nil, hasText: nil)
 ```
 
-The method finds an element matching the specified selector in the [Locator](./locator)'s subtree. It also accepts filter options,
+The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options,
 similar to [Locator#filter](./locator#filter) method.
 
+[Learn more about locators](https://playwright.dev/python/docs/locators).
+
 ## nth
 
 ```
@@ -684,8 +869,8 @@ element.type("world", delay: 100) # types slower, like a user
 An example of typing into a text field and then submitting the form:
 
 ```ruby
-element = page.locator("input")
-element.type("some text")
+element = page.get_by_label("Password")
+element.type("my password")
 element.press("Enter")
 ```
 

data/documentation/docs/api/page.md

@@ -276,6 +276,20 @@ def drag_and_drop(
       trial: nil)
 ```
 
+This method drags the source element to the target element. It will first move to the source element, perform a
+`mousedown`, then move to the target element and perform a `mouseup`.
+
+```ruby
+page.drag_and_drop("#source", "#target")
+# or specify exact positions relative to the top-left corners of the elements:
+page.drag_and_drop(
+  "#source",
+  "#target",
+  sourcePosition: { x: 34, y: 7 },
+  targetPosition: { x: 10, y: 20 },
+)
+```
+
 
 
 ## emulate_media
@@ -592,7 +606,7 @@ that iframe. Following snippet locates element with text "Submit" in the iframe
 id="my-frame">`:
 
 ```ruby
-locator = page.frame_locator("#my-iframe").locator("text=Submit")
+locator = page.frame_locator("#my-iframe").get_by_text("Submit")
 locator.click
 ```
 
@@ -614,6 +628,150 @@ def get_attribute(selector, name, strict: nil, timeout: nil)
 
 Returns element attribute value.
 
+## get_by_alt_text
+
+```
+def get_by_alt_text(text, exact: nil)
+```
+
+Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
+
+```html
+<img alt='Castle'>
+```
+
+
+## get_by_label
+
+```
+def get_by_label(text, exact: nil)
+```
+
+Allows locating input elements by the text of the associated label. For example, this method will find the input by
+label text "Password" in the following DOM:
+
+```html
+<label for="password-input">Password:</label>
+<input id="password-input">
+```
+
+
+## get_by_placeholder
+
+```
+def get_by_placeholder(text, exact: nil)
+```
+
+Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder
+"Country":
+
+```html
+<input placeholder="Country">
+```
+
+
+## get_by_role
+
+```
+def get_by_role(
+      role,
+      checked: nil,
+      disabled: nil,
+      exact: nil,
+      expanded: nil,
+      includeHidden: nil,
+      level: nil,
+      name: nil,
+      pressed: nil,
+      selected: nil)
+```
+
+Allows locating elements by their [ARIA role](https://www.w3.org/TR/wai-aria-1.2/#roles),
+[ARIA attributes](https://www.w3.org/TR/wai-aria-1.2/#aria-attributes) and
+[accessible name](https://w3c.github.io/accname/#dfn-accessible-name). Note that role selector **does not replace**
+accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
+
+Note that many html elements have an implicitly
+[defined role](https://w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You
+can find all the [supported roles here](https://www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not
+recommend** duplicating implicit roles and attributes by setting `role` and/or `aria-*` attributes to default values.
+
+## get_by_test_id
+
+```
+def get_by_test_id(testId)
+```
+
+Locate element by the test id. By default, the `data-testid` attribute is used as a test id. Use
+[Selectors#set_test_id_attribute](./selectors#set_test_id_attribute) to configure a different test id attribute if necessary.
+
+
+
+## get_by_text
+
+```
+def get_by_text(text, exact: nil)
+```
+
+Allows locating elements that contain given text. Consider the following DOM structure:
+
+```html
+<div>Hello <span>world</span></div>
+<div>Hello</div>
+```
+
+You can locate by text substring, exact string, or a regular expression:
+
+```ruby
+page.content = <<~HTML
+  <div>Hello <span>world</span></div>
+  <div>Hello</div>
+HTML
+
+# Matches <span>
+locator = page.get_by_text("world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<span>world</span>')
+
+# Matches first <div>
+locator = page.get_by_text("Hello world")
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+
+# Matches second <div>
+locator = page.get_by_text("Hello", exact: true)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches both <div>s
+locator = page.get_by_text(/Hello/)
+expect(locator.count).to eq(2)
+expect(locator.first.evaluate('e => e.outerHTML')).to eq('<div>Hello <span>world</span></div>')
+expect(locator.last.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+
+# Matches second <div>
+locator = page.get_by_text(/^hello$/i)
+expect(locator.evaluate('e => e.outerHTML')).to eq('<div>Hello</div>')
+```
+
+See also [Locator#filter](./locator#filter) that allows to match by another criteria, like an accessible role, and then filter
+by the text content.
+
+> NOTE: Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into
+one, turns line breaks into spaces and ignores leading and trailing whitespace.
+> NOTE: Input elements of the type `button` and `submit` are matched by their `value` instead of the text content. For
+example, locating by text `"Log in"` matches `<input type=button value="Log in">`.
+
+## get_by_title
+
+```
+def get_by_title(text, exact: nil)
+```
+
+Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
+
+```html
+<button title='Place the order'>Order Now</button>
+```
+
+
 ## go_back
 
 ```
@@ -670,6 +828,7 @@ def hover(
       selector,
       force: nil,
       modifiers: nil,
+      noWaitAfter: nil,
       position: nil,
       strict: nil,
       timeout: nil,
@@ -780,14 +939,12 @@ considered not visible.
 def locator(selector, has: nil, hasText: nil)
 ```
 
-The method returns an element locator that can be used to perform actions on the page. Locator is resolved to the
-element immediately before performing an action, so a series of actions on the same locator can in fact be performed on
-different DOM elements. That would happen if the DOM structure between those actions has changed.
+The method returns an element locator that can be used to perform actions on this page / frame. Locator is resolved to
+the element immediately before performing an action, so a series of actions on the same locator can in fact be performed
+on different DOM elements. That would happen if the DOM structure between those actions has changed.
 
 [Learn more about locators](https://playwright.dev/python/docs/locators).
 
-Shortcut for main frame's [Frame#locator](./frame#locator).
-
 ## main_frame
 
 ```
@@ -1364,7 +1521,7 @@ value. Will throw an error if the page is closed before the event is fired. Retu
 
 ```ruby
 frame = page.expect_event("framenavigated") do
-  page.click("button")
+  page.get_by_role("button")
 end
 ```
 
@@ -1415,13 +1572,13 @@ This resolves when the page reaches a required load state, `load` by default. Th
 when this method is called. If current document has already reached the required state, resolves immediately.
 
 ```ruby
-page.click("button") # click triggers navigation.
+page.get_by_role("button").click # click triggers navigation.
 page.wait_for_load_state # the promise resolves after "load" event.
 ```
 
 ```ruby
 popup = page.expect_popup do
-  page.click("button") # click triggers a popup.
+  page.get_by_role("button").click # click triggers a popup.
 end
 
 # Following resolves after "domcontentloaded" event.

data/documentation/docs/api/request.md

@@ -15,7 +15,7 @@ the  [`event: Page.requestFailed`] event is emitted.
 > NOTE: HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will
 complete with `'requestfinished'` event.
 
-If request gets a 'redirect' response, the request is successfully finished with the 'requestfinished' event, and a new
+If request gets a 'redirect' response, the request is successfully finished with the `requestfinished` event, and a new
 request is  issued to a redirected url.
 
 ## all_headers

data/documentation/docs/api/tracing.md

@@ -58,7 +58,7 @@ page = context.new_page
 page.goto("https://playwright.dev")
 
 context.tracing.start_chunk
-page.locator("text=Get Started").click
+page.get_by_text("Get Started").click
 # Everything between start_chunk and stop_chunk will be recorded in the trace.
 context.tracing.stop_chunk(path: "trace1.zip")
 

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

@@ -95,6 +95,7 @@ These parameters can be passed into `Capybara::Playwright::Driver.new`
   * record_video_dir
   * record_video_size
   * screen
+  * serviceWorkers
   * storageState
   * timezoneId
   * userAgent

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

@@ -84,3 +84,62 @@ describe 'example', driver: :null do
   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/include/api_coverage.md

@@ -159,6 +159,13 @@
 * frame_element
 * frame_locator
 * get_attribute
+* get_by_alt_text
+* get_by_label
+* get_by_placeholder
+* get_by_role
+* get_by_test_id
+* get_by_text
+* get_by_title
 * goto
 * hover
 * inner_html
@@ -204,6 +211,7 @@
 ## Selectors
 
 * register
+* ~~set_test_id_attribute~~
 
 ## ConsoleMessage
 
@@ -258,6 +266,13 @@
 * frame_locator
 * frames
 * get_attribute
+* get_by_alt_text
+* get_by_label
+* get_by_placeholder
+* get_by_role
+* get_by_test_id
+* get_by_text
+* get_by_title
 * go_back
 * go_forward
 * goto
@@ -405,8 +420,10 @@
 
 * all_inner_texts
 * all_text_contents
+* blur
 * bounding_box
 * check
+* clear
 * click
 * count
 * dblclick
@@ -423,6 +440,13 @@
 * focus
 * frame_locator
 * get_attribute
+* get_by_alt_text
+* get_by_label
+* get_by_placeholder
+* get_by_role
+* get_by_test_id
+* get_by_text
+* get_by_title
 * highlight
 * hover
 * inner_html
@@ -455,6 +479,13 @@
 
 * first
 * frame_locator
+* get_by_alt_text
+* get_by_label
+* get_by_placeholder
+* get_by_role
+* get_by_test_id
+* get_by_text
+* get_by_title
 * last
 * locator
 * nth
@@ -490,6 +521,7 @@
 
 ## Android
 
+* ~~connect~~
 * devices
 * ~~set_default_timeout~~