playwright-ruby-client 0.0.8 → 1.58.1.alpha1

data/lib/playwright_api/dialog.rb

@@ -1,90 +1,93 @@
 module Playwright
+  #
   # `Dialog` objects are dispatched by page via the [`event: Page.dialog`] event.
-  # 
+  #
   # An example of using `Dialog` class:
-  # 
   #
-  # ```js
-  # const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
-  # 
-  # (async () => {
-  #   const browser = await chromium.launch();
-  #   const page = await browser.newPage();
-  #   page.on('dialog', async dialog => {
-  #     console.log(dialog.message());
-  #     await dialog.dismiss();
-  #     await browser.close();
-  #   });
-  #   page.evaluate(() => alert('1'));
-  # })();
-  # ```
-  # 
-  # ```python async
-  # import asyncio
-  # from playwright.async_api import async_playwright
-  # 
-  # async def handle_dialog(dialog):
-  #     print(dialog.message)
-  #     await dialog.dismiss()
-  # 
-  # async def run(playwright):
-  #     chromium = playwright.chromium
-  #     browser = await chromium.launch()
-  #     page = await browser.new_page()
-  #     page.on("dialog", handle_dialog)
-  #     page.evaluate("alert('1')")
-  #     await browser.close()
-  # 
-  # async def main():
-  #     async with async_playwright() as playwright:
-  #         await run(playwright)
-  # asyncio.run(main())
-  # ```
-  # 
   # ```python sync
-  # # FIXME
-  # from playwright.sync_api import sync_playwright
-  # 
+  # from playwright.sync_api import sync_playwright, Playwright
+  #
   # def handle_dialog(dialog):
   #     print(dialog.message)
   #     dialog.dismiss()
-  # 
-  # def run(playwright):
+  #
+  # def run(playwright: Playwright):
   #     chromium = playwright.chromium
   #     browser = chromium.launch()
   #     page = browser.new_page()
   #     page.on("dialog", handle_dialog)
   #     page.evaluate("alert('1')")
   #     browser.close()
-  # 
+  #
   # with sync_playwright() as playwright:
   #     run(playwright)
   # ```
+  #
+  # **NOTE**: Dialogs are dismissed automatically, unless there is a [`event: Page.dialog`] listener.
+  # When listener is present, it **must** either [`method: Dialog.accept`] or [`method: Dialog.dismiss`] the dialog - otherwise the page will [freeze](https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop#never_blocking) waiting for the dialog, and actions like click will never finish.
   class Dialog < PlaywrightApi
 
+    #
     # Returns when the dialog has been accepted.
     def accept(promptText: nil)
-      raise NotImplementedError.new('accept is not implemented yet.')
+      wrap_impl(@impl.accept(promptText: unwrap_impl(promptText)))
     end
 
+    #
     # If dialog is prompt, returns default prompt value. Otherwise, returns empty string.
     def default_value
-      raise NotImplementedError.new('default_value is not implemented yet.')
+      wrap_impl(@impl.default_value)
     end
 
+    #
     # Returns when the dialog has been dismissed.
     def dismiss
-      raise NotImplementedError.new('dismiss is not implemented yet.')
+      wrap_impl(@impl.dismiss)
     end
 
+    #
     # A message displayed in the dialog.
     def message
-      raise NotImplementedError.new('message is not implemented yet.')
+      wrap_impl(@impl.message)
     end
 
+    #
+    # The page that initiated this dialog, if available.
+    def page
+      wrap_impl(@impl.page)
+    end
+
+    #
     # Returns dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`.
     def type
-      raise NotImplementedError.new('type is not implemented yet.')
+      wrap_impl(@impl.type)
+    end
+
+    # @nodoc
+    def accept_async(promptText: nil)
+      wrap_impl(@impl.accept_async(promptText: unwrap_impl(promptText)))
+    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/download.rb

@@ -1,78 +1,84 @@
 module Playwright
+  #
   # `Download` objects are dispatched by page via the [`event: Page.download`] event.
