playwright-ruby-client 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 623dc9bf11ce77bda6cd9006c727e31060564810bac0ccf5f06aabffc5976c07
-  data.tar.gz: 206995c24a6cbd4dcd6867eaa076e3b3052b7a7056cd63188a7ebb0e54c38056
+  metadata.gz: 9342eb9d31cb69d5eee5734d2143505672336cb630599f5d92a3e07559b76421
+  data.tar.gz: 66a5f38c686c7477037740cddf2d6572b63b21dd791f92a0c179fd292ee0b8e6
 SHA512:
-  metadata.gz: a341d042e6e35b5205f56303efda6fe9a34e857c12696622c366f0ebbc113816b3418e05e87b8fe60867ae2252964a36545b8bd782cf61f9c23f42e868cb098a
-  data.tar.gz: 68fc458f0fc750c208f8daa7f900ef33977987aa6684db4edea20c42cf5f3837deb4e5b828385fd9c25d11769ff1b345cdb795aef370158bd009a515dfeeb54d
+  metadata.gz: 9adc1be3cbef06c38bcb1080e26c8b816311dc81573b6d089f55fd286e9e29d9a29831f1655a2d8189d1c20ed6bea0fd108a98ed347d4c1c1281753d64cddd2b
+  data.tar.gz: f65e5ff953e8b1f6ef54a031cda1a53819bdb0c62caa44b5dc34a2011bc1d72d867a838de98bc7e2cbc8b0d34899cf19b6b89c4d008aa7a98f60871e91b3021e

data/documentation/docs/api/browser.md

@@ -138,7 +138,8 @@ def new_page(
       storageState: nil,
       timezoneId: nil,
       userAgent: nil,
-      viewport: nil)
+      viewport: nil,
+      &block)
 ```
 
 Creates a new page in a new browser context. Closing this page will close the context as well.

data/documentation/docs/api/browser_context.md

@@ -229,7 +229,7 @@ specified.
 ## new_page
 
 ```
-def new_page
+def new_page(&block)
 ```
 
 Creates a new page in the browser context.

data/documentation/docs/api/browser_type.md

@@ -65,7 +65,7 @@ def launch(
       proxy: nil,
       slowMo: nil,
       timeout: nil,
-      traceDir: nil,
+      tracesDir: nil,
       &block)
 ```
 
@@ -96,6 +96,59 @@ differences between Chromium and Chrome.
 [This article](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/chromium_browser_vs_google_chrome.md)
 describes some differences for Linux users.
 
+## launch_persistent_context
+
+```
+def launch_persistent_context(
+      userDataDir,
+      acceptDownloads: nil,
+      args: nil,
+      bypassCSP: nil,
+      channel: nil,
+      chromiumSandbox: nil,
+      colorScheme: nil,
+      deviceScaleFactor: nil,
+      devtools: nil,
+      downloadsPath: nil,
+      env: nil,
+      executablePath: nil,
+      extraHTTPHeaders: nil,
+      geolocation: nil,
+      handleSIGHUP: nil,
+      handleSIGINT: nil,
+      handleSIGTERM: nil,
+      hasTouch: nil,
+      headless: nil,
+      httpCredentials: nil,
+      ignoreDefaultArgs: nil,
+      ignoreHTTPSErrors: nil,
+      isMobile: nil,
+      javaScriptEnabled: nil,
+      locale: nil,
+      noViewport: nil,
+      offline: nil,
+      permissions: nil,
+      proxy: nil,
+      record_har_omit_content: nil,
+      record_har_path: nil,
+      record_video_dir: nil,
+      record_video_size: nil,
+      reducedMotion: nil,
+      screen: nil,
+      slowMo: nil,
+      timeout: nil,
+      timezoneId: nil,
+      tracesDir: nil,
+      userAgent: nil,
+      viewport: nil,
+      &block)
+```
+
+Returns the persistent browser context instance.
+
+Launches browser that uses persistent storage located at `userDataDir` and returns the only context. Closing this
+context will automatically close the browser.
+
 ## name
 
 ```

data/documentation/docs/api/experimental/android.md

@@ -4,14 +4,15 @@ sidebar_position: 10
 
 # Android
 
-Playwright has **experimental** support for Android automation. You can access android namespace via:
+Playwright has **experimental** support for Android automation. See [here](https://playwright.dev/python/docs/mobile) for more information. You can
+access android namespace via:
 
 An example of the Android automation script would be:
 
 Note that since you don't need Playwright to install web browsers when testing Android, you can omit browser download
 via setting the following environment variable when installing Playwright:
 
-```sh js
+```bash js
 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm i -D playwright
 ```
 

