Drastically simplify testing on CI with the Cypress GitHub Action

Learn more

Browser Launch API

Improve this doc

Before Cypress launches a browser, it gives you the ability to modify the arguments used to launch it.

This is helpful to modify, remove, or add your own arguments.

The most common use case is adding your own web extension - example recipe.


Modify args based on browser

Using your pluginsFile you can tap into the before:browser:launch event and modify the arguments based on the browser that Cypress is launching.

This event will yield you the browser as an object, and args which are the default arguments used to launch the browser.

args may be an array or an object (based on the type of browser we’re launching). Whatever you return from this event will become the new args for launching the browser.

Here are options for the currently supported browsers:

module.exports = (on, config) => {
  on('before:browser:launch', (browser = {}, args) => {
    // browser will look something like this
    // {
    //   name: 'chrome',
    //   displayName: 'Chrome',
    //   version: '63.0.3239.108',
    //   path: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
    //   majorVersion: '63'
    // }

    if (browser.name === 'chrome') {
      // `args` is an array of all the arguments
      // that will be passed to Chrome when it launchers

      // whatever you return here becomes the new args
      return args

    if (browser.name === 'electron') {
      // `args` is a `BrowserWindow` options object
      // https://electronjs.org/docs/api/browser-window#new-browserwindowoptions
      args['fullscreen'] = true

      // whatever you return here becomes the new args
      return args

Modify Electron app switches

Cypress Test Runner is an Electron application, and its behavior (and the behavior of the bundled-in Electron browser) can be customized using command line switches. The supported switches depend on the Electron version, see Electron documentation.

You can pass Electron-specific launch arguments using the ELECTRON_EXTRA_LAUNCH_ARGS environment variable. For example, to disable HTTP browser cache and ignore certificate errors, open or run the Cypress Test Runner like this:

export ELECTRON_EXTRA_LAUNCH_ARGS=--disable-http-cache --ignore-certificate-errors
npx cypress open|run

Cypress already sets some the Electron command line switches internally. See file packages/server/lib/environment.coffee. There is no way to see all currently set switches after Electron’s launch.

See all Chrome browser switches

If you are running Cypress tests using Chrome browser, you can see ALL currently set command line switches and the browser version information by opening a new tab and typing chrome://version url.

See all Chrome switches


Use fake video for webcam testing

By default, Cypress passes the Chrome command line switch to enable a fake video for a media stream. This is to better enable testing webcam functionality without having to have the necessary hardware to test.

Enable fake video for testing

You can however send your own video file for testing by passing a Chrome command line switch pointing to a video file.

module.exports = (on, config) => {
  on('before:browser:launch', (browser = {}, args) => {
    if (browser.name === 'chrome') {
      // Mac/Linux

      // Windows
      // args.push('--use-file-for-fake-video-capture=c:\\path\\to\\video\\my-video.y4m')

    return args