playwright-ruby-client 0.0.3 → 0.0.8

data/lib/playwright_api/playwright.rb

@@ -1,35 +1,196 @@
 module Playwright
-  # @nodoc
+  # Playwright module provides a method to launch a browser instance. The following is a typical example of using Playwright
+  # to drive automation:
+  # 
+  #
+  # ```js
+  # const { chromium, firefox, webkit } = require('playwright');
+  # 
+  # (async () => {
+  #   const browser = await chromium.launch();  // Or 'firefox' or 'webkit'.
+  #   const page = await browser.newPage();
+  #   await page.goto('http://example.com');
+  #   // other actions...
+  #   await browser.close();
+  # })();
+  # ```
+  # 
+  # ```python async
+  # import asyncio
+  # from playwright.async_api import async_playwright
+  # 
+  # async def run(playwright):
+  #     chromium = playwright.chromium # or "firefox" or "webkit".
+  #     browser = await chromium.launch()
+  #     page = await browser.new_page()
+  #     await page.goto("http://example.com")
+  #     # other actions...
+  #     await browser.close()
+  # 
+  # async def main():
+  #     async with async_playwright() as playwright:
+  #         await run(playwright)
+  # asyncio.run(main())
+  # ```
+  # 
+  # ```python sync
+  # from playwright.sync_api import sync_playwright
+  # 
+  # def run(playwright):
+  #     chromium = playwright.chromium # or "firefox" or "webkit".
+  #     browser = chromium.launch()
+  #     page = browser.new_page()
+  #     page.goto("http://example.com")
+  #     # other actions...
+  #     browser.close()
+  # 
+  # with sync_playwright() as playwright:
+  #     run(playwright)
+  # ```
   class Playwright < PlaywrightApi
 
-    # @nodoc
-    def android
-      wrap_channel_owner(@channel_owner.android)
+    # This object can be used to launch or connect to Chromium, returning instances of `ChromiumBrowser`.
+    def chromium # property
+      wrap_impl(@impl.chromium)
+    end
+
+    # Returns a dictionary of devices to be used with [`method: Browser.newContext`] or [`method: Browser.newPage`].
+    # 
+    #
+    # ```js
+    # const { webkit, devices } = require('playwright');
+    # const iPhone = devices['iPhone 6'];
+    # 
+    # (async () => {
+    #   const browser = await webkit.launch();
+    #   const context = await browser.newContext({
+    #     ...iPhone
+    #   });
+    #   const page = await context.newPage();
+    #   await page.goto('http://example.com');
+    #   // other actions...
+    #   await browser.close();
+    # })();
+    # ```
+    # 
+    # ```python async
+    # import asyncio
+    # from playwright.async_api import async_playwright
+    # 
+    # async def run(playwright):
+    #     webkit = playwright.webkit
+    #     iphone = playwright.devices["iPhone 6"]
+    #     browser = await webkit.launch()
+    #     context = await browser.new_context(**iphone)
+    #     page = await context.new_page()
+    #     await page.goto("http://example.com")
+    #     # other actions...
+    #     await browser.close()
+    # 
+    # async def main():
+    #     async with async_playwright() as playwright:
+    #         await run(playwright)
+    # asyncio.run(main())
+    # ```
+    # 
+    # ```python sync
+    # from playwright.sync_api import sync_playwright
+    # 
+    # def run(playwright):
+    #     webkit = playwright.webkit
+    #     iphone = playwright.devices["iPhone 6"]
+    #     browser = webkit.launch()
+    #     context = browser.new_context(**iphone)
+    #     page = context.new_page()
+    #     page.goto("http://example.com")
+    #     # other actions...
+    #     browser.close()
+    # 
+    # with sync_playwright() as playwright:
+    #     run(playwright)
+    # ```
+    def devices # property
+      wrap_impl(@impl.devices)
+    end
+
+    # Playwright methods might throw errors if they are unable to fulfill a request. For example,
+    # [`method: Page.waitForSelector`] might fail if the selector doesn't match any nodes during the given timeframe.
+    # 
+    # For certain types of errors Playwright uses specific error classes. These classes are available via
+    # [`playwright.errors`](#playwrighterrors).
+    # 
+    # An example of handling a timeout error:
+    # 
+    #
+    # ```js
+    # try {
+    #   await page.waitForSelector('.foo');
+    # } catch (e) {
+    #   if (e instanceof playwright.errors.TimeoutError) {
+    #     // Do something if this is a timeout.
+    #   }
+    # }
+    # ```
+    # 
+    # ```python async
+    # try:
+    #     await page.wait_for_selector(".foo")
+    # except TimeoutError as e:
+    #     # do something if this is a timeout.
+    # ```
+    # 
+    # ```python sync
+    # try:
+    #     page.wait_for_selector(".foo")
+    # except TimeoutError as e:
+    #     # do something if this is a timeout.
+    # ```
+    def errors # property
+      raise NotImplementedError.new('errors is not implemented yet.')
+    end
+
+    # This object can be used to launch or connect to Firefox, returning instances of `FirefoxBrowser`.
+    def firefox # property
+      wrap_impl(@impl.firefox)
+    end
+
+    # Selectors can be used to install custom selector engines. See
+    # [Working with selectors](./selectors.md#working-with-selectors) for more information.
+    def selectors # property
+      raise NotImplementedError.new('selectors is not implemented yet.')
+    end
+
+    # This object can be used to launch or connect to WebKit, returning instances of `WebKitBrowser`.
+    def webkit # property
+      wrap_impl(@impl.webkit)
     end
 
     # @nodoc
