playwright-ruby-client 0.6.0 → 0.6.5

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,47 @@
+---
+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")
+
+```
+
+
+
+## start
+
+```
+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)
+page.goto("https://playwright.dev")
+context.tracing.stop()
+context.tracing.stop(path = "trace.zip")
+
+```
+
+
+
+## stop
+
+```
+def stop(path: nil)
+```
+
+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,24 @@
+---
+sidebar_position: 10
+---
+
+# Worker
+
+The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). `worker`
+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)
+
+```
+
+

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,205 @@
+---
+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 = :playwright` (or `driven_by :playwright` in system spec) explicitly.
+
+### (reference) Available driver options
+
+These parameters can be passed into `Capybara::Playwright::Driver.new`
+
+* `playwright_cli_executable_path`
+  * Refer [this article](./download_playwright_driver) to understand what to specify.
+* `browser_type`
+  * `:chromium` (default), `:firefox`, or `:webkit`
+* Parameters for [Playwright::BrowserType#launch](/docs/api/browser_type#launch)
+  * args
+  * channel
+    * `chrome`, `msedge`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge-beta`, `msedge-dev` Browser distribution channel. Read more about using [Google Chrome & Microsoft Edge](https://playwright.dev/docs/browsers#google-chrome--microsoft-edge)
+  * devtools
+  * downloadsPath
+  * env
+  * executablePath
+  * firefoxUserPrefs
+  * headless
+  * ignoreDefaultArgs
+  * proxy
+  * slowMo
+  * timeout
+* Parameters for [Playwright::Browser#new_context](/docs/api/browser#new_context)
+  * bypassCSP
+  * colorScheme
+  * deviceScaleFactor
+  * extraHTTPHeaders
+  * geolocation
+  * hasTouch
+  * httpCredentials
+  * ignoreHTTPSErrors
+  * isMobile
+  * javaScriptEnabled
+  * locale
+  * noViewport
+  * offline
+  * permissions
+  * proxy
+  * record_har_omit_content
+  * record_har_path
+  * record_video_dir
+  * record_video_size
+  * screen
+  * storageState
+  * timezoneId
+  * userAgent
+  * viewport
+
+```ruby
+driver_opts = {
+  # `playwright` command path.
+  playwright_cli_executable_path: './node_modules/.bin/playwright',
+
+  # Use firefox for testing.
+  browser_type: :firefox,
+
+  # Headful mode.
+  headless: false,
+
+  # Slower operation
+  slowMo: 50, # integer. (50-100 would be good for most cases)
+}
+
+Capybara::Playwright::Driver.new(app, driver_opts)
+```
+
+
+## Available functions and Limitations
+
+### Capybara DSL
+
+Most of the methods of `Capybara::Session` and `Capybara::Node::Element` are available. However the following method is not yet implemented.
+
+* `Capybara::Node::Element#drop`
+
+### Playwright-native scripting
+
+We can also describe Playwright-native automation script using `with_playwright_page` and `with_playwright_element_handle`.
+
+```ruby
+# With Capybara DSL
+find('a[data-item-type="global_search"]').click
+
+# With Playwright-native Page
+Capybara.current_session.driver.with_playwright_page do |page|
+  # `page` is an instance of Playwright::Page.
+  page.click('a[data-item-type="global_search"]')
+end
+```
+
+```ruby
+all('.list-item').each do |li|
+  # With Capybara::Node::Element method
+  puts li.all('a').first.text
+
+  # With Playwright-native ElementHandle
+  puts li.with_playwright_element_handle do |handle|
+    # `handle` is an instance of Playwright::ElementHandle
+    handle.query_selector('a').text_content
+  end
+end
+```
+
+Generally, Capybara DSL seems simple, but Playwright-native scripting are more precise and efficient. Also `waitForNavigation`, `waitForSelector`, and many other Playwright functions are available with Playwright-native scripting.
+
+### Screen recording
+
+NO NEED to keep sitting in front of screen during test. Just record what happened with video.
+
+For example, we can store the video for [Allure report](https://github.com/allure-framework/allure-ruby) as below:
+
+```ruby
+before do |example|
+  Capybara.current_session.driver.on_save_screenrecord do |video_path|
+    Allure.add_attachment(
+      name: "screenrecord - #{example.description}",
+      source: File.read(video_path),
+      type: Allure::ContentType::WEBM,
+      test_case: true,
+    )
+  end
+end
+```
+
+![sceenrecord](https://user-images.githubusercontent.com/11763113/121126629-71b5f600-c863-11eb-8f88-7924ab669946.gif)
+
+For more details, refer [Recording video](./recording_video.md#using-screen-recording-from-capybara-driver)
+
+
+### Screenshot just before teardown
+
+In addition to `Capybara::Session#save_screenshot`, capybara-playwright-driver have another method for storing last screen state just before teardown.
+
+For example, we can attach the screenshot for [Allure report](https://github.com/allure-framework/allure-ruby) as below:
+
+```ruby
+before do |example|
+  Capybara.current_session.driver.on_save_raw_screenshot_before_reset do |raw_screenshot|
+    Allure.add_attachment(
+      name: "screenshot - #{example.description}",
+      source: raw_screenshot,
+      type: Allure::ContentType::PNG,
+      test_case: true,
+    )
+  end
+end
+```
+
+### Limitations
+
+* 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.