Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: document experimentalWebKitSupport #4710

Merged
merged 6 commits into from
Sep 13, 2022
Merged

docs: document experimentalWebKitSupport #4710

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
78b8bc0
docs: document `experimentalWebKitSupport`
flotwig Sep 1, 2022
685bf3c
document linux deps
flotwig Sep 1, 2022
828ed06
Suggestions from Jess
flotwig Sep 12, 2022
664b931
Add stack trace note
flotwig Sep 12, 2022
46b8cc5
pw s/o
flotwig Sep 12, 2022
04d5129
wording
flotwig Sep 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion content/guides/guides/cross-browser-testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert type="warning">

Expand Down
51 changes: 51 additions & 0 deletions content/guides/guides/launching-browsers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 simulated 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
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add something mentioning the Playwright team/individuas involved in their webkit support we are piggy-backing off, or will we add that somewhere else?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will come in the release blog post announcement.


### Launching by a path

You can launch any supported browser by specifying a path to the binary:
Expand Down
2 changes: 2 additions & 0 deletions content/guides/references/experiments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`. |
Expand Down