playwright-ruby-client 1.14.beta1 → 1.15.beta1

data/documentation/docs/api/locator.md

@@ -7,10 +7,9 @@ sidebar_position: 10
 Locator represents a view to the element(s) on the page. It captures the logic sufficient to retrieve the element at any
 given moment. Locator can be created with the [Page#locator](./page#locator) method.
 
-```python sync title=example_9f72eed0cd4b2405e6a115b812b36ff2624e889f9086925c47665333a7edabbc.py
+```ruby
 locator = page.locator("text=Submit")
-locator.click()
-
+locator.click
 ```
 
 The difference between the Locator and [ElementHandle](./element_handle) is that the latter points to a particular element, while Locator
@@ -35,6 +34,19 @@ locator.hover
 locator.click
 ```
 
+**Strictness**
+
+Locators are strict. This means that all operations on locators that imply some target DOM element will throw if more
+than one element matches given selector.
+
+```ruby
+# Throws if there are several buttons in DOM:
+page.locator('button').click
+
+# Works because we explicitly tell locator to pick the first element:
+page.locator('button').first.click
+```
+
 
 
 ## all_inner_texts
@@ -72,10 +84,12 @@ Elements from child frames return the bounding box relative to the main frame, u
 Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following
 snippet should click the center of the element.
 
-```python sync title=example_4d635e937854fa2ee56b7c43151ded535940f0bbafc00cf48e8214bed86715eb.py
-box = element.bounding_box()
-page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
-
+```ruby
+box = element.bounding_box
+page.mouse.click(
+  box["x"] + box["width"] / 2,
+  box["y"] + box["height"] / 2,
+)
 ```
 
 
@@ -177,9 +191,8 @@ The snippet below dispatches the `click` event on the element. Regardless of the
 `click` is dispatched. This is equivalent to calling
 [element.click()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click).
 
-```python sync title=example_8d92b900a98c237ffdcb102ddc35660e37101bde7d107dc64d97a7edeed62a43.py
+```ruby
 element.dispatch_event("click")
-
 ```
 
 Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties
@@ -196,11 +209,10 @@ Since `eventInit` is event-specific, please refer to the events documentation fo
 
 You can also specify [JSHandle](./js_handle) as the property value if you want live objects to be passed into the event:
 
-```python sync title=example_e369442a3ff291ab476da408ef63a63dacf47984dc766ff7189d82008ae2848b.py
+```ruby
 # note you can only create data_transfer in chromium and firefox
 data_transfer = page.evaluate_handle("new DataTransfer()")
-element.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})
-
+element.dispatch_event("dragstart", eventInit: { dataTransfer: data_transfer })
 ```
 
 
@@ -236,10 +248,9 @@ If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web
 
 Examples:
 
-```python sync title=example_df39b3df921f81e7cfb71cd873b76a5e91e46b4aa41e1f164128cb322aa38305.py
-tweets = page.locator(".tweet .retweets")
-assert tweets.evaluate("node => node.innerText") == "10 retweets"
-
+```ruby
+tweet = page.query_selector(".tweet .retweets")
+tweet.evaluate("node => node.innerText") # => "10 retweets"
 ```
 
 
@@ -253,15 +264,14 @@ def evaluate_all(expression, arg: nil)
 The method finds all elements matching the specified locator and passes an array of matched elements as a first argument
 to `expression`. Returns the result of `expression` invocation.
 
-If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [`Locator.evaluateAll`] would wait for the promise to resolve and return its
-value.
+If `expression` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Locator#evaluate_all](./locator#evaluate_all) would wait for the promise to resolve and
+return its value.
 
 Examples:
 
-```python sync title=example_32478e941514ed28b6ac221e6d54b55cf117038ecac6f4191db676480ab68d44.py
+```ruby
 elements = page.locator("div")
-div_counts = elements("(divs, min) => divs.length >= min", 10)
-
+elements.evaluate_all("(divs, min) => divs.length >= min", arg: 10)
 ```
 
 
@@ -368,7 +378,7 @@ Returns the `element.innerText`.
 def input_value(timeout: nil)
 ```
 
