End-to-End Testing with Cypress That Doesn't Break Every Sprint

The Problem With Most Cypress Setups

Most teams start Cypress the same way: write a test, it passes, ship it. Three sprints later, the designer changes a button label and five tests turn red. Someone runs cy.contains('Submit') everywhere. Someone else hardcodes URLs. The suite hasn't been green in two weeks and the team starts skipping it.

This is not a Cypress problem. It's a structural problem. Here's how we built a Cypress suite that's been running in CI for 18 months with a < 2% flake rate.

The Selector Strategy: Data Attributes Over Everything

The single most important decision in your Cypress setup is how you select elements. Text selectors break when copy changes. CSS class selectors break when you refactor styling. Role selectors are better but can be ambiguous with multiple identical roles.

We use data-testid attributes exclusively for test selectors:

// In your component
function SubmitButton({ onClick, label }: Props) {
  return (
    <button
      onClick={onClick}
      data-testid="form-submit-button"
      className="..."
    >
      {label}
    </button>
  );
}

// In your test
cy.get('[data-testid="form-submit-button"]').click();

The label can change. The design can change. The component can be refactored. The data-testid only changes when the test intentionally changes. This contract is explicit and survives CSS-in-JS migrations, design system overhauls, and copy rewrites.

Encapsulate Selectors in a Custom Command

Never repeat cy.get('[data-testid="..."]') directly in tests. Wrap it:

// cypress/support/commands.ts
Cypress.Commands.add('getByTestId', (testId: string) => {
  return cy.get(`[data-testid="${testId}"]`);
});
 
// Type declaration
declare global {
  namespace Cypress {
    interface Chainable {
      getByTestId(testId: string): Chainable<JQuery<HTMLElement>>;
    }
  }
}

// In tests
cy.getByTestId('form-submit-button').click();
cy.getByTestId('campaign-list').should('contain', 'Q1 Europe');

Now if you ever rename the attribute convention, the fix is in one place.

Page Object Model, But Leaner

Full Page Object Models can be over-engineered for most Cypress setups. We use a light Page Object pattern: one file per feature area with commands that encapsulate complex interactions:

// cypress/pages/lead-form.ts
export const LeadForm = {
  visit: () => cy.visit('/campaigns/new'),
 
  fillName: (name: string) =>
    cy.getByTestId('lead-name-input').type(name),
 
  fillEmail: (email: string) =>
    cy.getByTestId('lead-email-input').type(email),
 
  selectStatus: (status: string) => {
    cy.getByTestId('lead-status-select').click();
    cy.getByTestId(`status-option-${status}`).click();
  },
 
  submit: () => cy.getByTestId('form-submit-button').click(),
 
  expectSuccess: () =>
    cy.getByTestId('success-toast').should('be.visible'),
 
  expectError: (message: string) =>
    cy.getByTestId('error-message').should('contain', message),
};

// In the test
import { LeadForm } from '../pages/lead-form';
 
it('creates a new lead', () => {
  LeadForm.visit();
  LeadForm.fillName('Maria Schmidt');
  LeadForm.fillEmail('maria@example.de');
  LeadForm.selectStatus('new');
  LeadForm.submit();
  LeadForm.expectSuccess();
});

Tests read like specifications. When a flow changes, you update the Page Object once.

Handling Async Third-Party Dependencies

The most common source of flakiness: third-party scripts (analytics, chat widgets, cookie banners) that race with your tests.

Option 1: Block external requests in Cypress

// cypress.config.ts
export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser, launchOptions) => {
        // Block analytics and tracking scripts
      });
    },
  },
});

// In support/e2e.ts — intercept and stub third parties
beforeEach(() => {
  cy.intercept('GET', '**/analytics.js', { statusCode: 204, body: '' }).as('analytics');
  cy.intercept('POST', '**/collect', { statusCode: 204, body: '' }).as('tracking');
});

Option 2: Wait for app-ready signal

A more reliable pattern: have your app emit a custom event or set a global flag when it's fully initialised, including after third-party scripts:

