Implementation:Cypress io Cypress RunModule Start

Knowledge Sources	Cypress
Domains	CI_CD, Testing
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for executing Cypress tests in headless mode provided by the CLI run module and server run mode.

Description

The runModule.start function (cli/lib/exec/run.ts:L175-209) processes options via processRunOptions, then calls spawn.start to launch the server. The server-side ready function (packages/server/lib/modes/run.ts:L1040-1195) orchestrates spec iteration, browser launching, and result collection. The run entry point (L1197-1225) provides the top-level coordination.

Usage

Called when a user runs cypress run from the CLI or invokes it programmatically via the Cypress module API.

Code Reference

Source Location

• Repository: cypress-io/cypress
• Files:
  • cli/lib/exec/run.ts:L175-209 (runModule.start)
  • cli/lib/exec/spawn.ts:L286-322 (spawn.start)
  • packages/server/lib/modes/run.ts:L1040-1195 (ready)
  • packages/server/lib/modes/run.ts:L1197-1225 (run)

Signature

// CLI side
const start = async (options: any = {}): Promise<any> => {
  // Maps options via processRunOptions()
  // Calls spawn.start(args) to launch server
  // Returns exit code from spawned process
}

// Server side
async function ready(options: any): Promise<CypressRunResult> {
  // Discovers specs
  // Iterates through specs
  // Launches browser for each
  // Collects and aggregates results
}

Import

import runModule from '../exec/run'
await runModule.start(options)

I/O Contract

Inputs

Name	Type	Required	Description
options.project	string	Yes	Project directory
options.browser	string	No	Browser name (default: 'electron')
options.spec	string	No	Spec file pattern
options.headed	boolean	No	Run in headed mode
options.record	boolean	No	Record to Cypress Cloud
options.parallel	boolean	No	Enable parallelization

Outputs

Name	Type	Description
exit code	number	0 for all-pass, N for N failures
CypressRunResult	object	Aggregated test results with stats

Usage Examples

Headless CI Run

# Run all specs headlessly
npx cypress run

# Run specific spec
npx cypress run --spec "cypress/e2e/login.cy.ts"

# Run with Chrome instead of Electron
npx cypress run --browser chrome

Programmatic API

const cypress = require('cypress')

const results = await cypress.run({
  project: './my-app',
  browser: 'chrome',
  spec: 'cypress/e2e/**/*.cy.ts',
})

console.log(`Failures: ${results.totalFailed}`)
process.exit(results.totalFailed ? 1 : 0)

Related Pages

Implements Principle

• Principle:Cypress_io_Cypress_Headless_Test_Execution

Requires Environment

• Environment:Cypress_io_Cypress_Node_Runtime_Environment
• Environment:Cypress_io_Cypress_Browser_Requirements
• Environment:Cypress_io_Cypress_Linux_Display_Server

Uses Heuristic

• Heuristic:Cypress_io_Cypress_Xvfb_Display_Gotcha