Skip to content

Update limitations for loading extensions within Cypress #6183

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

Merged
merged 5 commits into from
May 15, 2025
Merged

Update limitations for loading extensions within Cypress #6183

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9c88ce6
update limitations for loading extensions within Cypress
jennifer-shehane May 13, 2025
f69ddaf
Update instructions to link to our docker image examples for other br…
jennifer-shehane May 13, 2025
a7e8724
lint fix
jennifer-shehane May 13, 2025
87c585d
Update docs/api/node-events/browser-launch-api.mdx
jennifer-shehane May 14, 2025
7b2c0d1
Update docs/api/node-events/browser-launch-api.mdx
jennifer-shehane May 14, 2025
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
31 changes: 17 additions & 14 deletions docs/api/node-events/browser-launch-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,17 +49,15 @@ An object describing the browser being launched, with the following properties:
Options that can be modified to control how the browser is launched, with the
following properties:

| Property | Type | Description |
| ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preferences` | `object` | An object describing browser preferences. Differs between browsers. See [Changing browser preferences](#Changing-browser-preferences) for details. |
| `args` | `string[]` | An array of strings that will be passed as command-line args when the browser is launched. Has no effect on Electron. See [Modify browser launch arguments](#Modify-browser-launch-arguments) for details. |
| `extensions` | `string[]` | An array of paths to folders containing unpacked WebExtensions to be loaded before the browser starts. Note: Electron currently only supports Chrome DevTools extensions. See [Add browser extensions](#Add-browser-extensions) for details. |
| `env` | `object` | An object of environment variables to pass to the launched browser. See [Configure browser environment](#Configure-browser-environment) for details. |
| Property | Type | Description |
| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preferences` | `object` | An object describing browser preferences. Differs between browsers. See [Changing browser preferences](#Changing-browser-preferences) for details. |
| `args` | `string[]` | An array of strings that will be passed as command-line args when the browser is launched. Has no effect on Electron. See [Modify browser launch arguments](#Modify-browser-launch-arguments) for details. |
| `extensions` | `string[]` | An array of paths to folders containing unpacked WebExtensions to be loaded before the browser starts. See [Add browser extensions](#Add-browser-extensions) for details. |
| `env` | `object` | An object of environment variables to pass to the launched browser. See [Configure browser environment](#Configure-browser-environment) for details. |

## Usage

### Modify browser launch arguments, preferences, extensions, and environment

Using the [setupNodeEvents](/app/plugins/plugins-guide#Using-a-plugin)
function you can tap into the `before:browser:launch` event and modify how
Cypress launches the browser (e.g. modify arguments, user preferences, and
Expand All @@ -72,14 +70,14 @@ how the browser is launched.
The returned `launchOptions` object will become the new launch options for the
browser.

#### Modify browser launch arguments:
### Modify browser launch arguments

Here are args available for the currently supported browsers:

- [Chromium-based browsers](https://peter.sh/experiments/chromium-command-line-switches/)
- [Firefox](https://developer.mozilla.org/docs/Mozilla/Command_Line_Options)

##### Open devtools by default
#### Open devtools by default

:::cypress-config-plugin-example

Expand Down Expand Up @@ -111,14 +109,19 @@ on('before:browser:launch', (browser = {}, launchOptions) => {

:::

#### Add browser extensions:
### Add browser extensions

**Limitations:**

- Headless Chrome does not support loading extensions.
- Chrome-branded browsers (e.g., standard Chrome) version 137 and above no longer support extension loading via this API, due to the removal of the --load-extension flag by Chrome. We recommend using Chrome for Testing or Chromium instead. See Cypress Docker image examples for [Chrome for Testing](https://github.com/cypress-io/cypress-docker-images/tree/master/examples/chrome-for-testing?rgh-link-date=2025-05-13T19%3A08%3A57.000Z) and [Chromium](https://github.com/cypress-io/cypress-docker-images/tree/master/examples/chromium?rgh-link-date=2025-05-13T19%3A08%3A57.000Z).
- Electron currently supports only Chrome DevTools extensions.

:::cypress-config-plugin-example

```ts
on('before:browser:launch', (browser, launchOptions) => {
// supply the absolute path to an unpacked extension's folder
// NOTE: extensions cannot be loaded in headless Chrome
launchOptions.extensions.push('Users/jane/path/to/extension')

return launchOptions
Expand All @@ -127,7 +130,7 @@ on('before:browser:launch', (browser, launchOptions) => {

:::

#### Configure browser environment:
### Configure browser environment

:::caution

Expand All @@ -148,7 +151,7 @@ on('before:browser:launch', (browser, launchOptions) => {

:::

#### Changing browser preferences:
### Change browser preferences

Here are preferences available for the currently supported browsers:

Expand Down
10 changes: 0 additions & 10 deletions docs/app/references/error-messages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -990,16 +990,6 @@ one of the following:
- See
[Cypress detected policy settings on your computer that may cause issues](#Cypress-detected-policy-settings-on-your-computer-that-may-cause-issues).

**The `--proxy-server` or `--load-extension` arguments have been changed**

- When adding a plugin with the
[Browser Launch API](/api/node-events/browser-launch-api), it's possible for a
necessary command-line argument to be changed. If you're running into this
error, you can troubleshoot by inspecting `args` before and after the plugin
runs, either by using `console.log()` or by
[printing DEBUG logs](/app/references/troubleshooting#Print-DEBUG-logs)
with `DEBUG=cypress:server:plugins,cypress:server:plugins:*`.

**You visit the Cypress proxy URL outside of a Cypress browser.**

- Don't copy the URL you see when launching a Cypress browser from the Cypress
Expand Down