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

data/documentation/docs/api/mouse.md

@@ -66,3 +66,14 @@ def up(button: nil, clickCount: nil)
 ```
 
 Dispatches a `mouseup` event.
+
+## wheel
+
+```
+def wheel(deltaX, deltaY)
+```
+
+Dispatches a `wheel` event.
+
+> NOTE: Wheel events may cause scrolling if they are not handled, and this method does not wait for the scrolling to
+finish before returning.

data/documentation/docs/api/page.md

@@ -281,7 +281,7 @@ def drag_and_drop(
 ## emulate_media
 
 ```
-def emulate_media(colorScheme: nil, media: nil, reducedMotion: nil)
+def emulate_media(colorScheme: nil, forcedColors: nil, media: nil, reducedMotion: nil)
 ```
 
 This method changes the `CSS media type` through the `media` argument, and/or the `'prefers-colors-scheme'` media
@@ -622,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).
@@ -758,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
@@ -935,7 +933,7 @@ last redirect.
 ## route
 
 ```
-def route(url, handler)
+def route(url, handler, times: nil)
 ```
 
 Routing provides the capability to modify network requests that are made by a page.
@@ -943,6 +941,9 @@ Routing provides the capability to modify network requests that are made by a pa
 Once routing is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
 
 > NOTE: The handler will only be called for the first url if the response is a redirect.
+> NOTE: [Page#route](./page#route) will not intercept requests intercepted by Service Worker. See
+[this](https://github.com/microsoft/playwright/issues/1090) issue. We recommend disabling Service Workers when using
+request interception. Via `await context.addInitScript(() => delete window.navigator.serviceWorker);`
 
 An example of a naive handler that aborts all image requests:
 
@@ -1032,6 +1033,36 @@ page.select_option("select#colors", value: ["red", "green", "blue"])
 
 Shortcut for main frame's [Frame#select_option](./frame#select_option).
 
+## set_checked
+
+```
+def set_checked(
+      selector,
+      checked,
+      force: nil,
+      noWaitAfter: nil,
+      position: nil,
+      strict: nil,
+      timeout: nil,
+      trial: nil)
+```
+
+This method checks or unchecks an element matching `selector` by performing the following steps:
+1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
+1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
+1. If the element already has the right checked state, this method returns immediately.
+1. Wait for [actionability](https://playwright.dev/python/docs/actionability) checks on the matched element, unless `force` option is set. If the
+   element is detached during the checks, the whole action is retried.
+1. Scroll the element into view if needed.
+1. Use [Page#mouse](./page#mouse) to click in the center of the element.
+1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
+1. Ensure that the element is now checked or unchecked. If not, this method throws.
+
+When all steps combined have not finished during the specified `timeout`, this method throws a `TimeoutError`. Passing
+zero timeout disables this.
+
+Shortcut for main frame's [Frame#set_checked](./frame#set_checked).
+
 ## set_content
 
 ```

data/documentation/docs/api/request.md

@@ -18,6 +18,14 @@ complete with `'requestfinished'` event.
 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
+
+```
+def all_headers
+```
+
+An object with all the request HTTP headers associated with this request. The header names are lower-cased.
+
 ## failure
 
 ```
@@ -48,7 +56,24 @@ Returns the [Frame](./frame) that initiated this request.
 def headers
 ```
 
