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

> Master Cypress integration tests for your monorepo. Learn to validate your stack using real browsers and detailed guides in this comprehensive Cypress tutorial.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: how-to-guide
- Published: 2026-06-18

---

**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](https://github.com/cypress-io/cypress/blob/develop/packages/server/README.md), 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`](https://github.com/cypress-io/cypress/blob/main/.cy.js), [`.cy.ts`](https://github.com/cypress-io/cypress/blob/main/.cy.ts), [`.spec.js`](https://github.com/cypress-io/cypress/blob/main/.spec.js), or [`.spec.ts`](https://github.com/cypress-io/cypress/blob/main/.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`](https://github.com/cypress-io/cypress/blob/main/packages/server/test/integration/cli_spec.js) that validates CLI behavior:

```js
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`](https://github.com/cypress-io/cypress/blob/main/packages/driver/cypress/e2e/webkit.cy.ts) demonstrates testing browser-specific behavior:

```ts
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:

```js
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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/.cy.js), [`.cy.ts`](https://github.com/cypress-io/cypress/blob/main/.cy.ts), [`.spec.js`](https://github.com/cypress-io/cypress/blob/main/.spec.js), or [`.spec.ts`](https://github.com/cypress-io/cypress/blob/main/.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`](https://github.com/cypress-io/cypress/blob/main/.cy.js), [`.cy.ts`](https://github.com/cypress-io/cypress/blob/main/.cy.ts), [`.spec.js`](https://github.com/cypress-io/cypress/blob/main/.spec.js), and [`.spec.ts`](https://github.com/cypress-io/cypress/blob/main/.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`](https://github.com/cypress-io/cypress/blob/main/packages/driver/cypress/e2e/webkit.cy.ts). Use the [`.cy.ts`](https://github.com/cypress-io/cypress/blob/main/.cy.ts) or [`.spec.ts`](https://github.com/cypress-io/cypress/blob/main/.spec.ts) extension for TypeScript tests.