playwright-ruby-client 1.26.0 → 1.27.0

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,103 @@ 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,
+      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.
+
+## 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 "Submit":
+
+```html
+<button title='Place the order'>Order Now</button>
+```
+
+
 ## go_back
 
 ```
@@ -780,14 +891,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 +1473,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 +1524,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/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_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
@@ -423,6 +438,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 +477,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

data/lib/playwright/channel_owners/frame.rb

@@ -1,6 +1,10 @@
+require_relative '../locator_utils'
+
 module Playwright
   # @ref https://github.com/microsoft/playwright-python/blob/master/playwright/_impl/_frame.py
   define_channel_owner :Frame do
+    include LocatorUtils
+
     private def after_initialize
       if @initializer['parentFrame']
         @parent_frame = ChannelOwners::Frame.from(@initializer['parentFrame'])

data/lib/playwright/channel_owners/page.rb

@@ -1,9 +1,11 @@
 require 'base64'
+require_relative '../locator_utils'
 
 module Playwright
   # @ref https://github.com/microsoft/playwright-python/blob/master/playwright/_impl/_page.py
   define_channel_owner :Page do
     include Utils::Errors::SafeCloseError
+    include LocatorUtils
     attr_writer :owned_context
 
     private def after_initialize

data/lib/playwright/channel_owners/selectors.rb

@@ -18,5 +18,9 @@ module Playwright
 
       nil
     end
+
+    def text_id_attribute=(attribute_name)
+      ::Playwright::LocatorUtils.instance_variable_set(:@test_id_attribute_name, attribute_name)
+    end
   end
 end

data/lib/playwright/frame_locator_impl.rb

@@ -1,5 +1,9 @@
+require_relative './locator_utils'
+
 module Playwright
   define_api_implementation :FrameLocatorImpl do
+    include LocatorUtils
+
     def initialize(frame:, timeout_settings:, frame_selector:)
       @frame = frame
       @timeout_settings = timeout_settings
@@ -10,7 +14,7 @@ module Playwright
       LocatorImpl.new(
         frame: @frame,
         timeout_settings: @timeout_settings,
-        selector: "#{@frame_selector} >> control=enter-frame >> #{selector}",
+        selector: "#{@frame_selector} >> internal:control=enter-frame >> #{selector}",
         hasText: hasText,
         has: has,
       )
@@ -20,7 +24,7 @@ module Playwright
       FrameLocatorImpl.new(
         frame: @frame,
         timeout_settings: @timeout_settings,
-        frame_selector: "#{@frame_selector} >> control=enter-frame >> #{selector}",
+        frame_selector: "#{@frame_selector} >> internal:control=enter-frame >> #{selector}",
       )
     end
 

data/lib/playwright/locator_impl.rb

@@ -1,49 +1,25 @@
 require 'json'
+require_relative './locator_utils'
 
 module Playwright
-  class EscapeWithQuotes
-    def initialize(text, char = "'")
-      stringified = text.to_json
-      escaped_text = stringified[1...-1].gsub(/\\"/, '"')
-
-      case char
-      when '"'
-        text = escaped_text.gsub(/["]/, '\\"')
-        @text = "\"#{text}\""
-      when "'"
-        text = escaped_text.gsub(/[']/, '\\\'')
-        @text = "'#{text}'"
-      else
-        raise ArgumentError.new('Invalid escape char')
-      end
-    end
-
-    def to_s
-      @text
-    end
-  end
-
   define_api_implementation :LocatorImpl do
+    include LocatorUtils
+
     def initialize(frame:, timeout_settings:, selector:, hasText: nil, has: nil)
       @frame = frame
       @timeout_settings = timeout_settings
       selector_scopes = [selector]
 
-      case hasText
-      when Regexp
-        regex = JavaScript::Regex.new(hasText)
-        source = EscapeWithQuotes.new(regex.source, '"')
-        selector_scopes << "has=#{"text=/#{regex.source}/#{regex.flag}".to_json}"
-      when String
-        text = EscapeWithQuotes.new(hasText, '"')
-        selector_scopes << ":scope:has-text(#{text})"
+      if hasText
+        text_selector = "text=#{escape_for_text_selector(hasText, false)}"
+        selector_scopes << "internal:has=#{text_selector.to_json}"
       end
 
       if has
         unless same_frame?(has)
           raise DifferentFrameError.new
         end
-        selector_scopes << "has=#{has.send(:selector_json)}"
+        selector_scopes << "internal:has=#{has.send(:selector_json)}"
       end
 
       @selector = selector_scopes.join(' >> ')

data/lib/playwright/locator_utils.rb

@@ -0,0 +1,142 @@
+module Playwright
+  module LocatorUtils
+    def get_by_test_id(test_id)
+      locator(get_by_test_id_selector(test_id))
+    end
+
+    def get_by_alt_text(text, exact: false)
+      locator(get_by_alt_text_selector(text, exact: exact))
+    end
+
+    def get_by_label(text, exact: false)
+      locator(get_by_label_selector(text, exact: exact))
+    end
+
+    def get_by_placeholder(text, exact: false)
+      locator(get_by_placeholder_selector(text, exact: exact))
+    end
+
+    def get_by_text(text, exact: false)
+      locator(get_by_text_selector(text, exact: exact))
+    end
+
+    def get_by_title(text, exact: false)
+      locator(get_by_title_selector(text, exact: exact))
+    end
+
+    def get_by_role(role, **options)
+      locator(get_by_role_selector(role, **(options.compact)))
+    end
+
+    # set from Playwright::Selectors#test_id_attribute=
+    @test_id_attribute_name = 'data-testid'
+
+    private def get_by_attribute_text_selector(attr_name, text, exact: false)
+      "internal:attr=[#{attr_name}=#{escape_for_attribute_selector_or_regex(text, exact)}]"
+    end
+
+    private def get_by_test_id_selector(test_id)
+      get_by_attribute_text_selector(
+        ::Playwright::LocatorUtils.instance_variable_get(:@test_id_attribute_name),
+        test_id,
+        exact: true)
+    end
+
+    private def get_by_label_selector(text, exact:)
+      "internal:label=#{escape_for_text_selector(text, exact)}"
+    end
+
+    private def get_by_alt_text_selector(text, exact:)
+      get_by_attribute_text_selector('alt', text, exact: exact)
+    end
+
+    private def get_by_title_selector(text, exact:)
+      get_by_attribute_text_selector('title', text, exact: exact)
+    end
+
+    private def get_by_placeholder_selector(text, exact:)
+      get_by_attribute_text_selector('placeholder', text, exact: exact)
+    end
+
+    private def get_by_text_selector(text, exact:)
+      "text=#{escape_for_text_selector(text, exact)}"
+    end
+
+    private def get_by_role_selector(role, **options)
+      props = []
+
+      ex = {
+        includeHidden: -> (value) { ['include-hidden', value.to_s] },
+        name: -> (value) { ['name', escape_for_attribute_selector_or_regex(value, false)]},
+      }
+
+      %i[
+        checked
+        disabled
+        selected
+        expanded
+        includeHidden
+        level
+        name
+        pressed
+      ].each do |attr_name|
+        if options.key?(attr_name)
+          attr_value = options[attr_name]
+          props << ex[attr_name]&.call(attr_value) || [attr_name, attr_value.to_s]
+        end
+      end
+
+      opts = props.map { |k, v| "[#{k}=#{v}]"}.join('')
+      "role=#{role}#{opts}"
+    end
+
+    # @param text [String]
+    private def escape_for_regex(text)
+      text.gsub(/[.*+?^>${}()|\[\]\\]/) { "\\#{$&}" }
+    end
+
+    # @param text [Regexp|String]
+    private def escape_for_text_selector(text, exact)
+      if text.is_a?(Regexp)
+        regex = JavaScript::Regex.new(text)
+        return "/#{regex.source}/#{regex.flag}"
+      end
+
+      if exact
+        _text = text.gsub(/["]/, '\\"')
+        return "\"#{_text}\""
+      end
+
+      if text.include?('"') || text.include?('>>') || text.start_with?('/')
+        _text = escape_for_regex(text).gsub(/\s+/, '\\s+')
+        return "/#{_text}/i"
+      end
+
+      text
+    end
+
+    # @param text [Regexp|String]
+    private def escape_for_attribute_selector_or_regex(text, exact)
+      if text.is_a?(Regexp)
+        regex = JavaScript::Regex.new(text)
+        "/#{regex.source}/#{regex.flag}"
+      else
+        escape_for_attribute_selector(text, exact)
+      end
+    end
+
+    # @param text [String]
+    private def escape_for_attribute_selector(text, exact)
+      # TODO: this should actually be
+      # cssEscape(value).replace(/\\ /g, ' ')
+      # However, our attribute selectors do not conform to CSS parsing spec,
+      # so we escape them differently.
+      _text = text.gsub(/["]/, '\\"')
+      if exact
+        "\"#{_text}\""
+      else
+        "\"#{_text}\"i"
+      end
+    end
+  end
+end

data/lib/playwright/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Playwright
-  VERSION = '1.26.0'
-  COMPATIBLE_PLAYWRIGHT_VERSION = '1.26.0'
+  VERSION = '1.27.0'
+  COMPATIBLE_PLAYWRIGHT_VERSION = '1.27.0'
 end