playwright-ruby-client 0.6.0 → 0.6.1

data/documentation/docs/api/touchscreen.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 10
+---
+
+# Touchscreen
+
+The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the
+touchscreen can only be used in browser contexts that have been initialized with `hasTouch` set to true.

data/documentation/docs/api/tracing.md

@@ -0,0 +1,54 @@
+---
+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_b375e389cd6685ec49d1ef57f3186da60ef682785c646fe8db351b6f39b1a34c.py
+browser = chromium.launch(traceDir='traces')
+context = browser.new_context()
+context.tracing.start(name="trace", screenshots=True, snapshots=True)
+page.goto("https://playwright.dev")
+context.tracing.stop()
+context.tracing.export("trace.zip")
+
+```
+
+
+## export
+
+```
+def export(path)
+```
+
+Export trace into the file with the given name. Should be called after the tracing has stopped.
+
+## start
+
+```
+def start(name: nil, screenshots: nil, snapshots: nil)
+```
+
+Start tracing.
+
+```python sync title=example_4c72a858b35ec7bd7aaba231cb93acecb7ee4b7ea8048a534f28f7e16af966b8.py
+context.tracing.start(name="trace", screenshots=True, snapshots=True)
+page.goto("https://playwright.dev")
+context.tracing.stop()
+context.tracing.export("trace.zip")
+
+```
+
+
+## stop
+
+```
+def stop
+```
+
+Stop tracing.

data/documentation/docs/api/web_socket.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 10
+---
+
+# WebSocket
+
+Not Implemented

data/documentation/docs/api/worker.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 10
+---
+
+# Worker
+
+Not Implemented

data/documentation/docs/article/api_coverage.mdx

@@ -0,0 +1,11 @@
+---
+position: 20
+---
+
+# API Coverages
+
+`playwright-ruby-client` doesn't cover all of the Playwright APIs. The APIs listed below without strikethrough are available in `playwright-ruby-client`.
+
+import ApiCoverage from '../include/api_coverage.md'
+
+<ApiCoverage />

data/documentation/docs/article/getting_started.md

@@ -0,0 +1,152 @@
+---
+sidebar_position: 0
+---
+
+# Getting started
+
+`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`.
+
+## 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,49 @@
+---
+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.
+
+## 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-1.11.0-linux/playwright.sh'`

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

@@ -0,0 +1,119 @@
+---
+sidebar_position: 2
+---
+
+# Launch Browser
+
+![image](https://user-images.githubusercontent.com/11763113/118982444-68e5a900-b9b6-11eb-92a8-3e8fcbe36186.png)
+
+## Create Playwright session
+
+In oder 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 of 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 is described repetedly, this is the recommended way for creating 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 separated start/end definition. `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 appers in.
+    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
+```

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

@@ -0,0 +1,51 @@
+---
+sidebar_position: 3
+---
+
+# Integration into 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.
+
+## Installation
+
+Add the line below into Gemfile:
+
+```rb
+gem 'capybara-playwright-driver'
+```
+
+and then `bundle install`.
+
+Note that capybara-playwright-driver does not depend on Selenium. But `selenium-webdriver` is also required [on Rails 5.x, 6.0](https://github.com/rails/rails/pull/39179)
+
+## Register and configure Capybara driver
+
+```rb
+Capybara.register_driver(:playwright) do |app|
+  Capybara::Playwright::Driver.new(app,
+    browser_type: :chromium, # :chromium (default) or :firefox, :webkit
+    headless: false, # true for headless mode (default), false for headful mode.
+  )
+end
+```
+
+### Update timeout
+
+Capybara sets the default value of timeout to *2 seconds*. Generally it is too short to wait for HTTP responses.
+
+It is recommended to set the timeout to 15-30 seconds for Playwright driver.
+
+```rb
+Capybara.default_max_wait_time = 15
+```
+
+### (Optional) Update default driver
+
+By default, Capybara driver is set to `:rack_test`, which works only with non-JS contents. If your Rails application has many JavaScript contents, it is recommended to change the default driver to `:playwrite`.
+
+```rb
+Capybara.default_driver = :playwright
+Capybara.javascript_driver = :playwright
+```
+
+It is not mandatry. Without changing the default driver, you can still use Playwright driver by specifying `Capybara.current_driver = :playwrite` (or `driven_by :playwright` in system spec) explicitly.