playwright-ruby-client 0.6.6 → 0.8.1

data/documentation/docs/api/response.md

@@ -64,6 +64,22 @@ def request
 
 Returns the matching [Request](./request) object.
 
+## security_details
+
+```
+def security_details
+```
+
+Returns SSL and other security information.
+
+## server_addr
+
+```
+def server_addr
+```
+
+Returns the IP address and port of the server.
+
 ## status
 
 ```

data/documentation/docs/api/web_socket.md

@@ -5,3 +5,40 @@ sidebar_position: 10
 # WebSocket
 
 The [WebSocket](./web_socket) class represents websocket connections in the page.
+
+## 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/article/guides/launch_browser.md

@@ -117,3 +117,5 @@ Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwrig
   end
 end
 ```
+
+Note that each browser context is isolated and not persisted by default. When persistent browser context is needed, we can use [BrowserType#launch_persistent_context](/docs/api/browser_type#launch_persistent_context).

data/documentation/docs/article/guides/playwright_on_alpine_linux.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 6
+---
+
+# Playwright on Alpine Linux
+
+**NOTE: This feature is EXPERIMENTAL.**
+
+Playwright actually requires a permission for shell command execution, and many run-time dependencies for each browser.
+
+![all-in-one](https://user-images.githubusercontent.com/11763113/124934388-9c9c9100-e03f-11eb-8f13-324afac3be2a.png)
+
+This all-in-one architecture is reasonable for browser automation in our own computers.
+
+However we may have trouble with bringing Playwright into:
+
+* Docker
+  * Alpine Linux
+* Serverless computing
+  * AWS Lambda
+  * Google Cloud Functions
+* PaaS
+  * Heroku
+  * Google App Engine
+
+This article introduces a way to separate environments into client (for executing Playwright script) and server (for working with browsers). The main use-case assumes Docker (using Alpine Linux), however the way can be applied also into other use-cases.
+
+## Overview
+
+Playwrignt Ruby client is running on Alpine Linux. It just sends/receives JSON messages of Playwright-protocol via WebSocket.
+
+Playwright server is running on a container of [official Docker image](https://hub.docker.com/_/microsoft-playwright). It just operates browsers in response to the JSON messages from WebSocket.
+
+![overview](https://user-images.githubusercontent.com/11763113/124934448-ad4d0700-e03f-11eb-942e-b9f3282bb703.png)
+
+## Playwright client
+
+Many example uses `Playwright#create`, which internally uses Pipe (stdin/stdout) transport for Playwright-protocol messaging. Instead, **just use `Playwright#connect_to_playwright_server(endpoint)`** for WebSocket transport.
+
+```ruby {3}
+require 'playwright'
+
+Playwright.connect_to_playwright_server('wss://example.com:8888/ws') do |playwright|
+  playwright.chromium.launch do |browser|
+    page = browser.new_page
+    page.goto('https://github.com/microsoft/playwright')
+    page.screenshot(path: 'github-microsoft-playwright.png')
+  end
+end
+```
+
+`wss://example.com:8888/ws` is an example of endpoint URL of the Playwright server. In local development environment, it is typically `"ws://127.0.0.1:#{port}/ws"`.
+
+## Playwright server
+
+With the [official Docker image](https://hub.docker.com/_/microsoft-playwright) or in the local development environment with Node.js, just execute `npx playwright install && npx playwright run-server $PORT`. (`$PORT` is a port number of the server)
+
+If custom Docker image is preferred, build it as follows:
+
+```Dockerfile
+FROM mcr.microsoft.com/playwright:focal
+
+WORKDIR /root
+RUN npm install playwright@1.12.3 && ./node_modules/.bin/playwright install
+
+ENV PORT 8888
+CMD ["./node_modules/.bin/playwright", "run-server", "$PORT"]
+```
+
+## Debugging for connection
+
+The client and server are really quiet. This chapter shows how to check if the communication on the WebSocket works well or not.
+
+### Show JSON message on client
+
+Just set an environment variable `DEBUG=1`.
+
+```
+DEBUG=1 bundle exec ruby some-automation-with-playwright.rb
+```
+
+
+### Enable verbose logging on server
+
+Just set an environment variable `DEBUG=pw:*` or `DEBUG=pw:server`
+
+```
+DEBUG=pw:* npx playwright run-server 8888
+```
+
+See [the official documentation](https://playwright.dev/docs/debug/#verbose-api-logs) for details.

data/documentation/docs/article/guides/rails_integration.md

@@ -202,4 +202,4 @@ end
 
 * Playwright doesn't allow clicking invisible DOM elements or moving elements. `click` sometimes doesn't work as Selenium does. See the detail in https://playwright.dev/docs/actionability/
 * `current_window.maximize` and `current_window.fullscreen` work only on headful (non-headless) mode, as selenium driver does.
-* `Capybara::Node::Element#drag_to` does not accept `html5` parameter.
+* `Capybara::Node::Element#drag_to` does not accept `html5` parameter. HTML5 drag and drop is not fully supported in Playwright.

data/documentation/docs/article/guides/semi_automation.md

@@ -0,0 +1,71 @@
+---
+sidebar_position: 5
+---
+
+# Semi-automation
+
+Playwright Browser context is isolated and not persisted by default. But we can also use persistent browser context using [BrowserType#launch_persistent_context](/docs/api/browser_type#launch_persistent_context).
+This allow us to intermediate into automation, for example
+
+* Authenticate with OAuth2 manually before automation
+* Testing a page after some chrome extensions are installed manually
+
+Keep in mind repeatedly that persistent browser context is NOT RECOMMENDED for most cases because it would bring many side effects.
+
+## Pause automation for manual operation
+
+`Page#pause` is not implemented yet, however we can use `binding.pry`  (with `pry-byebug` installed) instead.
+
+```ruby {4}
+playwright.chromium.launch_persistent_context('./data/', headless: false) do |context|
+  page = context.new_page
+  page.goto('https://example.com/')
+  binding.pry
+end
+```
+
+When script is executed, it is paused as below.
+
+```
+    3:
+    4: playwright.chromium.launch_persistent_context('./data/', headless: false) do |context|
+    5:   page = context.new_page
+    6:   page.goto('https://example.com/')
+ => 7:   binding.pry
+    8: end
+
+[1] pry(main)>
+```
+
+We can inspect using `page`, `context` and also we can operate something manually during the pause.
+
+See https://github.com/deivid-rodriguez/pry-byebug for more detailed debugging options.
+
+## Working with Chrome extensions
+
+**Playwright disables the Chrome extension feature by default.**
+We have to enable it for installing Chrome extension, by passing these 3 parameters on launch.
+
+* `acceptDownloads: true`
+* `headless: false`
+* `ignoreDefaultArgs: ['--disable-extensions']`
+
+```ruby
+require 'playwright'
+require 'pry'
+
+Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+  launch_params = {
+    acceptDownloads: true,
+    channel: 'chrome',
+    headless: false,
+    ignoreDefaultArgs: ['--disable-extensions'],
+  }
+
+  playwright.chromium.launch_persistent_context('./data/', **launch_params) do |context|
+    page = context.new_page
+    page.goto('https://example.com/')
+    binding.pry
+  end
+end
+```

data/documentation/docs/include/api_coverage.md

@@ -26,6 +26,8 @@
 * json
 * ok
 * request
+* security_details
+* server_addr
 * status
 * status_text
 * text
@@ -40,10 +42,10 @@
 
 ## WebSocket
 
-* ~~closed?~~
-* ~~url~~
-* ~~expect_event~~
-* ~~wait_for_event~~
+* closed?
+* url
+* expect_event
+* wait_for_event
 
 ## Keyboard
 
@@ -91,6 +93,7 @@
 * hover
 * inner_html
 * inner_text
+* input_value
 * checked?
 * disabled?
 * editable?
@@ -134,6 +137,7 @@
 * content
 * dblclick
 * dispatch_event
+* drag_and_drop
 * eval_on_selector
 * eval_on_selector_all
 * evaluate
@@ -146,6 +150,7 @@
 * hover
 * inner_html
 * inner_text
+* input_value
 * checked?
 * detached?
 * disabled?
@@ -213,6 +218,7 @@
 * context
 * dblclick
 * dispatch_event
+* drag_and_drop
 * emulate_media
 * eval_on_selector
 * eval_on_selector_all
@@ -231,6 +237,7 @@
 * hover
 * inner_html
 * inner_text
+* input_value
 * checked?
 * closed?
 * disabled?
@@ -273,12 +280,12 @@
 * expect_navigation
 * expect_popup
 * expect_request
-* ~~expect_request_finished~~
+* expect_request_finished
 * expect_response
 * wait_for_selector
 * ~~wait_for_timeout~~
 * wait_for_url
-* ~~expect_websocket~~
+* expect_websocket
 * ~~expect_worker~~
 * ~~workers~~
 * ~~wait_for_event~~
@@ -300,7 +307,7 @@
 * expose_binding
 * expose_function
 * grant_permissions
-* ~~new_cdp_session~~
+* new_cdp_session
 * new_page
 * pages
 * route
@@ -317,17 +324,17 @@
 * ~~wait_for_event~~
 * tracing
 
-## ~~CDPSession~~
+## CDPSession
 
-* ~~detach~~
-* ~~send_message~~
+* detach
+* send_message
 
 ## Browser
 
 * close
 * contexts
 * connected?
-* ~~new_browser_cdp_session~~
+* new_browser_cdp_session
 * new_context
 * new_page
 * start_tracing

data/lib/playwright.rb

@@ -59,7 +59,8 @@ module Playwright
   # and we *must* call execution.stop on the end.
   # The instance of playwright is available by calling execution.playwright
   module_function def create(playwright_cli_executable_path:, &block)
-    connection = Connection.new(playwright_cli_executable_path: playwright_cli_executable_path)
+    transport = Transport.new(playwright_cli_executable_path: playwright_cli_executable_path)
+    connection = Connection.new(transport)
     connection.async_run
 
     execution =
@@ -82,7 +83,39 @@ module Playwright
     end
   end
 
-  module_function def instance
-    @playwright_instance
+  # Connects to Playwright server, launched by `npx playwright run-server` via WebSocket transport.
+  #
+  # Playwright.connect_to_playwright_server(...) do |playwright|
+  #   browser = playwright.chromium.launch
+  #   ...
+  # end
+  #
+  # @experimental
+  module_function def connect_to_playwright_server(ws_endpoint, &block)
+    require 'playwright/web_socket_client'
+    require 'playwright/web_socket_transport'
+
+    transport = WebSocketTransport.new(ws_endpoint: ws_endpoint)
+    connection = Connection.new(transport)
+    connection.async_run
+
+    execution =
+      begin
+        playwright = connection.wait_for_object_with_known_name('Playwright')
+        Execution.new(connection, PlaywrightApi.wrap(playwright))
+      rescue
+        connection.stop
+        raise
+      end
+
+    if block
+      begin
+        block.call(execution.playwright)
+      ensure
+        execution.stop
+      end
+    else
+      execution
+    end
   end
 end

data/lib/playwright/channel_owners/artifact.rb

@@ -26,5 +26,9 @@ module Playwright
     def delete
       @channel.send_message_to_server('delete')
     end
+
+    def cancel
+      @channel.send_message_to_server('cancel')
+    end
   end
 end

data/lib/playwright/channel_owners/browser.rb

@@ -67,6 +67,11 @@ module Playwright
       @initializer['version']
     end
 
+    def new_browser_cdp_session
+      resp = @channel.send_message_to_server('newBrowserCDPSession')
+      ChannelOwners::CDPSession.from(resp)
+    end
+
     def start_tracing(page: nil, categories: nil, path: nil, screenshots: nil)
       params = {
         page: page&.channel,

data/lib/playwright/channel_owners/browser_context.rb

@@ -8,7 +8,7 @@ module Playwright
 
     private def after_initialize
       @pages = Set.new
-      @routes = Set.new
+      @routes = []
       @bindings = {}
       @timeout_settings = TimeoutSettings.new
 
@@ -98,6 +98,11 @@ module Playwright
       page&.emit(Events::Page::Response, response)
     end
 
+    def new_cdp_session(page)
+      resp = @channel.send_message_to_server('newCDPSession', page: page.channel)
+      ChannelOwners::CDPSession.from(resp)
+    end
+
     def set_default_navigation_timeout(timeout)
       @timeout_settings.default_navigation_timeout = timeout
       @channel.send_message_to_server('setDefaultNavigationTimeoutNoReply', timeout: timeout)
@@ -205,8 +210,8 @@ module Playwright
     end
 
     def route(url, handler)
-      entry = RouteHandlerEntry.new(url, handler)
-      @routes << entry
+      entry = RouteHandlerEntry.new(url, base_url, handler)
+      @routes.unshift(entry)
       if @routes.count >= 1
         @channel.send_message_to_server('setNetworkInterceptionEnabled', enabled: true)
       end
@@ -270,5 +275,9 @@ module Playwright
     private def has_record_video_option?
       @options.key?(:recordVideo)
     end
+
+    private def base_url
+      @options[:baseURL]
+    end
   end
 end