playwright-ruby-client 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9342eb9d31cb69d5eee5734d2143505672336cb630599f5d92a3e07559b76421
-  data.tar.gz: 66a5f38c686c7477037740cddf2d6572b63b21dd791f92a0c179fd292ee0b8e6
+  metadata.gz: 5c0e5286a6e8faaa590ce17ed083f4e6f93c54fb6899571c5edc2a99c4148b15
+  data.tar.gz: bccd47264ec992c5c901c94faf28ec346a606d75e4636ae80828e5d64a685bf0
 SHA512:
-  metadata.gz: 9adc1be3cbef06c38bcb1080e26c8b816311dc81573b6d089f55fd286e9e29d9a29831f1655a2d8189d1c20ed6bea0fd108a98ed347d4c1c1281753d64cddd2b
-  data.tar.gz: f65e5ff953e8b1f6ef54a031cda1a53819bdb0c62caa44b5dc34a2011bc1d72d867a838de98bc7e2cbc8b0d34899cf19b6b89c4d008aa7a98f60871e91b3021e
+  metadata.gz: c34792ec1bb838c99b5a540833c7e02c718147738d2b6129eb9ba63f53e6d6d1460e5abc62f9e94fecec2bc9dd07321c9badc1c4e4173ae0548151ebcbc38e12
+  data.tar.gz: 12b99906a534b8ec3a5eef041824ec4d0357fe70e3a1c696dc4f11a95c1b54edbe8c7a5d67694c7b9dc846bd34fa6e18fbb3d84f241aa345a1d89c8af4ac4a39

data/README.md

