diff --git a/docs/api/node-events/browser-launch-api.mdx b/docs/api/node-events/browser-launch-api.mdx index d4c0c1bc91..a1507e2d1f 100644 --- a/docs/api/node-events/browser-launch-api.mdx +++ b/docs/api/node-events/browser-launch-api.mdx @@ -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 [Change browser preferences](#Change-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 @@ -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 @@ -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) and [Chromium](https://github.com/cypress-io/cypress-docker-images/tree/master/examples/chromium). +- 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 @@ -127,7 +130,7 @@ on('before:browser:launch', (browser, launchOptions) => { ::: -#### Configure browser environment: +### Configure browser environment :::caution @@ -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: diff --git a/docs/app/references/error-messages.mdx b/docs/app/references/error-messages.mdx index 8413c31b1d..32ba417580 100644 --- a/docs/app/references/error-messages.mdx +++ b/docs/app/references/error-messages.mdx @@ -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