playwright-ruby-client 0.0.8 → 1.58.1.alpha1

data/documentation/docs/article/getting_started.md

@@ -0,0 +1,161 @@
+---
+sidebar_position: 0
+---
+
+# Getting started
+
+```
+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
+```
+
+and then set `playwright_cli_executable_path: "npx playwright"` into `Playwright.create`.
+
+Other methods of installation are also available. See the detail in [Download Playwright driver](./guides/download_playwright_driver)
+
+## Enjoy with examples
+
+### Capture a site
+
+Navigate pages with `page.goto(url)` and save the screenshot with `page.screenshot(path: './image.png')`.
+
+```rb {6-7}
+require 'playwright'
+
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  playwright.chromium.launch(headless: false) do |browser|
+    page = browser.new_page
+    page.goto('https://github.com/YusukeIwaki')
+    page.screenshot(path: './YusukeIwaki.png')
+  end
+end
+```
+
+![image](https://user-images.githubusercontent.com/11763113/104339718-412f9180-553b-11eb-9116-908e1e4b5186.gif)
+
+### Simple scraping
+
+Extract data from a site.
+
+* Grab DOM elements with `page.query_selector(loc)` and `page.query_selector_all(loc)`
+* Extract data with `elem.evaluate(js)` or `page.eval_on_selector(js)`
+* Wait for navigation with `page.expect_navigation do ... end`
+
+```rb {12-14,17-21}
+require 'playwright'
+
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  playwright.chromium.launch(headless: false) do |browser|
+    page = browser.new_page
+    page.goto('https://github.com/')
+
+    form = page.query_selector("form.js-site-search-form")
+    search_input = form.query_selector("input.header-search-input")
+    search_input.click
+    page.keyboard.type("playwright")
+    page.expect_navigation {
+      page.keyboard.press("Enter")
+    }
+
+    list = page.query_selector("ul.repo-list")
+    items = list.query_selector_all("div.f4")
+    items.each do |item|
+      title = item.eval_on_selector("a", "a => a.innerText")
+      puts("==> #{title}")
+    end
+  end
+end
+```
+
+```
+$ bundle exec ruby main.rb
+==> microsoft/playwright
+==> microsoft/playwright-python
+==> microsoft/playwright-cli
+==> checkly/headless-recorder
+==> microsoft/playwright-sharp
+==> playwright-community/jest-playwright
+==> microsoft/playwright-test
+==> mxschmitt/playwright-go
+==> microsoft/playwright-java
+==> MarketSquare/robotframework-browser
+```
+
+### Android browser automation
+
+As an experimental feature, we can automate Chrome for Android.
+
+```rb
+require 'playwright'
+
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  devices = playwright.android.devices
+  unless devices.empty?
+    device = devices.last
+    begin
+      puts "Model: #{device.model}"
+      puts "Serial: #{device.serial}"
+      puts device.shell('ls /system')
+
+      device.launch_browser do |context|
+        page = context.pages.first
+        page.goto('https://github.com/YusukeIwaki')
+        page.click('header button')
+        page.click('input[name="q"]')
+        page.keyboard.type('puppeteer')
+        page.expect_navigation {
+          page.keyboard.press('Enter')
+        }
+        page.screenshot(path: 'YusukeIwaki.android.png')
+      end
+    ensure
+      device.close
+    end
+  end
+end
+```
+
+![image](https://user-images.githubusercontent.com/11763113/106615177-8467a800-65af-11eb-94d9-c56e71487e78.gif)
+
+### Android native automation
+
+We have to download android-driver for Playwright in advance.
+
+```shell
+$ wget https://github.com/microsoft/playwright/raw/master/bin/android-driver-target.apk -O /path/to/playwright-driver/package/bin/android-driver-target.apk
+$ wget https://github.com/microsoft/playwright/raw/master/bin/android-driver.apk -O /path/to/playwright-driver/package/bin/android-driver.apk
+```
+
+(If you downloaded Playwright via npm, replace /path/to/playwright-driver/package/ with ./node_modules/playwright/ above.)
+
+```rb
+require 'playwright'
+
+Playwright.create(playwright_cli_executable_path: ENV['PLAYWRIGHT_CLI_EXECUTABLE_PATH']) do |playwright|
+  devices = playwright.android.devices
+  unless devices.empty?
+    device = devices.last
+    begin
+      device.shell('input keyevent POWER')
+      device.shell('input keyevent POWER')
+      device.shell('input keyevent 82')
+      sleep 1
+      device.shell('cmd statusbar expand-notifications')
+
+      # pp device.tree
+      # pp device.info(res: 'com.android.systemui:id/clock')
+      device.tap_on(res: 'com.android.systemui:id/clock')
+    ensure
+      device.close
+    end
+  end
+end
+```

data/documentation/docs/article/guides/_category_.yml

@@ -0,0 +1,3 @@
+label: Guides
+position: 10
+collapsed: false

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

@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+---
+
+# Download Playwright driver
+
+`playwright-ruby-client` doesn't include Playwright driver nor its downloader. **We have to install Playwright in advance**, and set the proper CLI path like `Playwright.create(playwright_cli_executable_path: /path/to/playwright)`
+
+Choose any of the three ways as you prefer to download the driver:
+
+- `npx`: suitable for playground use, and not suitable for continuous usage.
+- `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
+$ npx playwright install
+```
+
+and then set `playwright_cli_executable_path: "npx playwright"` at `Playwright.create`.
+
+## Using `npm install`
+
+Actually `npx playwright` is a bit slow. We can also use `npm install` to setup.
+
+Instead of `npx playwright install`:
+
+```shell
+$ export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION.strip')
+$ npm install playwright@$PLAYWRIGHT_CLI_VERSION || npm install playwright@next
+$ ./node_modules/.bin/playwright install
+```
+
+and then set `playwright_cli_executable_path: './node_modules/.bin/playwright'`
+
+## Directly download driver without Node.js installation.
+
+Instead of npm, you can also directly download playwright driver from playwright.azureedge.net. (The URL can be easily detected from [here](https://github.com/microsoft/playwright-python/blob/cfc1030a69d1e934cac579687a680eac53d4b9ee/setup.py#L75))
+
+```shell
+$ export PLAYWRIGHT_CLI_VERSION=$(bundle exec ruby -e 'puts Playwright::COMPATIBLE_PLAYWRIGHT_VERSION.strip')
+$ wget https://playwright.azureedge.net/builds/driver/playwright-$PLAYWRIGHT_CLI_VERSION-linux.zip
+```
+
+and then extract it, and set `playwright_cli_executable_path: '/path/to/playwright-$PLAYWRIGHT_CLI_VERSION-linux/node /path/to/playwright-$PLAYWRIGHT_CLI_VERSION-linux/package/cli.js'`

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

@@ -0,0 +1,31 @@
+---
+sidebar_position: 30
+---
+
+# Playwright inspector
+
+Playwright provides a useful inspector.
+https://playwright.dev/docs/inspector/
+
+## Overview
+
+```ruby {4,8}
+playwright.chromium.launch(headless: false) do |browser|
+  browser.new_context do |context|
+    # This method call should be put just after creating BrowserContext.
+    context.enable_debug_console!
+
+    page = context.new_page
+    page.goto('http://example.com/')
+    page.pause
+  end
+end
+```
+
+`page.pause` requires Playwright debug session, and it can be enabled by calling `BrowserContext#enable_debug_console!` in advance.
+
+Note that since Ruby is not officially supported in Playwright, many limitations exist. We CANNOT
+
+* Launch inspector via `PWDEBUG=1`
+* Debug without inspector UI (`PWDEBUG=console` is not working well)
+* Show Ruby code in inspector

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

@@ -0,0 +1,121 @@
+---
+sidebar_position: 2
+---
+
+# Launch Browser
+
+![image](https://user-images.githubusercontent.com/11763113/118982444-68e5a900-b9b6-11eb-92a8-3e8fcbe36186.png)
+
+## Create Playwright session
+
+In order to launch browser, it is required to create Playwright session.
+
+In previous examples,
+
+```rb
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  # Play with `playwright` here
+end
+```
+
+this is the exact procedure for creating Playwright session. Choose either method for creating the session.
+
+### Define scoped Playwright session with block
+
+```rb
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  # Play with `playwright` here
+end
+```
+
+As described repeatedly, this is the recommended way for creating a Playwright session. Even when any exception happens, Playwright session is safely ended on leaving the block.
+
+Internally `playwright run-driver` session is alive during the block.
+
+### Define start/end of the Playwright session separately without block.
+
+Sometimes we have to define separate start/end definitions. `playwright-ruby-client` also allows it.
+
+```rb
+class SomeClass
+
+  def start_playwright
+    # Start Playwright driver (runs `playwright run-driver` internally)
+    @playwright_exec = Playwright.create(playwright_cli_executable_path: 'npx playwright')
+  end
+
+  def stop_playwright!
+    # Stop Playwright driver
+    @playwright_exec.stop
+  end
+
+  def play_with_playwright(&blk)
+    # Acquire Playwright instance with PlaywrightExecution#playwright
+    playwright = @playwright_exec.playwright
+
+    browser = playwright.chromium.launch
+
+    begin
+      blk.call(browser)
+    ensure
+      browser.close
+    end
+  end
+end
+```
+
+Note that we have to make sure to call `PlaywrightExecution#stop` (`stop_playwright!` in this case).
+
+## Create browser instance
+
+Playwright allows launching several browsers.
+
+* `playwright.chromium.launch` for launching Chrome, Microsoft Edge, Chromium
+* `playwright.firefox.launch` for launching (modified version of) Firefox
+* `playwright.webkit.launch` for launching (modified version of) WebKit/Safari
+
+It is recommended in most cases to launch browser with block, which automatically closes the launched browser on end.
+
+```rb
+# scoped browser block
+playwright.chromium.launch do |browser|
+  # Play with `browser`
+end
+```
+
+Of course, you can manually call `Browser#close` when the browser is launched without block.
+
+```rb
+# separated start/end
+browser = playwright.chromium.launch
+
+begin
+  # Play with `@browser`
+ensure
+  browser.close
+end
+```
+
+## Open new window and new tab
+
+Use `Browser#new_context` to prepare a new browser window and use `BrowserContext#new_page` to create a new tab.
+Also we can use `Browser#new_page` to create a new window and new tab at once.
+
+```rb
+Playwright.create(playwright_cli_executable_path: 'npx playwright') do |playwright|
+  playwright.chromium.launch(headless: false) do |browser| # Chromium task icon appears.
+    context = browser.new_context # Prepare new window.
+    page = context.new_page # Open new window and new tab here. (about:blank)
+    page.goto('https://example.com') # Navigate to a site.
+
+    page2 = context.new_page # Open another tab here.
+    page2.goto('https://example.com') # Navigate to a site.
+
+    another_context = browser.new_context # Prepare another window here.
+    another_page = another_context.new_page # Open a new window and new tab.
+    another_page.goto('https://example.com/') # Navigate to a site.
+  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,112 @@
+---
+sidebar_position: 40
+---
+
+# 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.
+
+ref: https://playwright.dev/docs/docker#remote-connection
+
+## Overview
+
+Playwright 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)
+
+- Server can be launched with `npx playwright run-server` CLI command.
+- 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.
+
+### Client code
+
+Many example uses `Playwright#create`, which internally uses Pipe (stdin/stdout) transport for Playwright-protocol messaging. Instead, **use `Playwright#connect_to_browser_server(endpoint)`** for WebSocket transport.
+
+```ruby {3}
+require 'playwright'
+
+Playwright.connect_to_browser_server('wss://example.com:8888/ws') do |browser|
+  page = browser.new_page
+  page.goto('https://github.com/microsoft/playwright')
+  page.screenshot(path: 'github-microsoft-playwright.png')
+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"`.
+
+We can also pass launchOptions parameters using a `launch-options` query string like this:
+
+```ruby {3-4}
+require 'json'
+
+launch_params = { headless: false }
+Playwright.connect_to_browser_server("wss://example.com:8888/ws?launch-options=#{launch_params.to_json}") do |browser|
+  page = browser.new_page
+  page.goto('https://github.com/microsoft/playwright')
+  page.screenshot(path: 'github-microsoft-playwright_headful.png')
+end
+
+Playwright.connect_to_browser_server('wss://example.com:8888/ws') do |browser|
+  page = browser.new_page
+  page.goto('https://github.com/microsoft/playwright')
+  page.screenshot(path: 'github-microsoft-playwright_headless.png')
+end
+```
+
+### 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 --path /ws`. (`$PORT` is a port number of the server)
+
+If custom Docker image is preferred, build it as follows:
+
+```Dockerfile
+FROM mcr.microsoft.com/playwright
+
+WORKDIR /root
+RUN npm install playwright && ./node_modules/.bin/playwright install
+
+ENV PORT 8888
+CMD ["./node_modules/.bin/playwright", "run-server", "--port", "$PORT", "--path", "/ws"]
+```
+
+## 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 --browser chromium
+```
+
+See [the official documentation](https://playwright.dev/docs/debug/#verbose-api-logs) for details.