@@ -159,6 +159,32 @@ end
 
 ```
 
+### Communicate with Playwright server
+
+If your environment doesn't accept installing browser or creating browser process, consider separating Ruby client and Playwright server.
+
+![structure](https://user-images.githubusercontent.com/11763113/124934448-ad4d0700-e03f-11eb-942e-b9f3282bb703.png)
+
+For launching Playwright server, just execute:
+
+```
+npx playwright install && npx playwright run-server 8080
+```
+
+and we can connect to the server with the code like this:
+
+```ruby
+Playwright.connect_to_playwright_server('ws://127.0.0.1:8080') do |playwright|
+  playwright.chromium.launch do |browser|
+    page = browser.new_page
+    page.goto('https://github.com/YusukeIwaki')
+    page.screenshot(path: './YusukeIwaki.png')
+  end
+end
+```
+
+When `Playwright.connect_to_playwright_server` is used, playwright_cli_executable_path is not required.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/documentation/docs/api/browser.md

@@ -61,11 +61,22 @@ def connected?
 
 Indicates that the browser is connected.
 
+## new_browser_cdp_session
+
+```
+def new_browser_cdp_session
+```
+
+> NOTE: CDP Sessions are only supported on Chromium-based browsers.
+
+Returns the newly created browser session.
+
 ## new_context
 
 ```
 def new_context(
       acceptDownloads: nil,
+      baseURL: nil,
       bypassCSP: nil,
       colorScheme: nil,
       deviceScaleFactor: nil,
@@ -114,6 +125,7 @@ end
 ```
 def new_page(
       acceptDownloads: nil,
+      baseURL: nil,
       bypassCSP: nil,
       colorScheme: nil,
       deviceScaleFactor: nil,
@@ -154,7 +166,9 @@ testing frameworks should explicitly create [Browser#new_context](./browser#new_
 def start_tracing(page: nil, categories: nil, path: nil, screenshots: nil)
 ```
 
-> NOTE: Tracing is only supported on Chromium-based browsers.
+> NOTE: This API controls [Chromium Tracing](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)
+which is a low-level chromium-specific debugging tool. API to control [Playwright Tracing](https://playwright.dev/python/docs/trace-viewer) could be
+found [here](./tracing).
 
 You can use [Browser#start_tracing](./browser#start_tracing) and [Browser#stop_tracing](./browser#stop_tracing) to create a trace file that can be
 opened in Chrome DevTools performance panel.
@@ -175,7 +189,9 @@ end
 def stop_tracing
 ```
 
-> NOTE: Tracing is only supported on Chromium-based browsers.
+> NOTE: This API controls [Chromium Tracing](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)
+which is a low-level chromium-specific debugging tool. API to control [Playwright Tracing](https://playwright.dev/python/docs/trace-viewer) could be
+found [here](./tracing).
 
 Returns the buffer with trace data.
 

data/documentation/docs/api/browser_context.md

@@ -226,6 +226,16 @@ def grant_permissions(permissions, origin: nil)
 Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if
 specified.
 
+## new_cdp_session
+
+```
+def new_cdp_session(page)
+```
+
+> NOTE: CDP sessions are only supported on Chromium-based browsers.
+
+Returns the newly created session.
+
 ## new_page
 
 ```

data/documentation/docs/api/browser_type.md

@@ -103,6 +103,7 @@ def launch_persistent_context(
       userDataDir,
       acceptDownloads: nil,
       args: nil,
+      baseURL: nil,
       bypassCSP: nil,
       channel: nil,
       chromiumSandbox: nil,

data/documentation/docs/api/cdp_session.md

@@ -4,4 +4,44 @@ sidebar_position: 10
 
 # CDPSession
 
-Not Implemented
+- extends: [EventEmitter]
+
+The [CDPSession](./cdp_session) instances are used to talk raw Chrome Devtools Protocol:
+- protocol methods can be called with `session.send_message` method.
+- protocol events can be subscribed to with `session.on` method.
+
+Useful links:
+- Documentation on DevTools Protocol can be found here:
+  [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/).
+- Getting Started with DevTools Protocol:
+  https://github.com/aslushnikov/getting-started-with-cdp/blob/master/README.md
+
+```ruby
+client = page.context.new_cdp_session(page)
+client.send_message('Animation.enable')
+client.on('Animation.animationCreated', -> (_) { puts 'Animation Created' })
+response = client.send_message('Animation.getPlaybackRate')
+puts "Playback rate is #{response['playbackRate']}"
+client.send_message(
+  'Animation.setPlaybackRate',
+  params: { playbackRate: response['playbackRate'] / 2.0 },
+)
+```
+
+
+## detach
+
+```
+def detach
+```
+
+Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used to
+send messages.
+
+## send_message
+
+```
+def send_message(method, params: nil)
+```
+
+

data/documentation/docs/api/download.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 10
+---
+
+# Download
+
+[Download](./download) objects are dispatched by page via the [`event: Page.download`] event.
+
+All the downloaded files belonging to the browser context are deleted when the browser context is closed.
+
+Download event is emitted once the download starts. Download path becomes available once download completes:
+
+```ruby
+download = page.expect_download do
+  page.click('a')
+end
+
+# wait for download to complete
+path = download.path
+```
+
+> NOTE: Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the
+downloaded content. If `acceptDownloads` is not set, download events are emitted, but the actual download is not
+performed and user has no access to the downloaded files.
+
+## cancel
+
+```
+def cancel
+```
+
+Cancels a download. Will not fail if the download is already finished or canceled. Upon successful cancellations,
+`download.failure()` would resolve to `'canceled'`.
+
+## delete
+
+```
+def delete
+```
+
+Deletes the downloaded file. Will wait for the download to finish if necessary.
+
+## failure
+
+```
+def failure
+```
+
+Returns download error if any. Will wait for the download to finish if necessary.
+
+## page
+
+```
+def page
+```
+
+Get the page that the download belongs to.
+
+## path
+
+```
+def path
+```
+
+Returns path to the downloaded file in case of successful download. The method will wait for the download to finish if
+necessary. The method throws when connected remotely.
+
+Note that the download's file name is a random GUID, use [Download#suggested_filename](./download#suggested_filename) to get suggested file
+name.
+
+## save_as
+
+```
+def save_as(path)
+```
+
+Copy the download to a user-specified path. It is safe to call this method while the download is still in progress. Will
+wait for the download to finish if necessary.
+
+## suggested_filename
+
+```
+def suggested_filename
+```
+
+Returns suggested filename for this download. It is typically computed by the browser from the
+[`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header
+or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different
+browsers can use different logic for computing it.
+
+## url
+
+```
+def url
+```
+
+Returns downloaded url.

data/documentation/docs/api/element_handle.md

@@ -10,10 +10,8 @@ ElementHandle represents an in-page DOM element. ElementHandles can be created w
 method.
 
 ```ruby
-page.goto("https://example.com")
 href_element = page.query_selector("a")
 href_element.click
-# ...
 ```
 
 ElementHandle prevents DOM element from garbage collection unless the handle is disposed with
@@ -22,6 +20,33 @@ ElementHandle prevents DOM element from garbage collection unless the handle is
 ElementHandle instances can be used as an argument in [Page#eval_on_selector](./page#eval_on_selector) and [Page#evaluate](./page#evaluate)
 methods.
 
+> NOTE: In most cases, you would want to use the [Locator](./locator) object instead. You should only use [ElementHandle](./element_handle) if you
+want to retain a handle to a particular DOM Node that you intend to pass into [Page#evaluate](./page#evaluate) as an argument.
+
+The difference between the [Locator](./locator) and ElementHandle is that the ElementHandle points to a particular element, while
+[Locator](./locator) captures the logic of how to retrieve an element.
+
+In the example below, handle points to a particular DOM element on page. If that element changes text or is used by
+React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to
+unexpected behaviors.
+
+```ruby
+handle = page.query_selector("text=Submit")
+handle.hover
+handle.click
+```
+
+With the locator, every time the `element` is used, up-to-date DOM element is located in the page using the selector. So
+in the snippet below, underlying DOM element is going to be located twice.
+
+```ruby
+locator = page.locator("text=Submit")
+locator.hover
+locator.click
+```
+
+
+
 ## bounding_box
 
 ```
@@ -232,7 +257,7 @@ feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)
 ## fill
 
 ```
-def fill(value, noWaitAfter: nil, timeout: nil)
+def fill(value, force: nil, noWaitAfter: nil, timeout: nil)
 ```
 
 This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the element, fills it and triggers an `input`
@@ -300,6 +325,14 @@ def inner_text
 
 Returns the `element.innerText`.
 
+## input_value
+
+```
+def input_value(timeout: nil)
+```
+
+Returns `input.value` for `<input>` or `<textarea>` element. Throws for non-input elements.
+
 ## checked?
 
 ```
@@ -436,6 +469,7 @@ def select_option(
       index: nil,
       value: nil,
       label: nil,
+      force: nil,
       noWaitAfter: nil,
       timeout: nil)
 ```
@@ -470,7 +504,7 @@ element_handle.select_option(value: "blue", index: 2, label: "red")
 ## select_text
 
 ```
-def select_text(timeout: nil)
+def select_text(force: nil, timeout: nil)
 ```
 
 This method waits for [actionability](https://playwright.dev/python/docs/actionability) checks, then focuses the element and selects all its text

data/documentation/docs/api/experimental/android_device.md

@@ -28,6 +28,7 @@ Returns information about a widget defined by `selector`.
 ```
 def launch_browser(
       acceptDownloads: nil,
+      baseURL: nil,
       bypassCSP: nil,
       colorScheme: nil,
       command: nil,

data/documentation/docs/api/frame.md

@@ -68,6 +68,7 @@ def check(
       force: nil,
       noWaitAfter: nil,
       position: nil,
+      strict: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -106,6 +107,7 @@ def click(
       modifiers: nil,
       noWaitAfter: nil,
       position: nil,
+      strict: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -140,6 +142,7 @@ def dblclick(
       modifiers: nil,
       noWaitAfter: nil,
       position: nil,
+      strict: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -161,7 +164,12 @@ zero timeout disables this.
 ## dispatch_event
 
 ```
-def dispatch_event(selector, type, eventInit: nil, timeout: nil)
+def dispatch_event(
+      selector,
+      type,
+      eventInit: nil,
+      strict: nil,
+      timeout: nil)
 ```
 
 The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the element,
@@ -196,10 +204,25 @@ frame.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })
 
 
 
+## drag_and_drop
+
+```
+def drag_and_drop(
+      source,
+      target,
+      force: nil,
+      noWaitAfter: nil,
+      strict: nil,
+      timeout: nil,
+      trial: nil)
+```
+
+
+
 ## eval_on_selector
 
 ```
-def eval_on_selector(selector, expression, arg: nil)
+def eval_on_selector(selector, expression, arg: nil, strict: nil)
 ```
 
 Returns the return value of `expression`.
@@ -326,7 +349,13 @@ result_handle.dispose
 ## fill
 
 ```
-def fill(selector, value, noWaitAfter: nil, timeout: nil)
+def fill(
+      selector,
+      value,
+      force: nil,
+      noWaitAfter: nil,
+      strict: nil,
+      timeout: nil)
 ```
 
 This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/python/docs/actionability) checks, focuses the
@@ -343,7 +372,7 @@ To send fine-grained keyboard events, use [Frame#type](./frame#type).
 ## focus
 
 ```
-def focus(selector, timeout: nil)
+def focus(selector, strict: nil, timeout: nil)
 ```
 
 This method fetches an element with `selector` and focuses it. If there's no element matching `selector`, the method
@@ -374,7 +403,7 @@ assert frame == content_frame
 ## get_attribute
 
 ```
-def get_attribute(selector, name, timeout: nil)
+def get_attribute(selector, name, strict: nil, timeout: nil)
 ```
 
 Returns element attribute value.
@@ -412,6 +441,7 @@ def hover(
       force: nil,
       modifiers: nil,
       position: nil,
+      strict: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -430,7 +460,7 @@ zero timeout disables this.
 ## inner_html
 
 ```
-def inner_html(selector, timeout: nil)
+def inner_html(selector, strict: nil, timeout: nil)
 ```
 
 Returns `element.innerHTML`.
@@ -438,15 +468,23 @@ Returns `element.innerHTML`.
 ## inner_text
 
 ```
-def inner_text(selector, timeout: nil)
+def inner_text(selector, strict: nil, timeout: nil)
 ```
 
 Returns `element.innerText`.
 
+## input_value
+
+```
+def input_value(selector, strict: nil, timeout: nil)
+```
+
+Returns `input.value` for the selected `<input>` or `<textarea>` element. Throws for non-input elements.
+
 ## checked?
 
 ```
-def checked?(selector, timeout: nil)
+def checked?(selector, strict: nil, timeout: nil)
 ```
 
 Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
@@ -462,7 +500,7 @@ Returns `true` if the frame has been detached, or `false` otherwise.
 ## disabled?
 
 ```
-def disabled?(selector, timeout: nil)
+def disabled?(selector, strict: nil, timeout: nil)
 ```
 
 Returns whether the element is disabled, the opposite of [enabled](https://playwright.dev/python/docs/actionability).
@@ -470,7 +508,7 @@ Returns whether the element is disabled, the opposite of [enabled](https://playw
 ## editable?
 
 ```
-def editable?(selector, timeout: nil)
+def editable?(selector, strict: nil, timeout: nil)
 ```
 
 Returns whether the element is [editable](https://playwright.dev/python/docs/actionability).
@@ -478,7 +516,7 @@ Returns whether the element is [editable](https://playwright.dev/python/docs/act
 ## enabled?
 
 ```
-def enabled?(selector, timeout: nil)
+def enabled?(selector, strict: nil, timeout: nil)
 ```
 
 Returns whether the element is [enabled](https://playwright.dev/python/docs/actionability).
@@ -486,7 +524,7 @@ Returns whether the element is [enabled](https://playwright.dev/python/docs/acti
 ## hidden?
 
 ```
-def hidden?(selector, timeout: nil)
+def hidden?(selector, strict: nil, timeout: nil)
 ```
 
 Returns whether the element is hidden, the opposite of [visible](https://playwright.dev/python/docs/actionability).  `selector` that does not
@@ -495,12 +533,24 @@ match any elements is considered hidden.
 ## visible?
 
 ```
-def visible?(selector, timeout: nil)
+def visible?(selector, strict: nil, timeout: nil)
 ```
 
 Returns whether the element is [visible](https://playwright.dev/python/docs/actionability). `selector` that does not match any elements is
 considered not visible.
 
+## locator
+
+```
+def locator(selector)
+```
+
+The method returns an element locator that can be used to perform actions in the 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.
+
+Note that locator always implies visibility, so it will always be locating visible elements.
+
 ## name
 
 ```
@@ -537,6 +587,7 @@ def press(
       key,
       delay: nil,
       noWaitAfter: nil,
+      strict: nil,
       timeout: nil)
 ```
 
@@ -560,7 +611,7 @@ modifier, modifier is pressed and being held while the subsequent key is being p
 ## query_selector
 
 ```
-def query_selector(selector)
+def query_selector(selector, strict: nil)
 ```
 
 Returns the ElementHandle pointing to the frame element.
@@ -588,7 +639,9 @@ def select_option(
       index: nil,
       value: nil,
       label: nil,
+      force: nil,
       noWaitAfter: nil,
+      strict: nil,
       timeout: nil)
 ```
 
@@ -627,7 +680,12 @@ alias: `content=`
 ## set_input_files
 
 ```
-def set_input_files(selector, files, noWaitAfter: nil, timeout: nil)
+def set_input_files(
+      selector,
+      files,
+      noWaitAfter: nil,
+      strict: nil,
+      timeout: nil)
 ```
 
 This method expects `selector` to point to an
@@ -645,6 +703,7 @@ def tap_point(
       modifiers: nil,
       noWaitAfter: nil,
       position: nil,
+      strict: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -665,7 +724,7 @@ zero timeout disables this.
 ## text_content
 
 ```
-def text_content(selector, timeout: nil)
+def text_content(selector, strict: nil, timeout: nil)
 ```
 
 Returns `element.textContent`.
@@ -686,6 +745,7 @@ def type(
       text,
       delay: nil,
       noWaitAfter: nil,
+      strict: nil,
       timeout: nil)
 ```
 
@@ -710,6 +770,7 @@ def uncheck(
       force: nil,
       noWaitAfter: nil,
       position: nil,
+      strict: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -817,7 +878,7 @@ considered a navigation.
 ## wait_for_selector
 
 ```
-def wait_for_selector(selector, state: nil, timeout: nil)
+def wait_for_selector(selector, state: nil, strict: nil, timeout: nil)
 ```
 
 Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or