// In your app's root component
useEffect(() => {
  if (typeof window !== 'undefined') {
    window.dispatchEvent(new CustomEvent('app:ready'));
  }
}, []);

// In Cypress
cy.window().should('have.property', 'appReady', true);
// or
cy.window().then(win => {
  return new Cypress.Promise(resolve => {
    win.addEventListener('app:ready', resolve, { once: true });
  });
});

CI Integration Patterns

Parallel execution. A 200-test Cypress suite running sequentially takes 15–20 minutes. Running in parallel across 4 containers takes 4–5 minutes. Most CI platforms support this natively:

# GitHub Actions
strategy:
  matrix:
    containers: [1, 2, 3, 4]
steps:
  - uses: cypress-io/github-action@v6
    with:
      record: true
      parallel: true
      group: 'E2E Tests'
    env:
      CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}

Retry on failure. Set retries in cypress.config.ts to handle transient infrastructure failures without manual re-runs:

export default defineConfig({
  e2e: {
    retries: {
      runMode: 2,   // Retry twice in CI
      openMode: 0,  // No retries in local development
    },
  },
});

Smoke test tag. Not all tests need to run on every PR. Tag critical paths:

it('processes a lead submission', { tags: '@smoke' }, () => {
  // ...
});

Run cypress run --env grepTags=@smoke on PR pipelines and the full suite on main.

State Management Between Tests

The rule: each test must set up its own state and clean up after itself. Tests that depend on execution order are fragile.

For authenticated flows, don't log in through the UI in every test. It's slow and breaks when the login UI changes. Bypass the UI with a programmatic login:

// cypress/support/commands.ts
Cypress.Commands.add('loginAsEditor', () => {
  cy.request({
    method: 'POST',
    url: '/api/auth/login',
    body: {
      email: Cypress.env('EDITOR_EMAIL'),
      password: Cypress.env('EDITOR_PASSWORD'),
    },
  }).then(({ body }) => {
    window.localStorage.setItem('auth_token', body.token);
  });
});

beforeEach(() => {
  cy.loginAsEditor();
  cy.visit('/dashboard');
});

This approach reduced our login-dependent test time by 60%.

Keeping the Suite Fast

A slow test suite is an ignored test suite. Some rules we enforce:

Set viewport explicitly. cy.viewport(1280, 720) at the top of each file. Inconsistent viewports cause random layout-dependent failures.

Use cy.intercept for slow API calls. If a test only needs to verify UI behavior, stub the API:

cy.intercept('GET', '/api/campaigns', { fixture: 'campaigns.json' }).as('getCampaigns');
cy.visit('/campaigns');
cy.wait('@getCampaigns');
cy.getByTestId('campaign-list').should('have.length', 3);

This makes the test deterministic and fast. Reserve real API calls for integration-style tests that explicitly test the API contract.

Assert what you need, nothing more. Don't take screenshots of whole pages or assert on computed CSS unless the test is specifically about visual regression. Every extra assertion is latency.

What We Learned the Hard Way

Flakiness is a signal, not a problem to suppress. When a test is flaky, investigate the root cause. We caught two real race conditions in our frontend code by refusing to just add cy.wait(1000) and moving on.

Write tests when you write features, not after. Tests written after the fact test what the code does. Tests written alongside features test what the code should do. The distinction matters when you refactor.

Record videos in CI only when tests fail. Storing video for every run is expensive and slow. Configure this in cypress.config.ts:

export default defineConfig({
  e2e: {
    video: true,
    videoCompression: 32,
    screenshotOnRunFailure: true,
  },
});

The Suite That Keeps Running

Eighteen months, 240 tests, < 2% flake rate. The patterns that made the difference:

1. data-testid selectors, never text or CSS
2. Light Page Objects for every feature area
3. Stubbed third-party scripts and analytics
4. Programmatic authentication, not UI login
5. Parallel execution in CI from the start
6. Retries for transient failures, investigations for consistent ones

E2E tests are expensive to write and maintain. That investment only pays off if the suite stays green and the team trusts it. Structure for that trust from day one.