-

cli/CHANGELOG.md

@@ -3,6 +3,10 @@
 
 _Released 11/5/2024 (PENDING)_
 
+**Features:**
+
+- Added new [`defaultBrowser`](https://docs.cypress.io/app/references/configuration) configuration option to specify the default browser to launch. Addresses [#6646](https://github.com/cypress-io/cypress/issues/6646).
+
 **Bugfixes:**
 
 - Fixed an issue where the Cypress runner could hang in `after` or `afterEach` hooks that run Cypress commands after a page load timeout error occurs. Addresses [#30238](https://github.com/cypress-io/cypress/issues/30238).

cli/types/cypress.d.ts

@@ -3216,6 +3216,11 @@ declare namespace Cypress {
     setupNodeEvents: (on: PluginEvents, config: PluginConfigOptions) => Promise<PluginConfigOptions | void> | PluginConfigOptions | void
 
     indexHtmlFile: string
+
+    /**
+     * The default browser to launch if the "--browser" command line option is not provided.
+     */
+    defaultBrowser: string
   }
 
   interface EndToEndConfigOptions extends Omit<CoreConfigOptions, 'indexHtmlFile'> {

packages/config/__snapshots__/index.spec.ts.js

@@ -26,6 +26,7 @@ exports['config/src/index .getDefaultValues returns list of public config keys 1
     'specPattern': '**/*.cy.{js,jsx,ts,tsx}',
     'indexHtmlFile': 'cypress/support/component-index.html',
   },
+  'defaultBrowser': null,
   'defaultCommandTimeout': 4000,
   'downloadsFolder': 'cypress/downloads',
   'e2e': {
@@ -117,6 +118,7 @@ exports['config/src/index .getDefaultValues returns list of public config keys f
     'specPattern': '**/*.cy.{js,jsx,ts,tsx}',
     'indexHtmlFile': 'cypress/support/component-index.html',
   },
+  'defaultBrowser': null,
   'defaultCommandTimeout': 4000,
   'downloadsFolder': 'cypress/downloads',
   'e2e': {
@@ -206,6 +208,7 @@ exports['config/src/index .getPublicConfigKeys returns list of public config key
   'chromeWebSecurity',
   'clientCertificates',
   'component',
+  'defaultBrowser',
   'defaultCommandTimeout',
   'downloadsFolder',
   'e2e',

packages/config/src/options.ts

@@ -169,6 +169,10 @@ const driverConfigOptions: Array<DriverConfigOption> = [
       indexHtmlFile: 'cypress/support/component-index.html',
     },
     validation: isValidConfig,
+  }, {
+    name: 'defaultBrowser',
+    defaultValue: null,
+    validation: validate.isString,
   }, {
     name: 'defaultCommandTimeout',
     defaultValue: 4000,

packages/config/test/project/utils.spec.ts

@@ -1054,6 +1054,7 @@ describe('config/src/project/utils', () => {
             browsers: { value: [], from: 'default' },
             chromeWebSecurity: { value: true, from: 'default' },
             clientCertificates: { value: [], from: 'default' },
+            defaultBrowser: { value: null, from: 'default' },
             defaultCommandTimeout: { value: 4000, from: 'default' },
             downloadsFolder: { value: 'cypress/downloads', from: 'default' },
             env: {},
@@ -1152,6 +1153,7 @@ describe('config/src/project/utils', () => {
             browsers: { value: [], from: 'default' },
             chromeWebSecurity: { value: true, from: 'default' },
             clientCertificates: { value: [], from: 'default' },
+            defaultBrowser: { value: null, from: 'default' },
             defaultCommandTimeout: { value: 4000, from: 'default' },
             downloadsFolder: { value: 'cypress/downloads', from: 'default' },
             execTimeout: { value: 60000, from: 'default' },

packages/data-context/src/DataContext.ts

@@ -425,4 +425,8 @@ export class DataContext {
       this.#awaitingEmptyRequestCount.push(resolve)
     })
   }
+
+  updateModeOptionsBrowser (browser: string) {
+    (this.modeOptions as Partial<AllModeOptions>).browser = browser
+  }
 }

packages/data-context/src/actions/BrowserActions.ts

@@ -40,6 +40,11 @@ export class BrowserActions {
     })
   }
 
+  updateCliBrowser (browser: string) {
+    this.ctx.updateModeOptionsBrowser(browser)
+    this.ctx.coreData.cliBrowser = browser
+  }
+
   async focusActiveBrowserWindow () {
     await this.browserApi.focusActiveBrowserWindow()
   }

packages/data-context/src/data/ProjectLifecycleManager.ts

@@ -308,10 +308,23 @@ export class ProjectLifecycleManager {
   /**
    * Sets the initial `activeBrowser` depending on these criteria, in order of preference:
    *  1. The value of `--browser` passed via CLI.
-   *  2. The last browser selected in `open` mode (by name and channel) for this project.
-   *  3. The first browser found.
+   *  2. The value of `defaultBrowser` in `cypress.config`.
+   *  3. The last browser selected in `open` mode (by name and channel) for this project.
+   *  4. The first browser found.
    */
   async setInitialActiveBrowser () {
+    const configBrowser = this.loadedFullConfig?.defaultBrowser
+
+    // if we have a defaultBrowser from the config and a CLI browser wasn't passed and,
+    // we are in run mode or the CLI browser isn't set (prevents changing the browser in open mode when the config changes),
+    // update the cliBrowser to the defaultBrowser from the config
+    // since we want the defaultBrowser to behave as if it was passed via CLI
+    const shouldUpdateCliBrowser = (configBrowser && !this.ctx.modeOptions.isBrowserGivenByCli) &&
+      (this.ctx.isRunMode || this.ctx.coreData.cliBrowser)
+    if (shouldUpdateCliBrowser) {
+      this.ctx.actions.browser.updateCliBrowser(configBrowser)
+    }
+
     if (this.ctx.coreData.cliBrowser) {
       await this.setActiveBrowserByNameOrPath(this.ctx.coreData.cliBrowser)
 

packages/server/lib/modes/index.ts

@@ -18,6 +18,7 @@ export = (mode, options) => {
       quiet: false,
       morgan: false,
       report: true,
+      isBrowserGivenByCli: options.browser !== undefined,
     })
   }
 

packages/types/src/modeOptions.ts

@@ -24,6 +24,7 @@ export interface RunModeOptions extends CommonModeOptions {
   parallel?: boolean | null
   ciBuildId?: string | null
   tag?: (string)[] | null
+  isBrowserGivenByCli: boolean
 }
 
 export type TestingType = 'e2e' | 'component'

system-tests/__snapshots__/results_spec.ts.js

@@ -16,6 +16,7 @@ exports['module api and after:run results'] = `
     "blockHosts": null,
     "chromeWebSecurity": true,
     "clientCertificates": [],
+    "defaultBrowser": null,
     "defaultCommandTimeout": 4000,
     "downloadsFolder": "/path/to/downloadsFolder",
     "env": {},

system-tests/projects/config-defaultBrowser/cypress.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  e2e: {
+    supportFile: false,
+  },
+  defaultBrowser: 'chrome',
+}

system-tests/projects/config-defaultBrowser/cypress/e2e/spec.cy.js

@@ -0,0 +1,3 @@
+it('works', () => {
+  expect(1).to.eq(1)
+})

system-tests/test/config_spec.js

@@ -243,4 +243,17 @@ describe('e2e config', () => {
       snapshot: true,
     })
   })
+
+  it('launches browser using config.defaultBrowser', async function () {
+    await Fixtures.scaffoldProject('config-defaultBrowser')
+
+    return systemTests.exec(this, {
+      project: 'config-defaultBrowser',
+      command: 'cypress',
+      args: ['run', '--dev', '--project', path.resolve(process.cwd(), './projects/config-defaultBrowser')],
+      onStdout: (stdout) => {
+        expect(stdout).to.include('Browser:        Chrome')
+      },
+    })
+  })
 })