-Returns `input.value` for `<input>` or `<textarea>` element. Throws for non-input elements.
+Returns `input.value` for `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
 
 ## checked?
 
@@ -518,26 +528,18 @@ Returns the array of option values that have been successfully selected.
 
 Triggers a `change` and `input` event once all the provided options have been selected.
 
-```python sync title=example_2825b0a50091868d1ce3ea0752d94ba32d826d504c1ac6842522796ca405913e.py
+```ruby
 # single selection matching the value
-element.select_option("blue")
+element.select_option(value: "blue")
 # single selection matching both the label
-element.select_option(label="blue")
+element.select_option(label: "blue")
 # multiple selection
-element.select_option(value=["red", "green", "blue"])
-
+element.select_option(value: ["red", "green", "blue"])
 ```
 
-```python sync title=example_3aaff4985dc38e64fad34696c88a6a68a633e26aabee6fc749125f3ee1784e34.py
-# single selection matching the value
-element.select_option("blue")
-# single selection matching both the value and the label
-element.select_option(label="blue")
-# multiple selection
-element.select_option("red", "green", "blue")
+```ruby
 # multiple selection for blue, red and second option
-element.select_option(value="blue", { index: 2 }, "red")
-
+element.select_option(value: "blue", index: 2, label: "red")
 ```
 
 
@@ -607,19 +609,17 @@ Focuses the element, and then sends a `keydown`, `keypress`/`input`, and `keyup`
 
 To press a special key, like `Control` or `ArrowDown`, use [Locator#press](./locator#press).
 
-```python sync title=example_fa1712c0b6ceb96fcaa74790d33f2c2eefe2bd1f06e61b78e0bb84a6f22c7961.py
+```ruby
 element.type("hello") # types instantly
-element.type("world", delay=100) # types slower, like a user
-
+element.type("world", delay: 100) # types slower, like a user
 ```
 
 An example of typing into a text field and then submitting the form:
 
-```python sync title=example_adefe90dee78708d4375c20f081f12f2b71f2becb472a2e0d4fdc8cc49c37809.py
+```ruby
 element = page.locator("input")
 element.type("some text")
 element.press("Enter")
-
 ```
 
 

data/documentation/docs/api/mouse.md

@@ -8,16 +8,15 @@ The Mouse class operates in main-frame CSS pixels relative to the top-left corne
 
 Every `page` object has its own Mouse, accessible with [Page#mouse](./page#mouse).
 
-```python sync title=example_ba01da1f358cafb4c22b792488ff2f3de4dbd82d4ee1cc4050e3f0c24a2bd7dd.py
+```ruby
 # using ‘page.mouse’ to trace a 100x100 square.
 page.mouse.move(0, 0)
-page.mouse.down()
+page.mouse.down
 page.mouse.move(0, 100)
 page.mouse.move(100, 100)
 page.mouse.move(100, 0)
 page.mouse.move(0, 0)
-page.mouse.up()
-
+page.mouse.up
 ```
 
 

data/documentation/docs/api/page.md

