playwright-ruby-client 0.0.8 → 1.58.1.alpha1

data/lib/playwright_api/response.rb

@@ -1,80 +1,152 @@
 module Playwright
+  #
   # `Response` class represents responses which are received by page.
   class Response < PlaywrightApi
 
+    #
+    # An object with all the response HTTP headers associated with this response.
+    def all_headers
+      wrap_impl(@impl.all_headers)
+    end
+
+    #
     # Returns the buffer with response body.
     def body
-      raise NotImplementedError.new('body is not implemented yet.')
+      wrap_impl(@impl.body)
     end
 
-    # Waits for this response to finish, returns failure error if request failed.
+    #
+    # Waits for this response to finish, returns always `null`.
     def finished
-      raise NotImplementedError.new('finished is not implemented yet.')
+      wrap_impl(@impl.finished)
     end
 
+    #
     # Returns the `Frame` that initiated this response.
     def frame
-      raise NotImplementedError.new('frame is not implemented yet.')
+      wrap_impl(@impl.frame)
+    end
+
+    #
+    # Indicates whether this Response was fulfilled by a Service Worker's Fetch Handler (i.e. via [FetchEvent.respondWith](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/respondWith)).
+    def from_service_worker
+      wrap_impl(@impl.from_service_worker)
     end
 
-    # Returns the object with HTTP headers associated with the response. All header names are lower-case.
+    #
+    # An object with the response HTTP headers. The header names are lower-cased.
+    # Note that this method does not return security-related headers, including cookie-related ones.
+    # You can use [`method: Response.allHeaders`] for complete list of headers that include `cookie` information.
     def headers
-      raise NotImplementedError.new('headers is not implemented yet.')
+      wrap_impl(@impl.headers)
+    end
+
+    #
+    # An array with all the request HTTP headers associated with this response. Unlike [`method: Response.allHeaders`], header names are NOT lower-cased.
+    # Headers with multiple entries, such as `Set-Cookie`, appear in the array multiple times.
+    def headers_array
+      wrap_impl(@impl.headers_array)
+    end
+
+    #
+    # 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.
+    def header_value(name)
+      wrap_impl(@impl.header_value(unwrap_impl(name)))
+    end
+
+    #
+    # Returns all values of the headers matching the name, for example `set-cookie`. The name is case-insensitive.
+    def header_values(name)
+      wrap_impl(@impl.header_values(unwrap_impl(name)))
     end
 
+    #
     # Returns the JSON representation of response body.
-    # 
+    #
     # This method will throw if the response body is not parsable via `JSON.parse`.
     def json
-      raise NotImplementedError.new('json is not implemented yet.')
+      wrap_impl(@impl.json)
     end
 
+    #
     # Contains a boolean stating whether the response was successful (status in the range 200-299) or not.
     def ok
-      raise NotImplementedError.new('ok is not implemented yet.')
+      wrap_impl(@impl.ok)
     end
 
+    #
     # Returns the matching `Request` object.
     def request
-      raise NotImplementedError.new('request is not implemented yet.')
+      wrap_impl(@impl.request)
+    end
+
+    #
+    # Returns SSL and other security information.
+    def security_details
+      wrap_impl(@impl.security_details)
+    end
+
+    #
+    # Returns the IP address and port of the server.
+    def server_addr
+      wrap_impl(@impl.server_addr)
     end
 
+    #
     # Contains the status code of the response (e.g., 200 for a success).
     def status
-      raise NotImplementedError.new('status is not implemented yet.')
+      wrap_impl(@impl.status)
     end
 
+    #
     # Contains the status text of the response (e.g. usually an "OK" for a success).
     def status_text
-      raise NotImplementedError.new('status_text is not implemented yet.')
+      wrap_impl(@impl.status_text)
     end
 
+    #
     # Returns the text representation of response body.
     def text
-      raise NotImplementedError.new('text is not implemented yet.')
+      wrap_impl(@impl.text)
     end
 
+    #
     # Contains the URL of the response.
     def url
