Implementation:Cypress io Cypress System Test Runner

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

Overview

Concrete tool for running system-level integration tests against the Cypress binary provided by the system-tests package.

Description

The system test runner (system-tests/scripts/run.js:L1-187) uses Mocha 7.1.0 to execute system tests. It spawns Mocha with configurable glob patterns, handles xvfb for headless Linux execution, and supports spec filtering. Tests in system-tests/test/ validate core functionality while system-tests/test-binary/ validates binary-specific behavior.

Usage

Run during CI to validate releases, or locally to test specific features.

Code Reference

Source Location

• Repository: cypress-io/cypress
• Files:
  • system-tests/scripts/run.js:L1-187 (test runner)
  • system-tests/package.json:L15 (test script)

Signature

// system-tests/scripts/run.js
// Spawns mocha with:
//   --glob-in-dir: test directory glob pattern
//   --spec: specific test file
//   --xvfb: Linux headless display
// system-tests/package.json scripts:
//   "test": "node ./scripts/run.js --glob-in-dir=\"{test,test-binary}\""
//   "test:ci": "node ./scripts/run.js --glob-in-dir=\"{test,test-binary}\""

Import

# CLI usage
cd system-tests
node ./scripts/run.js --glob-in-dir="{test,test-binary}"

I/O Contract

Inputs

Name	Type	Required	Description
--glob-in-dir	string	Yes	Directory glob for test files
--spec	string	No	Specific test file to run
CYPRESS_ENV	env vars	No	Environment configuration for tests

Outputs

Name	Type	Description
exit code	number	0=pass, 1=fail
Mocha output	stdout	Test results with pass/fail counts

Usage Examples

Running System Tests

# Run all system tests
cd system-tests && yarn test

# Run specific test
node ./scripts/run.js --spec test/e2e/commands/actions_spec.js

# Run binary tests only
node ./scripts/run.js --glob-in-dir="test-binary"

Related Pages

Implements Principle

• Principle:Cypress_io_Cypress_System_Test_Validation