Implementation:Cypress io Cypress ProcessRunOptions

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

Overview

Concrete tool for mapping CLI options and environment variables to server arguments for headless test execution provided by the CLI run module.

Description

The processRunOptions function (cli/lib/exec/run.ts) takes an options object from the CLI parser and maps it to a string array of server arguments. It validates the project path, handles the CYPRESS_RECORD_KEY / CYPRESS_CI_KEY environment variables (L100-101), and maps boolean flags to their server argument equivalents.

Usage

Called internally by runModule.start before spawning the Cypress server process in headless mode.

Code Reference

Source Location

• Repository: cypress-io/cypress
• File: cli/lib/exec/run.ts
• Lines: L38-169

Signature

const processRunOptions = (options: any = {}): string[] => {
  // Validates project path
  // Maps CLI options to server argument array
  // Handles env vars: CYPRESS_RECORD_KEY, CYPRESS_CI_KEY
  // Returns: string[] of CLI arguments for server process
}

Import

// Internal module
import run from '../exec/run'
// Used via: run.processRunOptions(options)

I/O Contract

Inputs

Name	Type	Required	Description
options.project	string	Yes	Project directory path
options.record	boolean	No	Enable recording to Cypress Cloud
options.key	string	No	Record key (or via CYPRESS_RECORD_KEY)
options.parallel	boolean	No	Enable parallel spec distribution
options.group	string	No	Group name for parallel runs
options.ciBuildId	string	No	Unique CI build identifier
options.browser	string	No	Browser to use
options.spec	string	No	Specific spec files to run

Outputs

Name	Type	Description
args	string[]	Array of CLI arguments for the server process

Usage Examples

CI Pipeline Usage

# Basic headless run
npx cypress run

# Record to Cypress Cloud with parallelization
npx cypress run --record --key $CYPRESS_RECORD_KEY --parallel --ci-build-id $BUILD_ID

# Run specific specs with grouping
npx cypress run --record --parallel --group "smoke" --spec "cypress/e2e/smoke/**"

Related Pages

Implements Principle

• Principle:Cypress_io_Cypress_CI_Environment_Configuration

Requires Environment

• Environment:Cypress_io_Cypress_Node_Runtime_Environment