Skip to content

Commit 4aabad9

Browse files
Update limitations for loading extensions within Cypress (#6183)
* update limitations for loading extensions within Cypress * Update instructions to link to our docker image examples for other browsers * lint fix * Update docs/api/node-events/browser-launch-api.mdx Co-authored-by: Mike McCready <[email protected]> * Update docs/api/node-events/browser-launch-api.mdx Co-authored-by: Mike McCready <[email protected]> --------- Co-authored-by: Mike McCready <[email protected]>
1 parent aac4097 commit 4aabad9

File tree

2 files changed

+17
-24
lines changed

2 files changed

+17
-24
lines changed

docs/api/node-events/browser-launch-api.mdx

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -49,17 +49,15 @@ An object describing the browser being launched, with the following properties:
4949
Options that can be modified to control how the browser is launched, with the
5050
following properties:
5151

52-
| Property | Type | Description |
53-
| ------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54-
| `preferences` | `object` | An object describing browser preferences. Differs between browsers. See [Changing browser preferences](#Changing-browser-preferences) for details. |
55-
| `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. |
56-
| `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. |
57-
| `env` | `object` | An object of environment variables to pass to the launched browser. See [Configure browser environment](#Configure-browser-environment) for details. |
52+
| Property | Type | Description |
53+
| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54+
| `preferences` | `object` | An object describing browser preferences. Differs between browsers. See [Change browser preferences](#Change-browser-preferences) for details. |
55+
| `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. |
56+
| `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. |
57+
| `env` | `object` | An object of environment variables to pass to the launched browser. See [Configure browser environment](#Configure-browser-environment) for details. |
5858

5959
## Usage
6060

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

75-
#### Modify browser launch arguments:
73+
### Modify browser launch arguments
7674

7775
Here are args available for the currently supported browsers:
7876

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

82-
##### Open devtools by default
80+
#### Open devtools by default
8381

8482
:::cypress-config-plugin-example
8583

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

112110
:::
113111

114-
#### Add browser extensions:
112+
### Add browser extensions
113+
114+
**Limitations:**
115+
116+
- Headless Chrome does not support loading extensions.
117+
- 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) and [Chromium](https://github.com/cypress-io/cypress-docker-images/tree/master/examples/chromium).
118+
- Electron currently supports only Chrome DevTools extensions.
115119

116120
:::cypress-config-plugin-example
117121

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

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

128131
:::
129132

130-
#### Configure browser environment:
133+
### Configure browser environment
131134

132135
:::caution
133136

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

149152
:::
150153

151-
#### Changing browser preferences:
154+
### Change browser preferences
152155

153156
Here are preferences available for the currently supported browsers:
154157

docs/app/references/error-messages.mdx

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -990,16 +990,6 @@ one of the following:
990990
- See
991991
[Cypress detected policy settings on your computer that may cause issues](#Cypress-detected-policy-settings-on-your-computer-that-may-cause-issues).
992992

993-
**The `--proxy-server` or `--load-extension` arguments have been changed**
994-
995-
- When adding a plugin with the
996-
[Browser Launch API](/api/node-events/browser-launch-api), it's possible for a
997-
necessary command-line argument to be changed. If you're running into this
998-
error, you can troubleshoot by inspecting `args` before and after the plugin
999-
runs, either by using `console.log()` or by
1000-
[printing DEBUG logs](/app/references/troubleshooting#Print-DEBUG-logs)
1001-
with `DEBUG=cypress:server:plugins,cypress:server:plugins:*`.
1002-
1003993
**You visit the Cypress proxy URL outside of a Cypress browser.**
1004994

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

0 commit comments

Comments
 (0)