playwright-ruby-client 0.0.8 → 1.58.1.alpha1

data/documentation/docs/api/route.md

@@ -0,0 +1,205 @@
+---
+sidebar_position: 10
+---
+
+# Route
+
+
+Whenever a network route is set up with [Page#route](./page#route) or [BrowserContext#route](./browser_context#route), the [Route](./route) object
+allows to handle the route.
+
+Learn more about [networking](https://playwright.dev/python/docs/network).
+
+## abort
+
+```
+def abort(errorCode: nil)
+```
+
+
+Aborts the route's request.
+
+## continue
+
+```
+def continue(headers: nil, method: nil, postData: nil, url: nil)
+```
+
+
+Sends route's request to the network with optional overrides.
+
+**Usage**
+
+```ruby
+def handle(route, request)
+  # override headers
+  headers = request.headers
+  headers['foo'] = 'bar' # set "foo" header
+  headers['user-agent'] = 'Unknown Browser' # modify user-agent
+  headers.delete('bar') # remove "bar" header
+
+  route.continue(headers: headers)
+end
+page.route("**/*", method(:handle))
+```
+
+**Details**
+
+The `headers` option applies to both the routed request and any redirects it initiates. However, `url`, `method`, and `postData` only apply to the original request and are not carried over to redirected requests.
+
+[Route#continue](./route#continue) will immediately send the request to the network, other matching handlers won't be invoked. Use [Route#fallback](./route#fallback) If you want next matching handler in the chain to be invoked.
+
+**NOTE**: Some request headers are **forbidden** and cannot be overridden (for example, `Cookie`, `Host`, `Content-Length` and others, see [this MDN page](https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_request_header) for full list).
+If an override is provided for a forbidden header, it will be ignored and the original request header will be used.
+
+To set custom cookies, use [BrowserContext#add_cookies](./browser_context#add_cookies).
+
+## fallback
+
+```
+def fallback(headers: nil, method: nil, postData: nil, url: nil)
+```
+
+
+Continues route's request with optional overrides. The method is similar to [Route#continue](./route#continue) with the difference that other matching handlers will be invoked before sending the request.
+
+**Usage**
+
+When several routes match the given pattern, they run in the order opposite to their registration.
+That way the last registered route can always override all the previous ones. In the example below,
+request will be handled by the bottom-most handler first, then it'll fall back to the previous one and
+in the end will be aborted by the first registered route.
+
+```ruby
+page.route("**/*", -> (route,_) { route.abort })  # Runs last.
+page.route("**/*", -> (route,_) { route.fallback })  # Runs second.
+page.route("**/*", -> (route,_) { route.fallback })  # Runs first.
+```
+
+Registering multiple routes is useful when you want separate handlers to
+handle different kinds of requests, for example API calls vs page resources or
+GET requests vs POST requests as in the example below.
+
+```ruby
+# Handle GET requests.
+def handle_post(route, request)
+  if request.method != "GET"
+    route.fallback
+    return
+  end
+
+  # Handling GET only.
+  # ...
+end
+
+# Handle POST requests.
+def handle_post(route, request)
+  if request.method != "POST"
+    route.fallback
+    return
+  end
+
+  # Handling POST only.
+  # ...
+end
+
+page.route("**/*", handle_get)
+page.route("**/*", handle_post)
+```
+
+One can also modify request while falling back to the subsequent handler, that way intermediate
+route handler can modify url, method, headers and postData of the request.
+
+```ruby
+def handle(route, request)
+  # override headers
+  headers = request.headers
+  headers['foo'] = 'bar' # set "foo" header
+  headers['user-agent'] = 'Unknown Browser' # modify user-agent
+  headers.delete('bar') # remove "bar" header
+
+  route.fallback(headers: headers)
+end
+page.route("**/*", method(:handle))
+```
+
+Use [Route#continue](./route#continue) to immediately send the request to the network, other matching handlers won't be invoked in that case.
+
+## fetch
+
+```
+def fetch(
+      headers: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      method: nil,
+      postData: nil,
+      timeout: nil,
+      url: nil)
+```
+
+
+Performs the request and fetches result without fulfilling it, so that the response
+could be modified and then fulfilled.
+
+**Usage**
+
+```ruby
+def handle(route, request)
+  response = route.fetch
+  json = response.json
+  json["message"]["big_red_dog"] = []
+
+  route.fulfill(response: response, json: json)
+end
+page.route("https://dog.ceo/api/breeds/list/all", method(:handle))
+```
+
+**Details**
+
+Note that `headers` option will apply to the fetched request as well as any redirects initiated by it. If you want to only apply `headers` to the original request, but not to redirects, look into [Route#continue](./route#continue) instead.
+
+## fulfill
+
+```
+def fulfill(
+      body: nil,
+      contentType: nil,
+      headers: nil,
+      json: nil,
+      path: nil,
+      response: nil,
+      status: nil)
+```
+
+
+Fulfills route's request with given response.
+
+**Usage**
+
+An example of fulfilling all requests with 404 responses:
+
+```ruby
+page.route("**/*", ->(route, request) {
+  route.fulfill(
+    status: 404,
+    contentType: 'text/plain',
+    body: 'not found!!',
+  )
+})
+```
+
+An example of serving static file:
+
+```ruby
+page.route("**/xhr_endpoint", ->(route, _) { route.fulfill(path: "mock_data.json") })
+```
+
+## request
+
+```
+def request
+```
+
+
+A request to be routed.

data/documentation/docs/api/selectors.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 10
+---
+
+# Selectors
+
+
+Selectors can be used to install custom selector engines. See [extensibility](https://playwright.dev/python/docs/extensibility) for more
+information.
+
+## register
+
+```
+def register(name, script: nil, contentScript: nil, path: nil)
+```
+
+
+Selectors must be registered before creating the page.
+
+**Usage**
+
+An example of registering selector engine that queries elements based on a tag name:
+
+```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.locator('tag=button')
+  # Combine it with other selector engines.
+  page.locator('tag=div').get_by_text('Click me').click
+
+  # Can use it in any methods supporting selectors.
+  button_count = page.locator('tag=button').count
+  button_count # => 1
+end
+```
+
+## set_test_id_attribute
+
+```
+def set_test_id_attribute(attributeName)
+```
+alias: `test_id_attribute=`
+
+
+Defines custom attribute name to be used in [Page#get_by_test_id](./page#get_by_test_id). `data-testid` is used by default.

data/documentation/docs/api/touchscreen.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 10
+---
+
+# Touchscreen
+
+
+The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the
+touchscreen can only be used in browser contexts that have been initialized with `hasTouch` set to true.
+
+This class is limited to emulating tap gestures. For examples of other gestures simulated by manually dispatching touch events, see the [emulating legacy touch events](https://playwright.dev/python/docs/touch-events) page.
+
+## tap_point
+
+```
+def tap_point(x, y)
+```
+
+
+Dispatches a `touchstart` and `touchend` event with a single touch at the position (`x`,`y`).
+
+**NOTE**: [Page#tap_point](./page#tap_point) the method will throw if `hasTouch` option of the browser context is false.

data/documentation/docs/api/tracing.md

@@ -0,0 +1,129 @@
+---
+sidebar_position: 10
+---
+
+# Tracing
+
+
+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.
+
+**NOTE**: You probably want to [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead of using `context.tracing`.
+
+The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions (like `expect` calls). We recommend [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), which includes those assertions and provides a more complete trace for debugging test failures.
+
+Start recording a trace before performing actions. At the end, stop tracing and save it to a file.
+
+```ruby
+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
+```
+
+## start
+
+```
+def start(
+      name: nil,
+      screenshots: nil,
+      snapshots: nil,
+      sources: nil,
+      title: nil)
+```
+
+
+Start tracing.
+
+**NOTE**: You probably want to [enable tracing in your config file](https://playwright.dev/docs/api/class-testoptions#test-options-trace) instead of using `Tracing.start`.
+
+The `context.tracing` API captures browser operations and network activity, but it doesn't record test assertions (like `expect` calls). We recommend [enabling tracing through Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace), which includes those assertions and provides a more complete trace for debugging test failures.
+
+**Usage**
+
+```ruby
+context.tracing.start(screenshots: true, snapshots: true)
+page = context.new_page
+page.goto('https://playwright.dev')
+context.tracing.stop(path: 'trace.zip')
+```
+
+## start_chunk
+
+```
+def start_chunk(name: nil, title: nil)
+```
+
+
+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).
+
+**Usage**
+
+```ruby
+context.tracing.start(screenshots: true, snapshots: true)
+page = context.new_page
+page.goto("https://playwright.dev")
+
+context.tracing.start_chunk
+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")
+
+context.tracing.start_chunk
+page.goto("http://example.com")
+# Save a second trace file with different actions.
+context.tracing.stop_chunk(path: "trace2.zip")
+```
+
+## group
+
+```
+def group(name, location: nil)
+```
+
+
+**NOTE**: Use `test.step` instead when available.
+
+Creates a new group within the trace, assigning any subsequent API calls to this group, until [Tracing#group_end](./tracing#group_end) is called. Groups can be nested and will be visible in the trace viewer.
+
+**Usage**
+
+```ruby
+# All actions between group and group_end
+# will be shown in the trace viewer as a group.
+context.tracing.group("Open Playwright.dev > API")
+
+page = context.new_page
+page.goto("https://playwright.dev/")
+page.get_by_role("link", name: "API").click
+
+context.tracing.group_end
+```
+
+## group_end
+
+```
+def group_end
+```
+
+
+Closes the last group created by [Tracing#group](./tracing#group).
+
+## stop
+
+```
+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/web_socket.md

@@ -0,0 +1,51 @@
+---
+sidebar_position: 10
+---
+
+# WebSocket
+
+
+The [WebSocket](./web_socket) class represents WebSocket connections within a page. It provides the ability to inspect and manipulate the data being transmitted and received.
+
+If you want to intercept or modify WebSocket frames, consider using `WebSocketRoute`.
+
+## closed?
+
+```
+def closed?
+```
+
+
+Indicates that the web socket has been closed.
+
+## url
+
+```
+def url
+```
+
+
+Contains the URL of the WebSocket.
+
+## expect_event
+
+```
+def expect_event(event, predicate: nil, timeout: nil, &block)
+```
+
+
+Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy
+value. Will throw an error if the webSocket is closed before the event is fired. Returns the event data value.
+
+## wait_for_event
+
+```
+def wait_for_event(event, predicate: nil, timeout: nil, &block)
+```
+
+
+**NOTE**: In most cases, you should use [WebSocket#wait_for_event](./web_socket#wait_for_event).
+
+Waits for given `event` to fire. If predicate is provided, it passes
+event's value into the `predicate` function and waits for `predicate(event)` to return a truthy value.
+Will throw an error if the socket is closed before the `event` is fired.

data/documentation/docs/api/worker.md

@@ -0,0 +1,83 @@
+---
+sidebar_position: 10
+---
+
+# Worker
+
+
+The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). `worker`
+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.
+
+```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
+```
+
+## evaluate
+
+```
+def evaluate(expression, arg: nil)
+```
+
+
+Returns the return value of `expression`.
+
+If the function passed to the [Worker#evaluate](./worker#evaluate) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Worker#evaluate](./worker#evaluate) would wait for the promise
+to resolve and return its value.
+
+If the function passed to the [Worker#evaluate](./worker#evaluate) returns a non-[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) value, then [Worker#evaluate](./worker#evaluate) returns `undefined`. Playwright also supports transferring some
+additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`.
+
+## evaluate_handle
+
+```
+def evaluate_handle(expression, arg: nil)
+```
+
+
+Returns the return value of `expression` as a [JSHandle](./js_handle).
+
+The only difference between [Worker#evaluate](./worker#evaluate) and
+[Worker#evaluate_handle](./worker#evaluate_handle) is that [Worker#evaluate_handle](./worker#evaluate_handle)
+returns [JSHandle](./js_handle).
+
+If the function passed to the [Worker#evaluate_handle](./worker#evaluate_handle) returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), then [Worker#evaluate_handle](./worker#evaluate_handle) would wait for
+the promise to resolve and return its value.
+
+## url
+
+```
+def url
+```
+
+
+
+## expect_event
+
+```
+def expect_event(event, predicate: nil, timeout: nil, &block)
+```
+
+
+Waits for event to fire and passes its value into the predicate function.
+Returns when the predicate returns truthy value.
+Will throw an error if the page is closed before the event is fired.
+Returns the event data value.
+
+**Usage**
+
+```ruby
+message = worker.expect_event("console") do
+  worker.evaluate("console.log(42)")
+end
+```

data/documentation/docs/article/api_coverage.mdx

@@ -0,0 +1,11 @@
+---
+position: 20
+---
+
+# API Coverages
+
+`playwright-ruby-client` doesn't cover all of the Playwright APIs. The APIs listed below without strikethrough are available in `playwright-ruby-client`.
+
+import ApiCoverage from '../include/api_coverage.md'
+
+<ApiCoverage />