Programmatic Test Execution

/**
 * Execute a headless Cypress test run
 * @param options - Configuration options for the test run
 * @returns Promise resolving to test results or failure information
 */
function run(options?: Partial<CypressRunOptions>): Promise<CypressRunResult | CypressFailedRunResult>;

interface CypressRunOptions {
  /** Specify browser to run tests in, either by name or by filesystem path */
  browser: string;
  /** Specify a unique identifier for a run to enable grouping or parallelization */
  ciBuildId: string;
  /** Group recorded tests together under a single run name */
  group: string;
  /** Tag string for the recorded run, like "production,nightly" */
  tag: string;
  /** Display the browser instead of running headlessly */
  headed: boolean;
  /** Hide the browser instead of running headed */
  headless: boolean;
  /** Specify your secret Record Key */
  key: string;
  /** Keep Cypress open after all tests run */
  noExit: boolean;
  /** Run recorded specs in parallel across multiple machines */
  parallel: boolean;
  /** Override default port */
  port: number;
  /** Run quietly, using only the configured reporter */
  quiet: boolean;
  /** Whether to record the test run */
  record: boolean;
  /** Specify a mocha reporter */
  reporter: string;
  /** Specify mocha reporter options */
  reporterOptions: any;
  /** Specify the specs to run */
  spec: string;
  /** Specify the number of failures to cancel a run being recorded to the Cloud or false to disable auto-cancellation */
  autoCancelAfterFailures: number | false;
  /** Whether to display the Cypress Runner UI */
  runnerUi: boolean;
  /** Specify configuration */
  config: ConfigOptions;
  /** Path to the config file to be used */
  configFile: string;
  /** Specify environment variables */
  env: object;
  /** Path to a specific project */
  project: string;
  /** Specify the type of tests to execute */
  testingType: 'e2e' | 'component';
}

const cypress = require('cypress');

// Basic headless test run
const results = await cypress.run();

// Run specific specs with custom browser
const results = await cypress.run({
  spec: 'cypress/e2e/login/*.cy.js',
  browser: 'chrome',
  headed: false
});

// Run with environment variables and custom config
const results = await cypress.run({
  env: {
    username: 'testuser',
    password: 'testpass'
  },
  config: {
    baseUrl: 'http://localhost:3000',
    defaultCommandTimeout: 10000
  },
  reporter: 'junit',
  reporterOptions: {
    mochaFile: 'results/test-results.xml'
  }
});

// Handle results
if (results.status === 'failed') {
  console.error(`Tests failed with ${results.failures} failures`);
  console.error(results.message);
  process.exit(results.failures);
} else {
  console.log(`Tests completed: ${results.totalPassed} passed, ${results.totalFailed} failed`);
}

interface CypressRunResult {
  /** Browser used for the test run */
  browserName: string;
  /** Path to the browser executable */
  browserPath: string;
  /** Version of the browser used */
  browserVersion: string;
  /** Cypress configuration used during the run */
  config: PublicConfig;
  /** Version of Cypress used */
  cypressVersion: string;
  /** ISO timestamp when tests ended */
  endedTestsAt: string;
  /** Operating system name */
  osName: string;
  /** Operating system version */
  osVersion: string;
  /** Array of individual spec run results */
  runs: RunResult[];
  /** Full URL if Cypress test run was recorded to the Cloud */
  runUrl?: string;
  /** ISO timestamp when tests started */
  startedTestsAt: string;
  /** Total duration of all tests in milliseconds */
  totalDuration: number;
  /** Total number of failed tests */
  totalFailed: number;
  /** Total number of passed tests */
  totalPassed: number;
  /** Total number of pending tests */
  totalPending: number;
  /** Total number of skipped tests */
  totalSkipped: number;
  /** Total number of test suites */
  totalSuites: number;
  /** Total number of tests */
  totalTests: number;
}

interface CypressFailedRunResult {
  /** Indicates the run failed to execute */
  status: 'failed';
  /** Number of failures that prevented execution */
  failures: number;
  /** Error message describing why the run failed */
  message: string;
}

interface RunResult {
  /** Error message if the spec failed to run */
  error: string | null;
  /** Reporter name used for this spec */
  reporter: string;
  /** Reporter-specific statistics (varies by reporter) */
  reporterStats: object;
  /** Screenshots taken during this spec run */
  screenshots: ScreenshotInformation[];
  /** Accurate test results collected by Cypress */
  stats: TestStats;
  /** Information about the spec test file */
  spec: SpecResult;
  /** Individual test results */
  tests: TestResult[];
  /** Path to recorded video file, if enabled */
  video: string | null;
}

interface TestStats {
  /** Duration of the spec run in milliseconds */
  duration?: number;
  /** ISO timestamp when spec ended */
  endedAt: string;
  /** Number of failed tests */
  failures: number;
  /** Number of passed tests */
  passes: number;
  /** Number of pending tests */
  pending: number;
  /** Number of skipped tests */
  skipped: number;
  /** ISO timestamp when spec started */
  startedAt: string;
  /** Number of test suites */
  suites: number;
  /** Total number of tests */
  tests: number;
}

interface TestResult {
  /** Duration of the test in milliseconds */
  duration: number;
  /** Array of suite and test names forming the full test title */
  title: string[];
  /** Test state: 'passed', 'failed', 'pending', 'skipped' */
  state: string;
  /** Error message as presented in console if the test fails */
  displayError: string | null;
  /** Array of test attempt results (for retries) */
  attempts: AttemptResult[];
}

interface AttemptResult {
  /** State of this attempt: 'passed', 'failed', 'pending', 'skipped' */
  state: string;
}

interface ScreenshotInformation {
  /** Screenshot filename */
  name: string;
  /** ISO timestamp when screenshot was taken */
  takenAt: string;
  /** Absolute path to the saved image */
  path: string;
  /** Image height in pixels */
  height: number;
  /** Image width in pixels */
  width: number;
}

interface SpecResult {
  /** Resolved absolute path to the spec file */
  absolute: string;
  /** File extension like ".js" or ".ts" */
  fileExtension: string;
  /** File name without extension */
  fileName: string;
  /** Full filename including extension */
  name: string;
  /** Path relative to the project root */
  relative: string;
}

// Parallel test execution with recording
const results = await cypress.run({
  record: true,
  key: 'your-record-key',
  parallel: true,
  ciBuildId: process.env.CI_BUILD_ID,
  group: 'production-tests',
  tag: 'nightly,regression'
});

// Custom reporter with detailed options
const results = await cypress.run({
  reporter: 'mochawesome',
  reporterOptions: {
    reportDir: 'cypress/reports',
    overwrite: false,
    html: false,
    json: true
  }
});

// Process detailed results
if (results.status !== 'failed') {
  results.runs.forEach((run, index) => {
    console.log(`Spec ${index + 1}: ${run.spec.relative}`);
    console.log(`  Tests: ${run.stats.tests}, Passed: ${run.stats.passes}, Failed: ${run.stats.failures}`);
    
    if (run.video) {
      console.log(`  Video: ${run.video}`);
    }
    
    if (run.screenshots.length > 0) {
      console.log(`  Screenshots: ${run.screenshots.length}`);
      run.screenshots.forEach(screenshot => {
        console.log(`    ${screenshot.name} (${screenshot.width}x${screenshot.height})`);
      });
    }
  });
}