-  # 
-  # All the downloaded files belonging to the browser context are deleted when the browser context is closed. All downloaded
-  # files are deleted when the browser closes.
-  # 
-  # Download event is emitted once the download starts. Download path becomes available once download completes:
-  # 
   #
-  # ```js
-  # const [ download ] = await Promise.all([
-  #   page.waitForEvent('download'), // wait for download to start
-  #   page.click('a')
-  # ]);
-  # // wait for download to complete
-  # const path = await download.path();
-  # ```
-  # 
-  # ```python async
-  # async with page.expect_download() as download_info:
-  #     await page.click("a")
-  # download = await download_info.value
-  # # waits for download to complete
-  # path = await download.path()
-  # ```
-  # 
+  # All the downloaded files belonging to the browser context are deleted when the
+  # browser context is closed.
+  #
+  # Download event is emitted once the download starts. Download path becomes available once download completes.
+  #
   # ```python sync
+  # # Start waiting for the download
   # with page.expect_download() as download_info:
-  #     page.click("a")
+  #     # Perform the action that initiates download
+  #     page.get_by_text("Download file").click()
   # download = download_info.value
-  # # wait for download to complete
-  # path = download.path()
+  #
+  # # Wait for the download process to complete and save the downloaded file somewhere
+  # download.save_as("/path/to/save/at/" + download.suggested_filename)
   # ```
-  # 
-  # > NOTE: Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the
-  # downloaded content. If `acceptDownloads` is not set, download events are emitted, but the actual download is not
-  # performed and user has no access to the downloaded files.
   class Download < PlaywrightApi
 
-    # Returns readable stream for current download or `null` if download failed.
-    def create_read_stream
-      raise NotImplementedError.new('create_read_stream is not implemented yet.')
+    #
+    # Cancels a download. Will not fail if the download is already finished or canceled.
+    # Upon successful cancellations, `download.failure()` would resolve to `'canceled'`.
+    def cancel
+      wrap_impl(@impl.cancel)
     end
 
-    # Deletes the downloaded file.
+    #
+    # Deletes the downloaded file. Will wait for the download to finish if necessary.
     def delete
-      raise NotImplementedError.new('delete is not implemented yet.')
+      wrap_impl(@impl.delete)
     end
 
-    # Returns download error if any.
+    #
+    # Returns download error if any. Will wait for the download to finish if necessary.
     def failure
-      raise NotImplementedError.new('failure is not implemented yet.')
+      wrap_impl(@impl.failure)
+    end
+
+    #
+    # Get the page that the download belongs to.
+    def page
+      wrap_impl(@impl.page)
     end
 
-    # Returns path to the downloaded file in case of successful download.
+    #
+    # Returns path to the downloaded file for a successful download, or throws for a failed/canceled download. The method will wait for the download to finish if necessary. The method throws when connected remotely.
+    #
+    # Note that the download's file name is a random GUID, use [`method: Download.suggestedFilename`]
+    # to get suggested file name.
     def path
-      raise NotImplementedError.new('path is not implemented yet.')
+      wrap_impl(@impl.path)
     end
 
-    # Saves the download to a user-specified path.
+    #
+    # Copy the download to a user-specified path. It is safe to call this method while the download
+    # is still in progress. Will wait for the download to finish if necessary.
+    #
+    # **Usage**
+    #
+    # ```python sync
+    # download.save_as("/path/to/save/at/" + download.suggested_filename)
+    # ```
     def save_as(path)
-      raise NotImplementedError.new('save_as is not implemented yet.')
+      wrap_impl(@impl.save_as(unwrap_impl(path)))
     end
 
+    #
     # Returns suggested filename for this download. It is typically computed by the browser from the
     # [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) response header
     # or the `download` attribute. See the spec on [whatwg](https://html.spec.whatwg.org/#downloading-resources). Different
     # browsers can use different logic for computing it.
     def suggested_filename
-      raise NotImplementedError.new('suggested_filename is not implemented yet.')
+      wrap_impl(@impl.suggested_filename)
     end
 
+    #
     # Returns downloaded url.
     def url
-      raise NotImplementedError.new('url is not implemented yet.')
+      wrap_impl(@impl.url)
     end
   end
 end