-    def chromium
-      wrap_channel_owner(@channel_owner.chromium)
+    def android
+      wrap_impl(@impl.android)
     end
 
     # @nodoc
     def electron
-      wrap_channel_owner(@channel_owner.electron)
+      wrap_impl(@impl.electron)
     end
 
+    # -- inherited from EventEmitter --
     # @nodoc
-    def firefox
-      wrap_channel_owner(@channel_owner.firefox)
+    def on(event, callback)
+      wrap_impl(@impl.on(unwrap_impl(event), unwrap_impl(callback)))
     end
 
+    # -- inherited from EventEmitter --
     # @nodoc
-    def devices
-      wrap_channel_owner(@channel_owner.devices)
+    def off(event, callback)
+      wrap_impl(@impl.off(unwrap_impl(event), unwrap_impl(callback)))
     end
 
+    # -- inherited from EventEmitter --
     # @nodoc
-    def webkit
-      wrap_channel_owner(@channel_owner.webkit)
+    def once(event, callback)
+      wrap_impl(@impl.once(unwrap_impl(event), unwrap_impl(callback)))
     end
   end
 end

data/lib/playwright_api/request.rb

@@ -1,119 +1,204 @@
 module Playwright
-  # Whenever the page sends a request for a network resource the following sequence of events are emitted by Page:
+  # Whenever the page sends a request for a network resource the following sequence of events are emitted by `Page`:
+  # - [`event: Page.request`] emitted when the request is issued by the page.
+  # - [`event: Page.response`] emitted when/if the response status and headers are received for the request.
+  # - [`event: Page.requestfinished`] emitted when the response body is downloaded and the request is complete.
   # 
-  # page.on('request') emitted when the request is issued by the page.
-  # page.on('response') emitted when/if the response status and headers are received for the request.
-  # page.on('requestfinished') emitted when the response body is downloaded and the request is complete.
+  # If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event),
+  # the  [`event: Page.requestfailed`] event is emitted.
   # 
-  # If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event), the  page.on('requestfailed') event is emitted.
+  # > NOTE: HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will
+  # complete with `'requestfinished'` event.
   # 