-      raise NotImplementedError.new('url is not implemented yet.')
+      wrap_impl(@impl.url)
+    end
+
+    # @nodoc
+    def ok?
+      wrap_impl(@impl.ok?)
+    end
+
+    # @nodoc
+    def from_service_worker?
+      wrap_impl(@impl.from_service_worker?)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def on(event, callback)
-      wrap_impl(@impl.on(unwrap_impl(event), unwrap_impl(callback)))
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def off(event, callback)
-      wrap_impl(@impl.off(unwrap_impl(event), unwrap_impl(callback)))
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
     end
 
     # -- inherited from EventEmitter --
     # @nodoc
-    def once(event, callback)
-      wrap_impl(@impl.once(unwrap_impl(event), unwrap_impl(callback)))
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
+    end
+
+    private def event_emitter_proxy
+      @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
     end
   end
 end

data/lib/playwright_api/route.rb

@@ -1,97 +1,157 @@
 module Playwright
+  #
   # Whenever a network route is set up with [`method: Page.route`] or [`method: BrowserContext.route`], the `Route` object
   # allows to handle the route.
+  #
+  # Learn more about [networking](../network.md).
   class Route < PlaywrightApi
 
+    #
     # Aborts the route's request.
     def abort(errorCode: nil)
-      raise NotImplementedError.new('abort is not implemented yet.')
+      wrap_impl(@impl.abort(errorCode: unwrap_impl(errorCode)))
     end
 
-    # Continues route's request with optional overrides.
-    # 
-    #
-    # ```js
-    # await page.route('**/*', (route, request) => {
-    #   // Override headers
-    #   const headers = {
-    #     ...request.headers(),
-    #     foo: 'bar', // set "foo" header
-    #     origin: undefined, // remove "origin" header
-    #   };
-    #   route.continue({headers});
-    # });
-    # ```
-    # 
-    # ```python async
-    # async def handle(route, request):
+    #
+    # Sends route's request to the network with optional overrides.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # def handle(route, request):
     #     # override headers
     #     headers = {
     #         **request.headers,
-    #         "foo": "bar" # set "foo" header
-    #         "origin": None # remove "origin" header
+    #         "foo": "foo-value", # set "foo" header
+    #         "bar": None # remove "bar" header
     #     }
-    #     await route.continue(headers=headers)
-    # }
-    # await page.route("**/*", handle)
+    #     route.continue_(headers=headers)
+    #
+    # page.route("**/*", 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.
+    #
+    # [`method: Route.continue`] will immediately send the request to the network, other matching handlers won't be invoked. Use [`method: 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 [`method: BrowserContext.addCookies`].
+    def continue(headers: nil, method: nil, postData: nil, url: nil)
+      wrap_impl(@impl.continue(headers: unwrap_impl(headers), method: unwrap_impl(method), postData: unwrap_impl(postData), url: unwrap_impl(url)))
+    end
+
+    #
+    # Continues route's request with optional overrides. The method is similar to [`method: 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.
+    #
+    # ```python sync
+    # page.route("**/*", lambda route: route.abort())  # Runs last.
+    # page.route("**/*", lambda route: route.fallback())  # Runs second.
+    # page.route("**/*", lambda 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.
+    #
+    # ```python sync
+    # # Handle GET requests.
+    # def handle_get(route):
+    #     if route.request.method != "GET":
+    #         route.fallback()
+    #         return
+    #   # Handling GET only.
+    #   # ...
+    #
+    # # Handle POST requests.
+    # def handle_post(route):
+    #     if route.request.method != "POST":
+    #         route.fallback()
+    #         return
+    #   # Handling POST only.
+    #   # ...
+    #
+    # 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.
+    #
     # ```python sync
     # def handle(route, request):
     #     # override headers
     #     headers = {
     #         **request.headers,
-    #         "foo": "bar" # set "foo" header
-    #         "origin": None # remove "origin" header
+    #         "foo": "foo-value", # set "foo" header
+    #         "bar": None # remove "bar" header
     #     }
-    #     route.continue(headers=headers)
-    # }
+    #     route.fallback(headers=headers)
+    #
     # page.route("**/*", handle)
     # ```
