playwright-ruby-client 1.14.beta2 → 1.15.beta2

data/documentation/docs/api/selectors.md

@@ -15,9 +15,35 @@ def register(name, contentScript: nil, path: nil, script: nil)
 
 An example of registering selector engine that queries elements based on a tag name:
 
-```python sync title=example_49f0cb9b5a21d0d5fe2b180c847bdb21068b335b4c2f42d5c05eb1957297899f.py
-# FIXME: add snippet
-
+```ruby
+tag_selector = <<~JAVASCRIPT
+{
+    // 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));
+    }
+}
+JAVASCRIPT
+
+# Register the engine. Selectors will be prefixed with "tag=".
+playwright.selectors.register("tag", script: tag_selector)
+playwright.chromium.launch do |browser|
+  page = browser.new_page()
+  page.content = '<div><button>Click me</button></div>'
+
+  # Use the selector prefixed with its name.
+  button = page.query_selector('tag=button')
+  # Combine it with other selector engines.
+  page.click('tag=div >> text="Click me"')
+
+  # Can use it in any methods supporting selectors.
+  button_count = page.eval_on_selector_all('tag=button', 'buttons => buttons.length')
+  button_count # => 1
+end
 ```
 
 

data/documentation/docs/api/tracing.md

@@ -4,18 +4,18 @@ sidebar_position: 10
 
 # Tracing
 
-API for collecting and saving Playwright traces. Playwright traces can be opened using the Playwright CLI after
-Playwright script runs.
-
-Start with specifying the folder traces will be stored in:
-
-```python sync title=example_a767dfb400d98aef50f2767b94171d23474ea1ac1cf9b4d75d412936208e652d.py
-browser = chromium.launch()
-context = browser.new_context()
-context.tracing.start(screenshots=True, snapshots=True)
-page.goto("https://playwright.dev")
-context.tracing.stop(path = "trace.zip")
-
+API for collecting and saving Playwright traces. Playwright traces can be opened in [Trace Viewer](https://playwright.dev/python/docs/trace-viewer)
+after Playwright script runs.
+
+Start recording a trace before performing actions. At the end, stop tracing and save it to a file.
+
+```ruby
+browser.new_context do |context|
+  context.tracing.start(screenshots: true, snapshots: true)
+  page = context.new_page
+  page.goto('https://playwright.dev')
+  context.tracing.stop(path: 'trace.zip')
+end
 ```
 
 
@@ -28,12 +28,39 @@ def start(name: nil, screenshots: nil, snapshots: nil)
 
 Start tracing.
 
-```python sync title=example_e611abc8b1066118d0c87eae1bbbb08df655f36d50a94402fc56b8713150997b.py
-context.tracing.start(name="trace", screenshots=True, snapshots=True)
+```ruby
+context.tracing.start(name: 'trace', screenshots: true, snapshots: true)
+page = context.new_page
+page.goto('https://playwright.dev')
+context.tracing.stop(path: 'trace.zip')
+```
+
+
+
+## start_chunk
+
+```
+def start_chunk
+```
+
+Start a new trace chunk. If you'd like to record multiple traces on the same [BrowserContext](./browser_context), use
+[Tracing#start](./tracing#start) once, and then create multiple trace chunks with [Tracing#start_chunk](./tracing#start_chunk) and
+[Tracing#stop_chunk](./tracing#stop_chunk).
+
+```ruby
+context.tracing.start(name: "trace", screenshots: true, snapshots: true)
+page = context.new_page
 page.goto("https://playwright.dev")
-context.tracing.stop()
-context.tracing.stop(path = "trace.zip")
 
+context.tracing.start_chunk
+page.click("text=Get Started")
+# Everything between start_chunk and stop_chunk will be recorded in the trace.
+context.tracing.stop_chunk(path: "trace1.zip")
+
+context.tracing.start_chunk
+page.goto("http://example.com")
+# Save a second trace file with different actions.
+context.tracing.stop_chunk(path: "trace2.zip")
 ```
 
 
@@ -45,3 +72,11 @@ def stop(path: nil)
 ```
 
 Stop tracing.
+
+## stop_chunk
+
+```
+def stop_chunk(path: nil)
+```
+
+Stop the trace chunk. See [Tracing#start_chunk](./tracing#start_chunk) for more details about multiple trace chunks.

data/documentation/docs/api/worker.md

@@ -8,17 +8,18 @@ The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/do
 event is emitted on the page object to signal a worker creation. `close` event is emitted on the worker object when the
 worker is gone.
 
-```py title=example_29716fdd4471a97923a64eebeee96330ab508226a496ae8fd13f12eb07d55ee6.py
-def handle_worker(worker):
-    print("worker created: " + worker.url)
-    worker.on("close", lambda: print("worker destroyed: " + worker.url))
-
-page.on('worker', handle_worker)
-
-print("current workers:")
-for worker in page.workers:
-    print("    " + worker.url)
-
+```ruby
+def handle_worker(worker)
+  puts "worker created: #{worker.url}"
+  worker.once("close", -> (w) { puts "worker destroyed: #{w.url}" })
+end
+
+page.on('worker', method(:handle_worker))
+
+puts "current workers:"
+page.workers.each do |worker|
+  puts "    #{worker.url}"
+end
 ```
 
 

data/documentation/docs/article/getting_started.md

@@ -4,7 +4,14 @@ sidebar_position: 0
 
 # Getting started
 
-`playwright-ruby-client` doesn't include Playwright driver nor its downloader. **We have to install Playwright in advance**
+```
+gem 'playwright-ruby-client'
+```
+
+Add the line above and then `bundle install`.
+
+
+Since `playwright-ruby-client` doesn't include Playwright driver nor its downloader, **we have to install Playwright in advance**
 
 ```shell
 $ npx playwright install
@@ -12,6 +19,8 @@ $ npx playwright install
 
 and then set `playwright_cli_executable_path: "npx playwright"` into `Playwright.create`.
 
+Other methods of installation is also available. See the detail in [Download Playwright driver](./guides/download_playwright_driver)
+
 ## Enjoy with examples
 
 ### Capture a site

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

@@ -12,6 +12,15 @@ Choose any of the three ways as you prefer to download the driver:
 * `npm install`: the best choice for most use cases, with existing Node.js environment.
 * Direct download: maybe a good choice for Docker :whale: integration.
 
+:::note
+
+Also the article [Playwright on Alpine Linux](./playwright_on_alpine_linux) would be helpful if you plan to
+
+* Build a browser server/container like Selenium Grid
+* Run automation scripts on Alpine Linux
+
+:::
+
 ## Using `npx`
 
 ```shell

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 30
 ---
 
 # Playwright inspector

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 40
 ---
 
 # Playwright on Alpine Linux
@@ -33,7 +33,23 @@ Playwright server is running on a container of [official Docker image](https://h
 
 ![overview](https://user-images.githubusercontent.com/11763113/124934448-ad4d0700-e03f-11eb-942e-b9f3282bb703.png)
 
-## Playwright client
+### Playwright Server v.s. Browser Server
+
+Playwright provides two kind of methods to share the browser environments for clients.
+
+When you want to share only one browser environment, Browser server is suitable. This feature is officially supported in Playwright.
+
+* Server can be launched with [BrowserType#launchServer](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server) instead of `BrowserType#launch`.
+* Client can connect to server with [BrowserType#connect](https://playwright.dev/docs/api/class-browsertype#browser-type-connect). In playwright-ruby-client, `BrowserType#connect` and not implemented yet and use `Playwright#connect_to_browser_server()` instead.
+
+Another method is sharing all browser environment. This method is very simple, but not an official feature, and can be changed in future.
+
+* Server can be launched with `playwright run-server` (CLI command).
+* Client can connect to server with `Playwright.connect_to_playwright_server` instead of `Playwright.create`
+
+## Playwright server/client
+
+### Client code
 
 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.
 
@@ -51,7 +67,7 @@ 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
+### Server code
 
 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)
 
@@ -67,6 +83,43 @@ ENV PORT 8888
 CMD ["./node_modules/.bin/playwright", "run-server", "$PORT"]
 ```
 
+## Browser server/client
+
+### Client code
+
+Use `Playwright#connect_to_playwright_server` and pass the WebSocket URL for browser server.
+Note that this method requires a block with `Browser`, not `Playwright` or `BrowserType`.
+
+```ruby
+Playwright.connect_to_playwright_server(ws_url) do |browser|
+  page = browser.new_page
+  page.goto(...)
+  ...
+end
+```
+
+### Server code
+
+For instant use, `npx playwright launch-server chromium` generates a WebSocket endpoint URL with a random path.
+
+More customization can be done by implementing JavaScript server like below:
+
+```js
+const playwright = require('playwright')
+
+option = {
+  channel: 'chrome-canary',
+  headless: false,
+  port: 8080,
+  wsPath: 'ws',
+}
+playwright.chromium.launchServer(option).then((server) => { console.log(server.wsEndpoint()) })
+```
+
+`port` and `wsPath` would be useful for generating static WebSocket endpoint URL.
+Other available options for `BrowserType#launchServer` can be found here:
+https://playwright.dev/docs/api/class-browsertype#browser-type-launch-server
+
 ## 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.

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

@@ -2,9 +2,11 @@
 sidebar_position: 3
 ---
 
-# Integration into Ruby on Rails application
+# Capybara driver for Ruby on Rails application
 
-`playwright-ruby-client` is a client library just for browser automation. `capybara-playwright-driver` provides the [Capybara](https://github.com/teamcapybara/capybara) driver based on playwright-ruby-client and makes it easy to integrate into Ruby on Rails applications.
+`playwright-ruby-client` is a client library just for browser automation, while Rails uses [Capybara](https://github.com/teamcapybara/capybara) for system testing.
+
+`capybara-playwright-driver` provides a [Capybara](https://github.com/teamcapybara/capybara) driver based on playwright-ruby-client and makes it easy to integrate into Ruby on Rails applications.
 
 ## Installation
 

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

@@ -0,0 +1,86 @@
+---
+sidebar_position: 4
+---
+
+# Use Capybara without DSL
+
+:::note
+
+This article shows advanced-level configuration of Capybara and RSpec for more accurate automation/testing.
+If you want to just integrate Playwright into Rails application, refer the basic [configuration guide](./rails_integration)
+:::
+
+## Background
+
+[capybara-playwright-driver](./rails_integration) is easy to configure and migrate from Selenium or another Capybara driver, however it is a little **inaccurate** and would sometimes cause 'flaky test' problem originated from the internal implementation of Capybara DSL.
+
+Also **we cannot use most of useful Playwright features in Capybara driver**, such as auto-waiting, various kind of selectors, and some users would want to use Playwright features as it is without Capybara DSL.
+
+This article shows how to use playwright-ruby-client without Capybara DSL in Rails and RSpec.
+
+## Configure Capybara driver just for launching Rails server
+
+Capybara prepares the test server only when the configured driver returns true on `needs_server?` method. So we have to implement minimum driver like this:
+
+```ruby {5-7} title=spec/support/capybara_null_driver.rb
+RSpec.configure do |config|
+  require 'capybara'
+
+  class CapybaraNullDriver < Capybara::Driver::Base
+    def needs_server?
+      true
+    end
+  end
+
+  Capybara.register_driver(:null) { CapybaraNullDriver.new }
+
+  ...
+end
+```
+
+## Launch browser on each test
+
+Now Capybara DSL is unavailable with CapybaraNullDriver, we have to manually launch browsers using playwright-ruby-client.
+
+```rb
+RSpec.configure do |config|
+  require 'capybara'
+
+  ...
+
+  require 'playwright'
+
+  config.around(driver: :null) do |example|
+    Capybara.current_driver = :null
+
+    # Rails server is launched here, at the first time of accessing Capybara.current_session.server
+    base_url = Capybara.current_session.server.base_url
+
+    Playwright.create(playwright_cli_executable_path: './node_modules/.bin/playwright') do |playwright|
+      # pass any option for Playwright#launch and Browser#new_page as you prefer.
+      playwright.chromium.launch(headless: false) do |browser|
+        @playwright_page = browser.new_page(baseURL: base_url)
+        example.run
+      end
+    end
+  end
+end
+```
+
+With the configuration above, we can describe system-test codes with native Playwright methods like below:
+
+```rb
+require 'rails_helper'
+
+describe 'example', driver: :null do
+  let!(:user) { FactoryBot.create(:user) }
+  let(:page) { @playwright_page }
+
+  it 'can browse' do
+    page.goto("/tests/#{user.id}")
+    page.wait_for_selector('input').type('hoge')
+    page.keyboard.press('Enter')
+    expect(page.text_content('#content')).to include('hoge')
+  end
+end
+```

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 10
 ---
 
 # Recording video

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

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 20
 ---
 
 # Semi-automation
@@ -10,7 +10,7 @@ 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.
+Keep in mind repeatedly that persistent browser context is NOT RECOMMENDED for most cases because it would bring many side effects. Consider [reusing cookie and local storage](./use_storage_state) when you just want to keep authenticated across browser contexts.
 
 ## Pause automation for manual operation
 

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

@@ -0,0 +1,78 @@
+---
+sidebar_position: 21
+---
+
+# Reuse Cookie and LocalStorage
+
+In most cases, authentication state is stored in cookie or local storage. When we just want to keep authenticated, it is a good solution to dump/load 'storage state' (= Cookie + LocalStorage).
+https://playwright.dev/docs/next/auth#reuse-authentication-state
+
+* Dump storage state using [BrowserContext#storage_state](/docs/api/browser_context#storage_state) with `path: /path/to/state.json`
+* Load storage state by specifying the parameter `storageState: /path/to/state.json` into [Browser#new_context](/docs/api/browser#new_context) or [Browser#new_page](/docs/api/browser#new_page)
+
+## Example
+
+Generally in browser automation, it is very difficult to bypass 2FA or reCAPTCHA in login screen. In such cases, we would consider
+
+* Authenticate manually by hand
+* Resume automation with the authentication result
+
+
+```ruby {16,21}
+require 'playwright'
+require 'pry'
+
+force_login = !File.exist?('github_state.json')
+
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  if force_login
+    # Use headful mode for manual operation.
+    playwright.chromium.launch(headless: false, channel: 'chrome') do |browser|
+      page = browser.new_page
+      page.goto('https://github.com/login')
+
+      # Login manually.
+      binding.pry
+
+      page.context.storage_state(path: 'github_state.json')
+    end
+  end
+
+  playwright.chromium.launch do |browser|
+    page = browser.new_page(storageState: 'github_state.json')
+    page.goto('https://github.com/notifications')
+    page.screenshot(path: 'github_notification.png')
+  end
+end
+```
+
+When we execute this script at the first time (without github_state.json), login screen is shown:
+
+![login screen is shown](https://user-images.githubusercontent.com/11763113/129394130-7a248f6a-56f0-40b0-a4dd-f0f65d71b3a9.png)
+
+and input credentials manually:
+
+![input credentials manually](https://user-images.githubusercontent.com/11763113/129394155-fccc280e-5e6b-46c7-8a4d-a99d7db02c7f.png)
+
+and hit `exit` in Pry console.
+
+```
+
+     9:
+    10:     # Login manually. Hit `exit` in Pry console after authenticated.
+    11:     require 'pry'
+    12:     binding.pry
+    13:
+ => 14:     page.context.storage_state(path: 'github_state.json')
+    15:   end if force_login
+    16:
+    17:   playwright.chromium.launch do |browser|
+    18:     page = browser.new_page(storageState: 'github_state.json')
+    19:     page.goto('https://github.com/notifications')
+
+[1] pry(main)> exit
+```
+
+then we can enjoy automation with keeping authenticated. Login screen is never shown until github_state.json is deleted :)
+
+![github_notification.png](https://user-images.githubusercontent.com/11763113/129394879-838797eb-135f-41ab-b965-8d6fabde6109.png)