How to Write Cypress Integration Tests: A Complete Guide for the Cypress Monorepo

Cypress integration tests validate the driver and server stack by running tests in a real browser against a minimal fixture app, using files placed in packages/server/test/integration or packages/driver/cypress/e2e and executed via yarn test-integration.

Writing Cypress integration tests is essential for validating the framework's public API and server-side plumbing. In the cypress-io/cypress monorepo, these tests exercise the driver and server packages directly without requiring a full binary build. This guide explains how to write Cypress integration tests using the actual source code structure and testing patterns employed by the Cypress team.

Understanding the Integration Test Architecture

The Cypress monorepo organizes its testing infrastructure into distinct layers that integration tests target.

The Server Package (@packages/server)

Located in packages/server/test/integration, these tests validate the Node.js HTTP server that handles browser launch, socket communication, and test orchestration. According to the Server README, this is where you test the server-side plumbing including proxy behavior and network stubbing.

The Driver Package (@packages/driver)

The driver integration tests live in packages/driver/cypress/e2e and exercise the JavaScript library injected into the browser. These tests verify the cy API implementation, Mocha integration, and command queue functionality.

System Tests vs Integration Tests

While integration tests run against the driver and server directly, system-tests (located in system-tests/) spin up a full Cypress binary and launch a browser to verify the entire stack. Integration tests provide faster feedback during development since they don't require building the full binary.

Writing Cypress Integration Tests

To add a new integration test to the Cypress monorepo:

1. Create a test file ending in .cy.js, .cy.ts, .spec.js, or .spec.ts in the appropriate directory.
2. For server functionality, use packages/server/test/integration/.
3. For driver API testing, use packages/driver/cypress/e2e/.

Server Integration Test Example

Here's an example from packages/server/test/integration/cli_spec.js that validates CLI behavior:

describe('Cypress CLI', () => {
  before(() => {
    cy.exec('yarn cypress:run --spec cypress/e2e/basic.cy.js')
  })

  it('should start without errors', () => {
    cy.readFile('cypress/results.json').should('contain', '"total":1')
  })
})

Driver Integration Test Example

The following example from packages/driver/cypress/e2e/webkit.cy.ts demonstrates testing browser-specific behavior:

describe('WebKit support', () => {
  it('loads a page and finds an element', () => {
    cy.visit('https://example.com')
    cy.get('h1').should('contain.text', 'Example Domain')
  })
})

User Project Example

For contributors writing tests in their own projects, the pattern remains consistent:

describe('Todo app', () => {
  beforeEach(() => {
    cy.request('POST', '/reset')
    cy.visit('/')
  })

  it('adds a new item', () => {
    cy.get('[data-test=new-item]').type('Buy milk{enter}')
    cy.get('[data-test=item]').should('contain.text', 'Buy milk')
  })
})

Running Cypress Integration Tests

Execute the integration test suite using the npm scripts defined in CONTRIBUTING.md:

• From the repository root: yarn test-integration
• For package-specific testing: yarn workspace @packages/server test-integration

These commands launch the test runner against the minimal fixture apps, providing immediate feedback on changes to the driver or server code.

Key Cypress Commands for Integration Testing

When writing Cypress integration tests, you have access to the full public API:

• cy.visit() – Loads the fixture application in the browser
• cy.get() – Queries DOM elements for assertions
• cy.intercept() – Stubs and validates network requests
• cy.exec() – Runs shell commands in the Node process
• cy.readFile() – Validates generated output files

Why Integration Tests Matter

Cypress integration tests serve three critical functions:

• They exercise the public API (cy.*), ensuring command implementations remain stable across versions.
• They validate server-side plumbing including the proxy, network stubbing, and rewriter modules imported by the test runner.
• They run faster than system-tests, giving developers rapid feedback during the development cycle.

Summary

• Place server integration tests in packages/server/test/integration and driver tests in packages/driver/cypress/e2e.
• Use file extensions .cy.js, .cy.ts, .spec.js, or .spec.ts for test files.
• Run tests with yarn test-integration from the root or specific package workspaces.
• Leverage the full cy.* API including cy.visit, cy.get, and cy.intercept to validate behavior.
• Integration tests exercise the driver and server stack without requiring a full binary build, unlike system-tests in system-tests/.

Frequently Asked Questions

Where should I place new Cypress integration tests in the monorepo?

Place tests for server functionality in packages/server/test/integration/ and tests for driver API behavior in packages/driver/cypress/e2e/. Both locations support .cy.js, .cy.ts, .spec.js, and .spec.ts extensions.

How do I run only the integration tests without building the full Cypress binary?

Use the command yarn test-integration from the repository root, or yarn workspace @packages/server test-integration to run package-specific integration tests. These commands execute tests against the driver and server directly without the overhead of system-tests.

What is the difference between integration tests and system-tests in Cypress?

Integration tests run in the driver and server packages directly, validating the cy API and server-side plumbing quickly. System-tests, located in system-tests/, spin up the full Cypress binary and browser to validate the complete stack, making them slower but more comprehensive.

Can I use TypeScript for writing Cypress integration tests?

Yes. The Cypress monorepo supports TypeScript test files as demonstrated by packages/driver/cypress/e2e/webkit.cy.ts. Use the .cy.ts or .spec.ts extension for TypeScript tests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}