-    def continue_(headers: nil, method: nil, postData: nil, url: nil)
-      raise NotImplementedError.new('continue_ is not implemented yet.')
+    #
+    # Use [`method: Route.continue`] to immediately send the request to the network, other matching handlers won't be invoked in that case.
+    def fallback(headers: nil, method: nil, postData: nil, url: nil)
+      wrap_impl(@impl.fallback(headers: unwrap_impl(headers), method: unwrap_impl(method), postData: unwrap_impl(postData), url: unwrap_impl(url)))
+    end
+
+    #
+    # Performs the request and fetches result without fulfilling it, so that the response
+    # could be modified and then fulfilled.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # def handle(route):
+    #     response = route.fetch()
+    #     json = response.json()
+    #     json["message"]["big_red_dog"] = []
+    #     route.fulfill(response=response, json=json)
+    #
+    # page.route("https://dog.ceo/api/breeds/list/all", 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 [`method: Route.continue`] instead.
+    def fetch(
+          headers: nil,
+          maxRedirects: nil,
+          maxRetries: nil,
+          method: nil,
+          postData: nil,
+          timeout: nil,
+          url: nil)
+      wrap_impl(@impl.fetch(headers: unwrap_impl(headers), maxRedirects: unwrap_impl(maxRedirects), maxRetries: unwrap_impl(maxRetries), method: unwrap_impl(method), postData: unwrap_impl(postData), timeout: unwrap_impl(timeout), url: unwrap_impl(url)))
     end
 
+    #
     # Fulfills route's request with given response.
-    # 
+    #
+    # **Usage**
+    #
     # An example of fulfilling all requests with 404 responses:
-    # 
-    #
-    # ```js
-    # await page.route('**/*', route => {
-    #   route.fulfill({
-    #     status: 404,
-    #     contentType: 'text/plain',
-    #     body: 'Not Found!'
-    #   });
-    # });
-    # ```
-    # 
-    # ```python async
-    # await page.route("**/*", lambda route: route.fulfill(
-    #     status=404,
-    #     content_type="text/plain",
-    #     body="not found!"))
-    # ```
-    # 
+    #
     # ```python sync
     # page.route("**/*", lambda route: route.fulfill(
     #     status=404,
     #     content_type="text/plain",
     #     body="not found!"))
     # ```
-    # 
+    #
     # An example of serving static file:
-    # 
     #
-    # ```js
-    # await page.route('**/xhr_endpoint', route => route.fulfill({ path: 'mock_data.json' }));
-    # ```
-    # 
-    # ```python async
-    # await page.route("**/xhr_endpoint", lambda route: route.fulfill(path="mock_data.json"))
-    # ```
-    # 
     # ```python sync
     # page.route("**/xhr_endpoint", lambda route: route.fulfill(path="mock_data.json"))
     # ```
@@ -99,14 +159,44 @@ module Playwright
           body: nil,
           contentType: nil,
           headers: nil,
+          json: nil,
           path: nil,
+          response: nil,
           status: nil)
-      raise NotImplementedError.new('fulfill is not implemented yet.')
+      wrap_impl(@impl.fulfill(body: unwrap_impl(body), contentType: unwrap_impl(contentType), headers: unwrap_impl(headers), json: unwrap_impl(json), path: unwrap_impl(path), response: unwrap_impl(response), status: unwrap_impl(status)))
     end
 
+    #
     # A request to be routed.
     def request
-      raise NotImplementedError.new('request is not implemented yet.')
+      wrap_impl(@impl.request)
+    end
+
+    # @nodoc
+    def redirect_navigation_request(url)
+      wrap_impl(@impl.redirect_navigation_request(unwrap_impl(url)))
+    end
+
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def once(event, callback)
+      event_emitter_proxy.once(event, callback)
+    end
+
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def on(event, callback)
+      event_emitter_proxy.on(event, callback)
+    end
+
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def off(event, callback)
+      event_emitter_proxy.off(event, callback)
+    end
+
+    private def event_emitter_proxy
+      @event_emitter_proxy ||= EventEmitterProxy.new(self, @impl)
     end
   end
 end

data/lib/playwright_api/selectors.rb

@@ -1,73 +1,59 @@
 module Playwright
-  # Selectors can be used to install custom selector engines. See
-  # [Working with selectors](./selectors.md#working-with-selectors) for more information.
+  #
+  # Selectors can be used to install custom selector engines. See [extensibility](../extensibility.md) for more
+  # information.
   class Selectors < PlaywrightApi
 