-  # **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will 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.
+  # 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.
   class Request < PlaywrightApi
 
     # The method returns `null` unless this request has failed, as reported by `requestfailed` event.
+    # 
     # Example of logging of all the failed requests:
+    # 
     #
     # ```js
     # page.on('requestfailed', request => {
     #   console.log(request.url() + ' ' + request.failure().errorText);
     # });
     # ```
+    # 
+    # ```py
+    # page.on("requestfailed", lambda request: print(request.url + " " + request.failure))
+    # ```
     def failure
-      raise NotImplementedError.new('failure is not implemented yet.')
+      wrap_impl(@impl.failure)
     end
 
-    # Returns the Frame that initiated this request.
+    # Returns the `Frame` that initiated this request.
     def frame
-      raise NotImplementedError.new('frame is not implemented yet.')
+      wrap_impl(@impl.frame)
     end
 
     # An object with HTTP headers associated with the request. All header names are lower-case.
     def headers
-      raise NotImplementedError.new('headers is not implemented yet.')
+      wrap_impl(@impl.headers)
     end
 
     # Whether this request is driving frame's navigation.
     def navigation_request?
-      raise NotImplementedError.new('navigation_request? is not implemented yet.')
+      wrap_impl(@impl.navigation_request?)
     end
 
     # Request's method (GET, POST, etc.)
     def method
-      wrap_channel_owner(@channel_owner.method)
+      wrap_impl(@impl.method)
     end
 
     # Request's post body, if any.
     def post_data
-      raise NotImplementedError.new('post_data is not implemented yet.')
+      wrap_impl(@impl.post_data)
     end
 
     # Request's post body in a binary form, if any.
     def post_data_buffer
-      raise NotImplementedError.new('post_data_buffer is not implemented yet.')
+      wrap_impl(@impl.post_data_buffer)
     end
 
     # Returns parsed request's body for `form-urlencoded` and JSON as a fallback if any.
-    # When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned. Otherwise it will be parsed as JSON.
+    # 
+    # When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned.
+    # Otherwise it will be parsed as JSON.
     def post_data_json
-      raise NotImplementedError.new('post_data_json is not implemented yet.')
+      wrap_impl(@impl.post_data_json)
     end
 
     # Request that was redirected by the server to this one, if any.
-    # When the server responds with a redirect, Playwright creates a new Request object. The two requests are connected by `redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
+    # 
+    # When the server responds with a redirect, Playwright creates a new `Request` object. The two requests are connected by
+    # `redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to
+    # construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
+    # 
     # For example, if the website `http://example.com` redirects to `https://example.com`:
+    # 
     #
     # ```js
     # const response = await page.goto('http://example.com');
     # console.log(response.request().redirectedFrom().url()); // 'http://example.com'
     # ```
+    # 
+    # ```python async
+    # response = await page.goto("http://example.com")
+    # print(response.request.redirected_from.url) # "http://example.com"
+    # ```
+    # 
+    # ```python sync
+    # response = page.goto("http://example.com")
+    # print(response.request.redirected_from.url) # "http://example.com"
+    # ```
+    # 
     # If the website `https://google.com` has no redirects:
+    # 
     #
     # ```js
     # const response = await page.goto('https://google.com');
     # console.log(response.request().redirectedFrom()); // null
     # ```
+    # 
+    # ```python async
+    # response = await page.goto("https://google.com")
+    # print(response.request.redirected_from) # None
+    # ```
+    # 
+    # ```python sync
+    # response = page.goto("https://google.com")
+    # print(response.request.redirected_from) # None
+    # ```
     def redirected_from
-      raise NotImplementedError.new('redirected_from is not implemented yet.')
+      wrap_impl(@impl.redirected_from)
     end
 
     # New request issued by the browser if the server responded with redirect.
-    # This method is the opposite of `request.redirectedFrom()`:
+    # 
+    # This method is the opposite of [`method: Request.redirectedFrom`]:
+    # 
     #
     # ```js
     # console.log(request.redirectedFrom().redirectedTo() === request); // true
     # ```
