playwright-ruby-client 0.0.8 → 1.58.1.alpha1

data/documentation/docs/api/api_request_context.md

@@ -0,0 +1,298 @@
+---
+sidebar_position: 10
+---
+
+# APIRequestContext
+
+
+This API is used for the Web API testing. You can use it to trigger API endpoints, configure micro-services, prepare
+environment or the service to your e2e test.
+
+Each Playwright browser context has associated with it [APIRequestContext](./api_request_context) instance which shares cookie storage with
+the browser context and can be accessed via [BrowserContext#request](./browser_context#request) or [Page#request](./page#request).
+It is also possible to create a new APIRequestContext instance manually by calling [APIRequest#new_context](./api_request#new_context).
+
+**Cookie management**
+
+[APIRequestContext](./api_request_context) returned by [BrowserContext#request](./browser_context#request) and [Page#request](./page#request) shares cookie
+storage with the corresponding [BrowserContext](./browser_context). Each API request will have `Cookie` header populated with the
+values from the browser context. If the API response contains `Set-Cookie` header it will automatically update
+[BrowserContext](./browser_context) cookies and requests made from the page will pick them up. This means that if you log in using
+this API, your e2e test will be logged in and vice versa.
+
+If you want API requests to not interfere with the browser cookies you should create a new [APIRequestContext](./api_request_context) by
+calling [APIRequest#new_context](./api_request#new_context). Such [APIRequestContext](./api_request_context) object will have its own isolated cookie
+storage.
+
+```ruby
+playwright.chromium.launch do |browser|
+  # This will launch a new browser, create a context and page. When making HTTP
+  # requests with the internal APIRequestContext (e.g. `context.request` or `page.request`)
+  # it will automatically set the cookies to the browser page and vise versa.
+  context = browser.new_context(base_url: 'https://api.github,com')
+  api_request_context = context.request
+
+
+  # Create a repository.
+  response = api_request_context.post(
+    "/user/repos",
+    headers: {
+      "Accept": "application/vnd.github.v3+json",
+      "Authorization": "Bearer #{API_TOKEN}",
+    },
+    data: { name: 'test-repo-1' },
+  )
+  response.ok? # => true
+  response.json['name'] # => "test-repo-1"
+
+  # Delete a repository.
+  response = api_request_context.delete(
+    "/repos/YourName/test-repo-1",
+    headers: {
+      "Accept": "application/vnd.github.v3+json",
+      "Authorization": "Bearer #{API_TOKEN}",
+    },
+  )
+  response.ok? # => true
+end
+```
+
+## delete
+
+```
+def delete(
+      url,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) [DELETE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) request and returns its response.
+The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.
+
+## dispose
+
+```
+def dispose(reason: nil)
+```
+
+
+All responses returned by [APIRequestContext#get](./api_request_context#get) and similar methods are stored in the memory, so that you can later call [APIResponse#body](./api_response#body).This method discards all its resources, calling any method on disposed [APIRequestContext](./api_request_context) will throw an exception.
+
+## fetch
+
+```
+def fetch(
+      urlOrRequest,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      method: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) request and returns its response. The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.
+
+**Usage**
+
+JSON objects can be passed directly to the request:
+
+```ruby
+data = {
+  title: "Book Title",
+  body: "John Doe",
+}
+api_request_context.fetch("https://example.com/api/create_book", method: 'post', data: data)
+```
+
+The common way to send file(s) in the body of a request is to upload them as form fields with `multipart/form-data` encoding, by specifiying the `multipart` parameter:
+
+```ruby
+api_request_context.fetch(
+  "https://example.com/api/upload_script",
+  method: 'post',
+  multipart: {
+    fileField: {
+      name: "f.js",
+      mimeType: "text/javascript",
+      buffer: "console.log(2022);",
+    },
+  },
+)
+```
+
+## get
+
+```
+def get(
+      url,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) [GET](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) request and returns its response.
+The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.
+
+**Usage**
+
+Request parameters can be configured with `params` option, they will be serialized into the URL search parameters:
+
+```ruby
+query_params = {
+  isbn: "1234",
+  page: "23"
+}
+api_request_context.get("https://example.com/api/get_text", params: query_params)
+```
+
+## head
+
+```
+def head(
+      url,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) [HEAD](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) request and returns its response.
+The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.
+
+## patch
+
+```
+def patch(
+      url,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) [PATCH](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) request and returns its response.
+The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.
+
+## post
+
+```
+def post(
+      url,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) [POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request and returns its response.
+The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.
+
+**Usage**
+
+JSON objects can be passed directly to the request:
+
+```ruby
+data = {
+  title: "Book Title",
+  body: "John Doe",
+}
+api_request_context.post("https://example.com/api/create_book", data: data)
+```
+
+To send form data to the server use `form` option. Its value will be encoded into the request body with `application/x-www-form-urlencoded` encoding (see below how to use `multipart/form-data` form encoding to send files):
+
+```ruby
+form_data = {
+  title: "Book Title",
+  body: "John Doe",
+}
+api_request_context.post("https://example.com/api/find_book", form: form_data)
+```
+
+The common way to send file(s) in the body of a request is to upload them as form fields with `multipart/form-data` encoding. Use `FormData` to construct request body and pass it to the request as `multipart` parameter:
+
+```ruby
+api_request_context.post(
+  "https://example.com/api/upload_script",
+  multipart: {
+    fileField: {
+      name: "f.js",
+      mimeType: "text/javascript",
+      buffer: "console.log(2022);",
+    },
+  },
+)
+```
+
+## put
+
+```
+def put(
+      url,
+      data: nil,
+      failOnStatusCode: nil,
+      form: nil,
+      headers: nil,
+      ignoreHTTPSErrors: nil,
+      maxRedirects: nil,
+      maxRetries: nil,
+      multipart: nil,
+      params: nil,
+      timeout: nil)
+```
+
+
+Sends HTTP(S) [PUT](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) request and returns its response.
+The method will populate request cookies from the context and update
+context cookies from the response. The method will automatically follow redirects.

data/documentation/docs/api/api_response.md

@@ -0,0 +1,114 @@
+---
+sidebar_position: 10
+---
+
+# APIResponse
+
+
+[APIResponse](./api_response) class represents responses returned by [APIRequestContext#get](./api_request_context#get) and similar methods.
+
+```ruby
+playwright.chromium.launch do |browser|
+  context = browser.new_context
+  response = context.request.get("https://example.com/user/repos")
+
+  response.ok? # => true
+  response.status # => 200
+  response.headers["content-type"] # => "application/json; charset=utf-8"
+  response.json # => { "name" => "Foo" }
+  response.body # => "{ \"name\" => \"Foo\" }"
+end
+```
+
+## body
+
+```
+def body
+```
+
+
+Returns the buffer with response body.
+
+## dispose
+
+```
+def dispose
+```
+
+
+Disposes the body of this response. If not called then the body will stay in memory until the context closes.
+
+## headers
+
+```
+def headers
+```
+
+
+An object with all the response HTTP headers associated with this response.
+
+## headers_array
+
+```
+def headers_array
+```
+
+
+An array with all the response HTTP headers associated with this response. Header names are not lower-cased.
+Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
+
+## json
+
+```
+def json
+```
+
+
+Returns the JSON representation of response body.
+
+This method will throw if the response body is not parsable via `JSON.parse`.
+
+## ok
+
+```
+def ok
+```
+
+
+Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
+
+## status
+
+```
+def status
+```
+
+
+Contains the status code of the response (e.g., 200 for a success).
+
+## status_text
+
+```
+def status_text
+```
+
+
+Contains the status text of the response (e.g. usually an "OK" for a success).
+
+## text
+
+```
+def text
+```
+
+
+Returns the text representation of response body.
+
+## url
+
+```
+def url
+```
+
+
+Contains the URL of the response.

data/documentation/docs/api/browser.md

@@ -0,0 +1,237 @@
+---
+sidebar_position: 10
+---
+
+# Browser
+
+
+A Browser is created via [BrowserType#launch](./browser_type#launch). An example of using a [Browser](./browser) to create a [Page](./page):
+
+```ruby
+firefox = playwright.firefox
+browser = firefox.launch
+begin
+  page = browser.new_page
+  page.goto("https://example.com")
+ensure
+  browser.close
+end
+```
+
+## browser_type
+
+```
+def browser_type
+```
+
+
+Get the browser type (chromium, firefox or webkit) that the browser belongs to.
+
+## close
+
+```
+def close(reason: nil)
+```
+
+
+In case this browser is obtained using [BrowserType#launch](./browser_type#launch), closes the browser and all of its pages (if any
+were opened).
+
+In case this browser is connected to, clears all created contexts belonging to this browser and disconnects from the
+browser server.
+
+**NOTE**: This is similar to force-quitting the browser. To close pages gracefully and ensure you receive page close events, call [BrowserContext#close](./browser_context#close) on any [BrowserContext](./browser_context) instances you explicitly created earlier using [Browser#new_context](./browser#new_context) **before** calling [Browser#close](./browser#close).
+
+The [Browser](./browser) object itself is considered to be disposed and cannot be used anymore.
+
+## contexts
+
+```
+def contexts
+```
+
+
+Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts.
+
+**Usage**
+
+```ruby
+playwright.webkit.launch do |browser|
+  puts browser.contexts.count # => 0
+  context = browser.new_context
+  puts browser.contexts.count # => 1
+end
+```
+
+## connected?
+
+```
+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,
+      clientCertificates: nil,
+      colorScheme: nil,
+      contrast: nil,
+      deviceScaleFactor: nil,
+      extraHTTPHeaders: nil,
+      forcedColors: nil,
+      geolocation: nil,
+      hasTouch: nil,
+      httpCredentials: nil,
+      ignoreHTTPSErrors: nil,
+      isMobile: nil,
+      javaScriptEnabled: nil,
+      locale: nil,
+      noViewport: nil,
+      offline: nil,
+      permissions: nil,
+      proxy: nil,
+      record_har_content: nil,
+      record_har_mode: nil,
+      record_har_omit_content: nil,
+      record_har_path: nil,
+      record_har_url_filter: nil,
+      record_video_dir: nil,
+      record_video_size: nil,
+      reducedMotion: nil,
+      screen: nil,
+      serviceWorkers: nil,
+      storageState: nil,
+      strictSelectors: nil,
+      timezoneId: nil,
+      userAgent: nil,
+      viewport: nil,
+      &block)
+```
+
+
+Creates a new browser context. It won't share cookies/cache with other browser contexts.
+
+**NOTE**: If directly using this method to create [BrowserContext](./browser_context)s, it is best practice to explicitly close the returned context via [BrowserContext#close](./browser_context#close) when your code is done with the [BrowserContext](./browser_context),
+and before calling [Browser#close](./browser#close). This will ensure the `context` is closed gracefully and any artifacts—like HARs and videos—are fully flushed and saved.
+
+**Usage**
+
+```ruby
+playwright.firefox.launch do |browser| # or "chromium.launch" or "webkit.launch".
+  # create a new incognito browser context.
+  browser.new_context do |context|
+    # create a new page in a pristine context.
+    page = context.new_page
+    page.goto("https://example.com")
+  end
+end
+```
+
+## new_page
+
+```
+def new_page(
+      acceptDownloads: nil,
+      baseURL: nil,
+      bypassCSP: nil,
+      clientCertificates: nil,
+      colorScheme: nil,
+      contrast: nil,
+      deviceScaleFactor: nil,
+      extraHTTPHeaders: nil,
+      forcedColors: nil,
+      geolocation: nil,
+      hasTouch: nil,
+      httpCredentials: nil,
+      ignoreHTTPSErrors: nil,
+      isMobile: nil,
+      javaScriptEnabled: nil,
+      locale: nil,
+      noViewport: nil,
+      offline: nil,
+      permissions: nil,
+      proxy: nil,
+      record_har_content: nil,
+      record_har_mode: nil,
+      record_har_omit_content: nil,
+      record_har_path: nil,
+      record_har_url_filter: nil,
+      record_video_dir: nil,
+      record_video_size: nil,
+      reducedMotion: nil,
+      screen: nil,
+      serviceWorkers: nil,
+      storageState: nil,
+      strictSelectors: nil,
+      timezoneId: nil,
+      userAgent: nil,
+      viewport: nil,
+      &block)
+```
+
+
+Creates a new page in a new browser context. Closing this page will close the context as well.
+
+This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and
+testing frameworks should explicitly create [Browser#new_context](./browser#new_context) followed by the
+[BrowserContext#new_page](./browser_context#new_page) to control their exact life times.
+
+## start_tracing
+
+```
+def start_tracing(page: nil, categories: nil, path: nil, screenshots: nil)
+```
+
+
+**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.
+
+**Usage**
+
+```ruby
+browser.start_tracing(page: page, path: "trace.json")
+begin
+  page.goto("https://www.google.com")
+ensure
+  browser.stop_tracing
+end
+```
+
+## stop_tracing
+
+```
+def stop_tracing
+```
+
+
+**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.
+
+## version
+
+```
+def version
+```
+
+
+Returns the browser version.