+    #
+    # Selectors must be registered before creating the page.
+    #
+    # **Usage**
+    #
     # An example of registering selector engine that queries elements based on a tag name:
-    # 
     #
-    # ```js
-    # const { selectors, firefox } = require('playwright');  // Or 'chromium' or 'webkit'.
-    # 
-    # (async () => {
-    #   // Must be a function that evaluates to a selector engine instance.
-    #   const createTagNameEngine = () => ({
-    #     // 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));
-    #     }
-    #   });
-    # 
-    #   // Register the engine. Selectors will be prefixed with "tag=".
-    #   await selectors.register('tag', createTagNameEngine);
-    # 
-    #   const browser = await firefox.launch();
-    #   const page = await browser.newPage();
-    #   await page.setContent(`<div><button>Click me</button></div>`);
-    # 
-    #   // Use the selector prefixed with its name.
-    #   const button = await page.$('tag=button');
-    #   // Combine it with other selector engines.
-    #   await page.click('tag=div >> text="Click me"');
-    #   // Can use it in any methods supporting selectors.
-    #   const buttonCount = await page.$$eval('tag=button', buttons => buttons.length);
-    # 
-    #   await browser.close();
-    # })();
-    # ```
-    # 
-    # ```python async
-    # # FIXME: add snippet
-    # ```
-    # 
     # ```python sync
-    # # FIXME: add snippet
+    # from playwright.sync_api import sync_playwright, Playwright
+    #
+    # def run(playwright: Playwright):
+    #     tag_selector = """
+    #       {
+    #           // 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));
+    #           }
+    #       }"""
+    #
+    #     # Register the engine. Selectors will be prefixed with "tag=".
+    #     playwright.selectors.register("tag", tag_selector)
+    #     browser = playwright.chromium.launch()
+    #     page = browser.new_page()
+    #     page.set_content('<div><button>Click me</button></div>')
+    #
+    #     # Use the selector prefixed with its name.
+    #     button = page.locator('tag=button')
+    #     # Combine it with built-in locators.
+    #     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()
+    #     print(button_count)
+    #     browser.close()
+    #
+    # with sync_playwright() as playwright:
+    #     run(playwright)
     # ```
-    def register(name, script, contentScript: nil)
-      raise NotImplementedError.new('register is not implemented yet.')
-    end
-
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def on(event, callback)
-      wrap_impl(@impl.on(unwrap_impl(event), unwrap_impl(callback)))
+    def register(name, script: nil, contentScript: nil, path: nil)
+      wrap_impl(@impl.register(unwrap_impl(name), script: unwrap_impl(script), contentScript: unwrap_impl(contentScript), path: unwrap_impl(path)))
     end
 
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def off(event, callback)
-      wrap_impl(@impl.off(unwrap_impl(event), unwrap_impl(callback)))
-    end
-
-    # -- inherited from EventEmitter --
-    # @nodoc
-    def once(event, callback)
-      wrap_impl(@impl.once(unwrap_impl(event), unwrap_impl(callback)))
+    #
+    # Defines custom attribute name to be used in [`method: Page.getByTestId`]. `data-testid` is used by default.
+    def set_test_id_attribute(attributeName)
+      wrap_impl(@impl.set_test_id_attribute(unwrap_impl(attributeName)))
     end
+    alias_method :test_id_attribute=, :set_test_id_attribute
   end
 end

data/lib/playwright_api/touchscreen.rb

@@ -1,11 +1,17 @@
 module Playwright
+  #
   # 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 intialized with `hasTouch` set to true.
+  # 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](../touch-events.md) page.
   class Touchscreen < PlaywrightApi
 
+    #
     # Dispatches a `touchstart` and `touchend` event with a single touch at the position (`x`,`y`).
+    #
+    # **NOTE**: [`method: Page.tap`] the method will throw if `hasTouch` option of the browser context is false.
     def tap_point(x, y)
-      raise NotImplementedError.new('tap_point is not implemented yet.')
+      wrap_impl(@impl.tap_point(unwrap_impl(x), unwrap_impl(y)))
     end
   end
 end