Implementation:Cypress io Cypress Detect Browsers

Knowledge Sources	Cypress
Domains	Browser_Automation, Cross_Platform
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for detecting installed browsers across macOS, Linux, and Windows provided by the @packages/launcher module.

Description

The detect function iterates through knownBrowsers (defined in known-browsers.ts) and uses platform-specific helpers to check if each browser is installed. For each found browser, it extracts the version string, parses the major version, and returns a FoundBrowser object. The detectByPath function handles custom browser paths specified via --browser /path/to/browser.

Usage

Called during Cypress startup to populate the browser selection list, and when the user specifies a custom browser.

Code Reference

Source Location

Repository: cypress-io/cypress
Files:
- packages/launcher/lib/detect.ts:L148-165 (detect)
- packages/launcher/lib/detect.ts:L167-238 (detectByPath)
- packages/launcher/lib/known-browsers.ts:L23-143 (knownBrowsers)
- packages/launcher/lib/browsers.ts:L9-50 (launch)

Signature

export const detect = (
  goalBrowsers?: Browser[]
): Bluebird<FoundBrowser[]>

export const detectByPath = (
  path: string,
  goalBrowsers?: Browser[]
): Promise<FoundBrowser>

export const launch = (
  browser: FoundBrowser,
  url: string,
  debuggingPort: number,
  args?: string[],
  browserEnv?: Record<string, string>
): cp.ChildProcess

Import

import { detect, detectByPath } from '@packages/launcher'
import { launch } from '@packages/launcher/lib/browsers'

I/O Contract

Inputs

Name	Type	Required	Description
goalBrowsers	Browser[]	No	Browsers to detect (defaults to knownBrowsers)
path	string	Yes (detectByPath)	Custom browser executable path

Outputs

Name	Type	Description
FoundBrowser[]	Array	List of detected browsers with name, version, path, family
FoundBrowser	object	Single browser detected by custom path

Usage Examples

Detecting All Browsers

import { detect } from '@packages/launcher'

const browsers = await detect()
browsers.forEach((b) => {
  console.log(`${b.displayName} ${b.version} (${b.family}) at ${b.path}`)
})
// Chrome 120.0.6099.129 (chromium) at /usr/bin/google-chrome
// Firefox 121.0 (firefox) at /usr/bin/firefox

Detecting by Path

import { detectByPath } from '@packages/launcher'

const browser = await detectByPath('/usr/bin/brave-browser')
console.log(browser.displayName) // "Custom Brave"

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment