playwright-ruby-client 0.7.1 → 1.14.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8e3e3982a30add91ed67641a29dcff9778c40788c8434d2ef581cb926951968
-  data.tar.gz: bc7c51236c2d9c2632c53dfe25ae7f9f357c1118a434bb1c41f735a0c67c7625
+  metadata.gz: 301191e26a4aa496f59d5feb5bed3c8438d5de5dfaa3e769dea1dae12dfe091c
+  data.tar.gz: 19fb694b3528977da5f934eff87432fff83a89072de874531fae3ab489f30e41
 SHA512:
-  metadata.gz: b438126a715d3c427408fb4d0b13483bb6f96444cb9c359a946da70125f00b0eee488e5753493a5f9e37ff1294209fd58a044721e0c7b0b2e5c06ef2a8611aef
-  data.tar.gz: a13605776cfca08333630a2e18cf53035d71b6b0ea454a27f76bf0562ef1d505844c70b1119bdca2c2cfd400d402d2c62e06fe38d53abf561c005b6127900c83
+  metadata.gz: b0c3f28732256000b39c835cc6d38cd1f942c6e9defaa6e1aaf2f4269ba3e121422c0feebb76653ec323b64420bc24418b73ca1fc1fa98a7188e257f6e0ab359
+  data.tar.gz: 1c7ba51eef58fe196bee1411fd9b3da95f3f1a66cf150ce69a614e51511aad081fb7a18b8befdcc9ce2f7ebacae82e8ecb90f0a099b01530d3b7897f22c12142

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/accessibility.md

@@ -4,4 +4,55 @@ sidebar_position: 10
 
 # Accessibility
 
-Not Implemented
+The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by
+assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or
+[switches](https://en.wikipedia.org/wiki/Switch_access).
+
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might
+have wildly different output.
+
+Rendering engines of Chromium, Firefox and WebKit have a concept of "accessibility tree", which is then translated into
+different platform-specific APIs. Accessibility namespace gives access to this Accessibility Tree.
+
+Most of the accessibility tree gets filtered out when converting from internal browser AX Tree to Platform-specific
+AX-Tree or by assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing
+only the "interesting" nodes of the tree.
+
+## snapshot
+
+```
+def snapshot(interestingOnly: nil, root: nil)
+```
+
+Captures the current state of the accessibility tree. The returned object represents the root accessible node of the
+page.
+
+> NOTE: The Chromium accessibility tree contains nodes that go unused on most platforms and by most screen readers.
+Playwright will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`.
+
+An example of dumping the entire accessibility tree:
+
+```python sync title=example_2e5019929403491cde0c78bed1e0e18e0c86ab423d7ac8715876c4de4814f483.py
+snapshot = page.accessibility.snapshot()
+print(snapshot)
+
+```
+
+An example of logging the focused node's name:
+
+```python sync title=example_df2acadf9e261a7624d83399f0d8b0910293a6a7081c812474715f22f8af7a4a.py
+def find_focused_node(node):
+    if (node.get("focused"))
+        return node
+    for child in (node.get("children") or []):
+        found_node = find_focused_node(child)
+        return found_node
+    return None
+
+snapshot = page.accessibility.snapshot()
+node = find_focused_node(snapshot)
+if node:
+    print(node["name"])
+
+```
+

data/documentation/docs/api/browser.md

@@ -76,6 +76,7 @@ Returns the newly created browser session.
 ```
 def new_context(
       acceptDownloads: nil,
+      baseURL: nil,
       bypassCSP: nil,
       colorScheme: nil,
       deviceScaleFactor: nil,
@@ -124,6 +125,7 @@ end
 ```
 def new_page(
       acceptDownloads: nil,
+      baseURL: nil,
       bypassCSP: nil,
       colorScheme: nil,
       deviceScaleFactor: nil,
@@ -164,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.
@@ -185,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

@@ -67,6 +67,16 @@ browser_context.add_init_script(path: "preload.js")
 > NOTE: The order of evaluation of multiple scripts installed via [BrowserContext#add_init_script](./browser_context#add_init_script) and
 [Page#add_init_script](./page#add_init_script) is not defined.
 
+## background_pages
+
+```
+def background_pages
+```
+
+> NOTE: Background pages are only supported on Chromium-based browsers.
+
+All existing background pages in the context.
+
 ## browser
 
 ```
@@ -301,6 +311,16 @@ To remove a route with its handler you can use [BrowserContext#unroute](./browse
 
 > NOTE: Enabling routing disables http cache.
 
+## service_workers
+
+```
+def service_workers
+```
+
+> NOTE: Service workers are only supported on Chromium-based browsers.
+
+All existing service workers in the context.
+
 ## set_default_navigation_timeout
 
 ```
@@ -369,6 +389,14 @@ alias: `offline=`
 
 
 
+## storage_state
+
+```
+def storage_state(path: nil)
+```
+
+Returns storage state for this browser context, contains current cookies and local storage snapshot.
+
 ## unroute
 
 ```

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/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
@@ -849,6 +910,17 @@ with sync_playwright() as playwright:
 
 
 
+## wait_for_timeout
+
+```
+def wait_for_timeout(timeout)
+```
+
+Waits for the given `timeout` in milliseconds.
+
+Note that `frame.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going to
+be flaky. Use signals such as network events, selectors becoming visible and others instead.
+
 ## wait_for_url
 
 ```