data/documentation/docs/api/page.md

@@ -1393,6 +1393,14 @@ page.wait_for_url("**/target.html")
 
 Shortcut for main frame's [Frame#wait_for_url](./frame#wait_for_url).
 
+## expect_websocket
+
+```
+def expect_websocket(predicate: nil, timeout: nil, &block)
+```
+
+Performs action and waits for a new [WebSocket](./web_socket). If predicate is provided, it passes [WebSocket](./web_socket) value into the `predicate` function and waits for `predicate.call(web_socket)` to return a truthy value. Will throw an error if the page is closed before the WebSocket event is fired.
+
 ## accessibility
 
 ## keyboard

data/documentation/docs/api/route.md

@@ -23,18 +23,16 @@ def continue(headers: nil, method: nil, postData: nil, url: nil)
 
 Continues route's request with optional overrides.
 
-```python sync title=example_1960aabd58c9553683368e29429d39c1209d35e6e3625bbef1280a1fa022a9ee.py
-def handle(route, request):
-    # override headers
-    headers = {
-        **request.headers,
-        "foo": "bar" # set "foo" header
-        "origin": None # remove "origin" header
-    }
-    route.continue_(headers=headers)
-}
-page.route("**/*", handle)
-
+```ruby
+def handle(route, request)
+  # override headers
+  headers = request.headers
+  headers['foo'] = 'bar' # set "foo" header
+  headers['user-agent'] = 'Unknown Browser' # modify user-agent
+
+  route.continue(headers: headers)
+end
+page.route("**/*", method(:handle))
 ```
 
 
@@ -54,19 +52,20 @@ Fulfills route's request with given response.
 
 An example of fulfilling all requests with 404 responses:
 
-```python sync title=example_6d2dfd4bb5c8360f8d80bb91c563b0bd9b99aa24595063cf85e5a6e1b105f89c.py
-page.route("**/*", lambda route: route.fulfill(
-    status=404,
-    content_type="text/plain",
-    body="not found!"))
-
+```ruby
+page.route("**/*", ->(route, request) {
+  route.fulfill(
+    status: 404,
+    contentType: 'text/plain',
+    body: 'not found!!',
+  )
+})
 ```
 
 An example of serving static file:
 
-```python sync title=example_c77fd0986d0b74c905cd9417756c76775e612cc86410f9a5aabc5b46d233d150.py
-page.route("**/xhr_endpoint", lambda route: route.fulfill(path="mock_data.json"))
-
+```ruby
+page.route("**/xhr_endpoint", ->(route, _) { route.fulfill(path: "mock_data.json") })
 ```
 
 

data/documentation/docs/api/tracing.md

@@ -9,24 +9,16 @@ Playwright script runs.
 
 Start with specifying the folder traces will be stored in:
 
-```python sync title=example_b375e389cd6685ec49d1ef57f3186da60ef682785c646fe8db351b6f39b1a34c.py
-browser = chromium.launch(traceDir='traces')
+```python sync title=example_a767dfb400d98aef50f2767b94171d23474ea1ac1cf9b4d75d412936208e652d.py
+browser = chromium.launch()
 context = browser.new_context()
-context.tracing.start(name="trace", screenshots=True, snapshots=True)
+context.tracing.start(screenshots=True, snapshots=True)
 page.goto("https://playwright.dev")
-context.tracing.stop()
-context.tracing.export("trace.zip")
+context.tracing.stop(path = "trace.zip")
 
 ```
 
 
-## export
-
-```
-def export(path)
-```
-
-Export trace into the file with the given name. Should be called after the tracing has stopped.
 
 ## start
 
@@ -36,19 +28,20 @@ def start(name: nil, screenshots: nil, snapshots: nil)
 
 Start tracing.
 
-```python sync title=example_4c72a858b35ec7bd7aaba231cb93acecb7ee4b7ea8048a534f28f7e16af966b8.py
+```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.export("trace.zip")
+context.tracing.stop(path = "trace.zip")
 
 ```
 
 
+
 ## stop
 
 ```
-def stop
+def stop(path: nil)
 ```
 
 Stop tracing.

data/documentation/docs/api/web_socket.md

@@ -4,4 +4,41 @@ sidebar_position: 10
 
 # WebSocket
 
-Not Implemented
+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/rails_integration.md

@@ -41,11 +41,165 @@ 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`.
+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 `:playwright`.
 
 ```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.
+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.