From 377250e12e4dbba9cb9dcdb6905326ef5192b668 Mon Sep 17 00:00:00 2001 From: Zach Bloomquist Date: Mon, 12 Sep 2022 22:57:13 -0400 Subject: [PATCH] docs: document experimentalWebKitSupport (#4710) --- .../guides/guides/cross-browser-testing.md | 4 +- content/guides/guides/launching-browsers.md | 51 +++++++++++++++++++ content/guides/references/experiments.md | 2 + 3 files changed, 56 insertions(+), 1 deletion(-) diff --git a/content/guides/guides/cross-browser-testing.md b/content/guides/guides/cross-browser-testing.md index 116cc04a03..6cbbe3fa22 100644 --- a/content/guides/guides/cross-browser-testing.md +++ b/content/guides/guides/cross-browser-testing.md @@ -5,7 +5,9 @@ title: Cross Browser Testing Cypress has the capability to run tests across multiple browsers. Currently, Cypress has support for [Chrome-family browsers](/guides/guides/launching-browsers#Chrome-Browsers) -(including Electron and Chromium-based Microsoft Edge), and Firefox. +(including Electron and Chromium-based Microsoft Edge), +[WebKit](/guides/guides/launching-browsers#WebKit-Experimental) (Safari's +browser engine), and Firefox. diff --git a/content/guides/guides/launching-browsers.md b/content/guides/guides/launching-browsers.md index b445eec143..546f17c8f7 100644 --- a/content/guides/guides/launching-browsers.md +++ b/content/guides/guides/launching-browsers.md @@ -35,6 +35,7 @@ using number of browsers including: - [Firefox](https://www.mozilla.org/firefox/) - [Firefox Developer Edition](https://www.mozilla.org/firefox/developer/) - [Firefox Nightly](https://www.mozilla.org/firefox/nightly/) +- [WebKit (Experimental)](#WebKit-Experimental) Cypress automatically detects available browsers on your OS. You can switch the browser by using the drop down near the top right corner: @@ -148,6 +149,56 @@ of our [docker images](/examples/examples/docker). By default, we will launch Firefox headlessly during `cypress run`. To run Firefox headed, you can pass the `--headed` argument to `cypress run`. +### WebKit (Experimental) + +Cypress has [experimental](/guides/references/experiments) support for WebKit, +Safari's browser engine. Testing your app with WebKit is representative of how +your app would run in Safari. To opt-in to `experimentalWebKitSupport`, follow +these steps: + +1. Add `experimentalWebKitSupport: true` to your + [configuration](/guides/references/configuration) to enable the experiment. +2. Install the `playwright-webkit` NPM package in your repo to acquire WebKit + itself: `npm install --save-dev playwright-webkit`. + - We built this experiment on top of the Playwright WebKit browser as a + stepping stone towards creating a better UX with Cypress-provided browsers + in the future. Thank you, Playwright contributors. +3. Now, you should be able to use WebKit like any other browser. For example, to + record with WebKit in CI: + ```shell + cypress run --browser webkit --record # ... + ``` + +WebKit support is _experimental_, so you may encounter issues. If you encounter +an issue not on the "Known Issues" list, please +[open an issue](https://github.com/cypress-io/cypress/issues/new/choose) on the +GitHub repository. + +#### Known Issues with `experimentalWebKitSupport` + +- `cy.origin()` and `cy.session()` are not yet supported. +- `cy.intercept()`'s `forceNetworkError` option is disabled. +- When using `experimentalSingleTabRunMode` with video recording in WebKit, only + the video for the first spec is recorded. +- Some differences in `cy.type()` behavior: + - `textInput` events are missing the `data` property + - `beforeinput` events are missing the `inputType` property + - `cy.type('{uparrow}')` and `cy.type('{downarrow}')` on an + `input[type=number]` do not round to the nearest `step` specified +- Stack traces may be missing some function names and location information. +- See issues labeled + [`experiment: webkit`](https://github.com/cypress-io/cypress/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22experiment%3A+webkit%22) + for a complete list. + +#### Linux Dependencies + +WebKit requires additional dependencies to run on Linux. To install the required +dependencies, run this: + +```shell +npx playwright install-deps webkit +``` + ### Launching by a path You can launch any supported browser by specifying a path to the binary: diff --git a/content/guides/references/experiments.md b/content/guides/references/experiments.md index 13be591ce9..35866e4a88 100644 --- a/content/guides/references/experiments.md +++ b/content/guides/references/experiments.md @@ -27,6 +27,7 @@ configuration to Cypress. | `experimentalInteractiveRunEvents` | `false` | Allows listening to the [`before:run`](/api/plugins/before-run-api), [`after:run`](/api/plugins/after-run-api), [`before:spec`](/api/plugins/before-spec-api), and [`after:spec`](/api/plugins/after-spec-api) events in the [setupNodeEvents](/guides/tooling/plugins-guide#Using-a-plugin) function during interactive mode. | | `experimentalModifyObstructiveThirdPartyCode` | `false` | Whether Cypress will search for and replace obstructive code in third party `.js` or `.html` files. NOTE: Setting this flag removes [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). | | `experimentalSourceRewriting` | `false` | Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See [#5273](https://github.com/cypress-io/cypress/issues/5273) for details. | +| `experimentalWebKitSupport` | `false` | Enable experimental support for running tests in WebKit. When set, installs of `playwright-webkit` will be detected and available in Cypress. See [Launching Browsers](/guides/guides/launching-browsers#WebKit-Experimental) for more information. | ## Testing Type-Specific Experiments @@ -56,6 +57,7 @@ configuration object: | Version | Changes | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| [10.8.0](/guides/references/changelog#10-x-y) | Added `experimentalWebKitSupport`. | | [10.6.0](/guides/references/changelog#10-6-0) | Added support for `experimentalSingleTabRunMode`. | | [10.4.0](/guides/references/changelog#10-4-0) | Added support for `experimentalModifyObstructiveThirdPartyCode`. | | [9.6.0](/guides/references/changelog#9-6-0) | Added support for `experimentalSessionAndOrigin` and removed `experimentalSessionSupport`. |