@@ -269,7 +269,9 @@ def drag_and_drop(
       target,
       force: nil,
       noWaitAfter: nil,
+      sourcePosition: nil,
       strict: nil,
+      targetPosition: nil,
       timeout: nil,
       trial: nil)
 ```
@@ -620,18 +622,18 @@ def goto(url, referer: nil, timeout: nil, waitUntil: nil)
 Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
 last redirect.
 
-`page.goto` will throw an error if:
+The method will throw an error if:
 - there's an SSL error (e.g. in case of self-signed certificates).
 - target URL is invalid.
 - the `timeout` is exceeded during navigation.
 - the remote server does not respond or is unreachable.
 - the main resource failed to load.
 
-`page.goto` will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not
+The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not
 Found" and 500 "Internal Server Error".  The status code for such responses can be retrieved by calling
 [Response#status](./response#status).
 
-> NOTE: `page.goto` either throws an error or returns a main resource response. The only exceptions are navigation to
+> NOTE: The method either throws an error or returns a main resource response. The only exceptions are navigation to
 `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
 > NOTE: Headless mode doesn't support navigation to a PDF document. See the
 [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
@@ -686,7 +688,7 @@ Returns `element.innerText`.
 def input_value(selector, strict: nil, timeout: nil)
 ```
 
-Returns `input.value` for the selected `<input>` or `<textarea>` element. Throws for non-input elements.
+Returns `input.value` for the selected `<input>` or `<textarea>` or `<select>` element. Throws for non-input elements.
 
 ## checked?
 
@@ -756,8 +758,6 @@ The method returns an element locator that can be used to perform actions on 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.
-
 Shortcut for main frame's [Frame#locator](./frame#locator).
 
 ## main_frame

data/documentation/docs/api/request.md

@@ -28,9 +28,8 @@ The method returns `null` unless this request has failed, as reported by `reques
 
 Example of logging of all the failed requests:
 
-```py title=example_5f3f4534ab17f584cfd41ca38448ce7de9490b6588e29e73116ede3cb15a25a5.py
-page.on("requestfailed", lambda request: print(request.url + " " + request.failure))
-
+```ruby
+page.on("requestfailed", ->(request) { puts "#{request.url} #{request.failure}" })
 ```
 
 
@@ -108,18 +107,17 @@ construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
 
 For example, if the website `http://example.com` redirects to `https://example.com`:
 
-```python sync title=example_89568fc86bf623eef37b68c6659b1a8524647c8365bb32a7a8af63bd86111075.py
-response = page.goto("http://example.com")
-print(response.request.redirected_from.url) # "http://example.com"
-
+```ruby
+response = page.goto("http://github.com")
+puts response.url # => "https://github.com"
+puts response.request.redirected_from&.url # => "http://github.com"
 ```
 
 If the website `https://google.com` has no redirects:
 
-```python sync title=example_6d7b3fbf8d69dbe639b71fedc5a8977777fca29dfb16d38012bb07c496342472.py
+```ruby
 response = page.goto("https://google.com")
-print(response.request.redirected_from) # None
-
+puts response.request.redirected_from&.url # => nil
 ```
 
 
@@ -134,9 +132,8 @@ New request issued by the browser if the server responded with redirect.
 
 This method is the opposite of [Request#redirected_from](./request#redirected_from):
 
-```py title=example_922623f4033e7ec2158787e54a8554655f7e1e20a024e4bf4f69337f781ab88a.py
-assert request.redirected_from.redirected_to == request
-
+```ruby
+request.redirected_from.redirected_to # equals to request
 ```
 
 
@@ -169,12 +166,11 @@ Returns resource timing information for given request. Most of the timing values
 `responseEnd` becomes available when request finishes. Find more information at
 [Resource Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
 
-```python sync title=example_e2a297fe95fd0699b6a856c3be2f28106daa2615c0f4d6084f5012682a619d20.py
-with page.expect_event("requestfinished") as request_info:
-    page.goto("http://example.com")
-request = request_info.value
-print(request.timing)
-
+```ruby
+request = page.expect_event("requestfinished") do
+  page.goto("https://example.com")
+end
+puts request.timing
 ```
 
 

data/documentation/docs/api/selectors.md

@@ -15,9 +15,35 @@ def register(name, contentScript: nil, path: nil, script: nil)
 
 An example of registering selector engine that queries elements based on a tag name:
 
-```python sync title=example_49f0cb9b5a21d0d5fe2b180c847bdb21068b335b4c2f42d5c05eb1957297899f.py
-# FIXME: add snippet
-
+```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.query_selector('tag=button')
+  # Combine it with other selector engines.
+  page.click('tag=div >> text="Click me"')
+
+  # Can use it in any methods supporting selectors.
+  button_count = page.eval_on_selector_all('tag=button', 'buttons => buttons.length')
+  button_count # => 1
+end
 ```
 
 

data/documentation/docs/api/tracing.md

@@ -9,13 +9,14 @@ Playwright script runs.
 
 Start with specifying the folder traces will be stored in:
 
-```python sync title=example_a767dfb400d98aef50f2767b94171d23474ea1ac1cf9b4d75d412936208e652d.py
-browser = chromium.launch()
-context = browser.new_context()
-context.tracing.start(screenshots=True, snapshots=True)
-page.goto("https://playwright.dev")
-context.tracing.stop(path = "trace.zip")
-
+```ruby
+browser.new_page do |page|
+  context = page.context
+
+  context.tracing.start(screenshots: true, snapshots: true)
+  page.goto('https://playwright.dev')
+  context.tracing.stop(path: 'trace.zip')
+end
 ```
 
 
@@ -28,12 +29,12 @@ def start(name: nil, screenshots: nil, snapshots: nil)
 
 Start tracing.
 
-```python sync title=example_e611abc8b1066118d0c87eae1bbbb08df655f36d50a94402fc56b8713150997b.py
-context.tracing.start(name="trace", screenshots=True, snapshots=True)
-page.goto("https://playwright.dev")
-context.tracing.stop()
-context.tracing.stop(path = "trace.zip")
+```ruby
+context = page.context
 
+context.tracing.start(name: 'trace', screenshots: true, snapshots: true)
+page.goto('https://playwright.dev')
+context.tracing.stop(path: 'trace.zip')
 ```
 
 

data/documentation/docs/api/worker.md

@@ -8,17 +8,18 @@ The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/do
 event is emitted on the page object to signal a worker creation. `close` event is emitted on the worker object when the
 worker is gone.
 
-```py title=example_29716fdd4471a97923a64eebeee96330ab508226a496ae8fd13f12eb07d55ee6.py
-def handle_worker(worker):
-    print("worker created: " + worker.url)
-    worker.on("close", lambda: print("worker destroyed: " + worker.url))
-
-page.on('worker', handle_worker)
-
-print("current workers:")
-for worker in page.workers:
-    print("    " + worker.url)
-
+```ruby
+def handle_worker(worker)
+  puts "worker created: #{worker.url}"
+  worker.once("close", -> (w) { puts "worker destroyed: #{w.url}" })
+end
+
+page.on('worker', method(:handle_worker))
+
+puts "current workers:"
+page.workers.each do |worker|
+  puts "    #{worker.url}"
+end
 ```
 
 

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Playwright inspector

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Playwright on Alpine Linux

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

@@ -10,7 +10,7 @@ This allow us to intermediate into automation, for example
 * Authenticate with OAuth2 manually before automation
 * Testing a page after some chrome extensions are installed manually
 
-Keep in mind repeatedly that persistent browser context is NOT RECOMMENDED for most cases because it would bring many side effects.
+Keep in mind repeatedly that persistent browser context is NOT RECOMMENDED for most cases because it would bring many side effects. Consider [reusing cookie and local storage](./use_storage_state) when you just want to keep authenticated across browser contexts.
 
 ## Pause automation for manual operation
 

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

@@ -0,0 +1,78 @@
+---
+sidebar_position: 6
+---
+
+# Reuse Cookie and LocalStorage
+
+In most cases, authentication state is stored in cookie or local storage. When we just want to keep authenticated, it is a good solution to dump/load 'storage state' (= Cookie + LocalStorage).
+https://playwright.dev/docs/next/auth#reuse-authentication-state
+
+* Dump storage state using [BrowserContext#storage_state](/docs/api/browser_context#storage_state) with `path: /path/to/state.json`
+* Load storage state by specifying the parameter `storageState: /path/to/state.json` into [Browser#new_context](/docs/api/browser#new_context) or [Browser#new_page](/docs/api/browser#new_page)
+
+## Example
+
+Generally in browser automation, it is very difficult to bypass 2FA or reCAPTCHA in login screen. In such cases, we would consider
+
+* Authenticate manually by hand
+* Resume automation with the authentication result
+
+
+```ruby {16,21}
+require 'playwright'
+require 'pry'
+
+force_login = !File.exist?('github_state.json')
+
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  if force_login
+    # Use headful mode for manual operation.
+    playwright.chromium.launch(headless: false, channel: 'chrome') do |browser|
+      page = browser.new_page
+      page.goto('https://github.com/login')
+
+      # Login manually.
+      binding.pry
+
+      page.context.storage_state(path: 'github_state.json')
+    end
+  end
+
+  playwright.chromium.launch do |browser|
+    page = browser.new_page(storageState: 'github_state.json')
+    page.goto('https://github.com/notifications')
+    page.screenshot(path: 'github_notification.png')
+  end
+end
+```
+
+When we execute this script at the first time (without github_state.json), login screen is shown:
+
+![login screen is shown](https://user-images.githubusercontent.com/11763113/129394130-7a248f6a-56f0-40b0-a4dd-f0f65d71b3a9.png)
+
+and input credentials manually:
+
+![input credentials manually](https://user-images.githubusercontent.com/11763113/129394155-fccc280e-5e6b-46c7-8a4d-a99d7db02c7f.png)
+
+and hit `exit` in Pry console.
+
+```
+
+     9:
+    10:     # Login manually. Hit `exit` in Pry console after authenticated.
+    11:     require 'pry'
+    12:     binding.pry
+    13:
+ => 14:     page.context.storage_state(path: 'github_state.json')
+    15:   end if force_login
+    16:
+    17:   playwright.chromium.launch do |browser|
+    18:     page = browser.new_page(storageState: 'github_state.json')
+    19:     page.goto('https://github.com/notifications')
+
+[1] pry(main)> exit
+```
+
+then we can enjoy automation with keeping authenticated. Login screen is never shown until github_state.json is deleted :)
+
+![github_notification.png](https://user-images.githubusercontent.com/11763113/129394879-838797eb-135f-41ab-b965-8d6fabde6109.png)