-An object with HTTP headers associated with the request. All header names are lower-case.
+**DEPRECATED** Incomplete list of headers as seen by the rendering engine. Use [Request#all_headers](./request#all_headers) instead.
+
+## headers_array
+
+```
+def headers_array
+```
+
+An array with all the request HTTP headers associated with this request. Unlike [Request#all_headers](./request#all_headers), header
+names are NOT lower-cased. Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
+
+## header_value
+
+```
+def header_value(name)
+```
+
+Returns the value of the header matching the name. The name is case insensitive.
 
 ## navigation_request?
 
@@ -156,6 +181,14 @@ def response
 
 Returns the matching [Response](./response) object, or `null` if the response was not received due to error.
 
+## sizes
+
+```
+def sizes
+```
+
+Returns resource size information for given request.
+
 ## timing
 
 ```

data/documentation/docs/api/response.md

@@ -6,6 +6,14 @@ sidebar_position: 10
 
 [Response](./response) class represents responses which are received by page.
 
+## all_headers
+
+```
+def all_headers
+```
+
+An object with all the response HTTP headers associated with this response.
+
 ## body
 
 ```
@@ -20,7 +28,7 @@ Returns the buffer with response body.
 def finished
 ```
 
-Waits for this response to finish, returns failure error if request failed.
+Waits for this response to finish, returns always `null`.
 
 ## frame
 
@@ -36,7 +44,34 @@ Returns the [Frame](./frame) that initiated this response.
 def headers
 ```
 
-Returns the object with HTTP headers associated with the response. All header names are lower-case.
+**DEPRECATED** Incomplete list of headers as seen by the rendering engine. Use [Response#all_headers](./response#all_headers) instead.
+
+## headers_array
+
+```
+def headers_array
+```
+
+An array with all the request HTTP headers associated with this response. Unlike [Response#all_headers](./response#all_headers), header
+names are NOT lower-cased. Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
+
+## header_value
+
+```
+def header_value(name)
+```
+
+Returns the value of the header matching the name. The name is case insensitive. If multiple headers have the same name
+(except `set-cookie`), they are returned as a list separated by `, `. For `set-cookie`, the `\n` separator is used. If
+no headers are found, `null` is returned.
+
+## header_values
+
+```
+def header_values(name)
+```
+
+Returns all values of the headers matching the name, for example `set-cookie`. The name is case insensitive.
 
 ## json
 

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

@@ -4,16 +4,15 @@ sidebar_position: 10
 
 # Tracing
 
-API for collecting and saving Playwright traces. Playwright traces can be opened using the Playwright CLI after
-Playwright script runs.
+API for collecting and saving Playwright traces. Playwright traces can be opened in [Trace Viewer](https://playwright.dev/python/docs/trace-viewer)
+after Playwright script runs.
 
-Start with specifying the folder traces will be stored in:
+Start recording a trace before performing actions. At the end, stop tracing and save it to a file.
 
 ```ruby
-browser.new_page do |page|
-  context = page.context
-
+browser.new_context do |context|
   context.tracing.start(screenshots: true, snapshots: true)
+  page = context.new_page
   page.goto('https://playwright.dev')
   context.tracing.stop(path: 'trace.zip')
 end
@@ -30,15 +29,42 @@ def start(name: nil, screenshots: nil, snapshots: nil)
 Start tracing.
 
 ```ruby
-context = page.context
-
 context.tracing.start(name: 'trace', screenshots: true, snapshots: true)
+page = context.new_page
 page.goto('https://playwright.dev')
 context.tracing.stop(path: 'trace.zip')
 ```
 
 
 
+## start_chunk
+
+```
+def start_chunk
+```
+
+Start a new trace chunk. If you'd like to record multiple traces on the same [BrowserContext](./browser_context), use
+[Tracing#start](./tracing#start) once, and then create multiple trace chunks with [Tracing#start_chunk](./tracing#start_chunk) and
+[Tracing#stop_chunk](./tracing#stop_chunk).
+
+```ruby
+context.tracing.start(name: "trace", screenshots: true, snapshots: true)
+page = context.new_page
+page.goto("https://playwright.dev")
+
+context.tracing.start_chunk
+page.click("text=Get Started")
+# Everything between start_chunk and stop_chunk will be recorded in the trace.
+context.tracing.stop_chunk(path: "trace1.zip")
+
+context.tracing.start_chunk
+page.goto("http://example.com")
+# Save a second trace file with different actions.
+context.tracing.stop_chunk(path: "trace2.zip")
+```
+
+
+
 ## stop
 
 ```
@@ -46,3 +72,11 @@ def stop(path: nil)
 ```
 
 Stop tracing.
+
+## stop_chunk
+
+```
+def stop_chunk(path: nil)
+```
+
+Stop the trace chunk. See [Tracing#start_chunk](./tracing#start_chunk) for more details about multiple trace chunks.

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

@@ -4,7 +4,14 @@ sidebar_position: 0
 
 # Getting started
 
-`playwright-ruby-client` doesn't include Playwright driver nor its downloader. **We have to install Playwright in advance**
+```
+gem 'playwright-ruby-client'
+```
+
+Add the line above and then `bundle install`.
+
+
+Since `playwright-ruby-client` doesn't include Playwright driver nor its downloader, **we have to install Playwright in advance**
 
 ```shell
 $ npx playwright install
@@ -12,6 +19,8 @@ $ npx playwright install
 
 and then set `playwright_cli_executable_path: "npx playwright"` into `Playwright.create`.
 
+Other methods of installation is also available. See the detail in [Download Playwright driver](./guides/download_playwright_driver)
+
 ## Enjoy with examples
 
 ### Capture a site

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

@@ -12,6 +12,15 @@ Choose any of the three ways as you prefer to download the driver:
 * `npm install`: the best choice for most use cases, with existing Node.js environment.
 * Direct download: maybe a good choice for Docker :whale: integration.
 
+:::note
+
+Also the article [Playwright on Alpine Linux](./playwright_on_alpine_linux) would be helpful if you plan to
+
+* Build a browser server/container like Selenium Grid
+* Run automation scripts on Alpine Linux
+
+:::
+
 ## Using `npx`
 
 ```shell

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

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

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 40
 ---
 
 # Playwright on Alpine Linux
@@ -33,7 +33,23 @@ Playwright server is running on a container of [official Docker image](https://h
 
 ![overview](https://user-images.githubusercontent.com/11763113/124934448-ad4d0700-e03f-11eb-942e-b9f3282bb703.png)
 
-## Playwright client
+### Playwright Server v.s. Browser Server
+
+Playwright provides two kind of methods to share the browser environments for clients.
+
+When you want to share only one browser environment, Browser server is suitable. This feature is officially supported in Playwright.
+
+* Server can be launched with [BrowserType#launchServer](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server) instead of `BrowserType#launch`.
+* Client can connect to server with [BrowserType#connect](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). In playwright-ruby-client, `BrowserType#connect` and not implemented yet and use `Playwright#connect_to_browser_server()` instead.
+
+Another method is sharing all browser environment. This method is very simple, but not an official feature, and can be changed in future.
+
+* Server can be launched with `playwright run-server` (CLI command).
+* Client can connect to server with `Playwright.connect_to_playwright_server` instead of `Playwright.create`
+
+## Playwright server/client
+
+### Client code
 
 Many example uses `Playwright#create`, which internally uses Pipe (stdin/stdout) transport for Playwright-protocol messaging. Instead, **just use `Playwright#connect_to_playwright_server(endpoint)`** for WebSocket transport.
 
@@ -51,7 +67,7 @@ end
 
 `wss://example.com:8888/ws` is an example of endpoint URL of the Playwright server. In local development environment, it is typically `"ws://127.0.0.1:#{port}/ws"`.
 
-## Playwright server
+### Server code
 
 With the [official Docker image](https://hub.docker.com/_/microsoft-playwright) or in the local development environment with Node.js, just execute `npx playwright install && npx playwright run-server $PORT`. (`$PORT` is a port number of the server)
 
@@ -67,6 +83,43 @@ ENV PORT 8888
 CMD ["./node_modules/.bin/playwright", "run-server", "$PORT"]
 ```
 
+## Browser server/client
+
+### Client code
+
+Use `Playwright#connect_to_playwright_server` and pass the WebSocket URL for browser server.
+Note that this method requires a block with `Browser`, not `Playwright` or `BrowserType`.
+
+```ruby
+Playwright.connect_to_playwright_server(ws_url) do |browser|
+  page = browser.new_page
+  page.goto(...)
+  ...
+end
+```
+
+### Server code
+
+For instant use, `npx playwright launch-server chromium` generates a WebSocket endpoint URL with a random path.
+
+More customization can be done by implementing JavaScript server like below:
+
+```js
+const playwright = require('playwright')
+
+option = {
+  channel: 'chrome-canary',
+  headless: false,
+  port: 8080,
+  wsPath: 'ws',
+}
+playwright.chromium.launchServer(option).then((server) => { console.log(server.wsEndpoint()) })
+```
+
+`port` and `wsPath` would be useful for generating static WebSocket endpoint URL.
+Other available options for `BrowserType#launchServer` can be found here:
+https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server
+
 ## Debugging for connection
 
 The client and server are really quiet. This chapter shows how to check if the communication on the WebSocket works well or not.