+    # 
+    # ```py
+    # assert request.redirected_from.redirected_to == request
+    # ```
     def redirected_to
-      raise NotImplementedError.new('redirected_to is not implemented yet.')
+      wrap_impl(@impl.redirected_to)
     end
 
-    # Contains the request's resource type as it was perceived by the rendering engine. ResourceType will be one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`.
+    # Contains the request's resource type as it was perceived by the rendering engine. ResourceType will be one of the
+    # following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`,
+    # `websocket`, `manifest`, `other`.
     def resource_type
-      raise NotImplementedError.new('resource_type is not implemented yet.')
+      wrap_impl(@impl.resource_type)
     end
 
-    # Returns the matching Response object, or `null` if the response was not received due to error.
+    # Returns the matching `Response` object, or `null` if the response was not received due to error.
     def response
-      raise NotImplementedError.new('response is not implemented yet.')
+      wrap_impl(@impl.response)
     end
 
-    # Returns resource timing information for given request. Most of the timing values become available upon the response, `responseEnd` becomes available when request finishes. Find more information at Resource Timing API.
+    # Returns resource timing information for given request. Most of the timing values become available upon the response,
+    # `responseEnd` becomes available when request finishes. Find more information at
+    # [Resource Timing API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).
+    # 
     #
     # ```js
     # const [request] = await Promise.all([
     #   page.waitForEvent('requestfinished'),
-    #   page.goto(httpsServer.EMPTY_PAGE)
+    #   page.goto('http://example.com')
     # ]);
     # console.log(request.timing());
     # ```
+    # 
+    # ```python async
+    # async with page.expect_event("requestfinished") as request_info:
+    #     await page.goto("http://example.com")
+    # request = await request_info.value
+    # print(request.timing)
+    # ```
+    # 
+    # ```python sync
+    # with page.expect_event("requestfinished") as request_info:
+    #     page.goto("http://example.com")
+    # request = request_info.value
+    # print(request.timing)
+    # ```
     def timing
-      raise NotImplementedError.new('timing is not implemented yet.')
+      wrap_impl(@impl.timing)
     end
 
     # URL of the request.
     def url
-      raise NotImplementedError.new('url is not implemented yet.')
+      wrap_impl(@impl.url)
+    end
+
+    # @nodoc
+    def after_initialize
+      wrap_impl(@impl.after_initialize)
+    end
+
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def on(event, callback)
+      wrap_impl(@impl.on(unwrap_impl(event), unwrap_impl(callback)))
+    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)))
     end
   end
 end

data/lib/playwright_api/response.rb

@@ -1,5 +1,5 @@
 module Playwright
-  # Response class represents responses which are received by page.
+  # `Response` class represents responses which are received by page.
   class Response < PlaywrightApi
 
     # Returns the buffer with response body.
@@ -12,7 +12,7 @@ module Playwright
       raise NotImplementedError.new('finished is not implemented yet.')
     end
 
-    # Returns the Frame that initiated this response.
+    # Returns the `Frame` that initiated this response.
     def frame
       raise NotImplementedError.new('frame is not implemented yet.')
     end
@@ -23,6 +23,7 @@ module Playwright
     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.')
@@ -33,7 +34,7 @@ module Playwright
       raise NotImplementedError.new('ok is not implemented yet.')
     end
 
-    # Returns the matching Request object.
+    # Returns the matching `Request` object.
     def request
       raise NotImplementedError.new('request is not implemented yet.')
     end
@@ -57,5 +58,23 @@ module Playwright
     def url
       raise NotImplementedError.new('url is not implemented yet.')
     end
+
+    # -- inherited from EventEmitter --
+    # @nodoc
+    def on(event, callback)
+      wrap_impl(@impl.on(unwrap_impl(event), unwrap_impl(callback)))
+    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)))
+    end
   end
 end