Implementation:Cypress io Cypress CreateInstance

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

Overview

Concrete wrapper for the Cypress Cloud API spec distribution endpoint used during parallel CI execution provided by the server record module.

Description

The createInstance function (packages/server/lib/modes/record.ts:L521-547) communicates with the Cypress Cloud API to claim the next spec to execute. It sends the machine identifier and current state, and receives the next spec to run along with metadata about total/claimed instances. The iterateThroughSpecs function in run.ts calls this in a loop until no more specs are available.

Usage

Called internally during cypress run --record --parallel to claim specs from the Cloud API. Not directly invoked by users.

Code Reference

Source Location

• Repository: cypress-io/cypress
• Files:
  • packages/server/lib/modes/record.ts:L521-547 (createInstance)
  • packages/server/lib/modes/run.ts:L58-106 (iterateThroughSpecs)

Signature

async function createInstance(options: InstanceOptions): Promise<{
  spec: string | null
  claimedInstances: number
  totalInstances: number
  estimated: number
  instanceId: string
}>

Import

// Internal server module - not directly importable
// Called via recordMode.createRunAndRecordSpecs()

I/O Contract

Inputs

Name	Type	Required	Description
options.parallel	boolean	Yes	Must be true for parallelization
options.ciBuildId	string	Yes	Unique CI build identifier
options.group	string	No	Group name for the run
machineId	string	Yes	Unique machine/container identifier

Outputs

Name	Type	Description
spec	string or null	Next spec to run (null when all claimed)
claimedInstances	number	Number of specs claimed so far
totalInstances	number	Total specs in the run
instanceId	string	Unique ID for this spec execution

Usage Examples

Parallel CI Configuration

# Run with parallelization across CI containers
npx cypress run \
  --record \
  --key $CYPRESS_RECORD_KEY \
  --parallel \
  --ci-build-id $CIRCLE_WORKFLOW_ID \
  --group "e2e"

Related Pages

Implements Principle

• Principle:Cypress_io_Cypress_CI_Parallelization