Cypress Interceptor - Quick Start Guide

For Cypress developers who want better request handling and debugging.

What is it?

Cypress Interceptor replaces cy.intercept with a more powerful alternative that logs all network requests, provides detailed statistics, and makes debugging test failures easier.

Why use it instead of cy.intercept?

| Feature | cy.intercept | Cypress Interceptor | |---------|-------------|-------------------| | Log all requests | ⚠️ Complex | ✅ Built-in | | Request statistics | ⚠️ Complex | ✅ Built-in | | Timing data | ⚠️ Complex | ✅ Built-in | | Throttle requests | ⚠️ Complex | ✅ Built-in | | Wait for requests reliably | ⚠️ Flaky | ✅ Stable | | Mock responses | ✅ | ✅ | | Export logs on failure | ❌ | ✅ | | WebSocket support | ❌ | ✅ Optional | | Console monitoring | ❌ | ✅ Optional |

Installation

npm install cypress-interceptor

Add to cypress/support/e2e.ts:

import "cypress-interceptor";

Common Use Cases

1. Wait for a request reliably

// Instead of guessing with cy.intercept, wait for the actual request
cy.waitUntilRequestIsDone(
  () => cy.get("button").click(),
  "**/api/users"
);

2. Get request statistics

cy.interceptorStats("**/api/users").then((stats) => {
  expect(stats[0].response?.statusCode).to.eq(200);
  expect(stats[0].duration).to.be.lt(1000); // took less than 1 second
  expect(stats[0].request.body).to.deep.eq({ id: 5 });
});

3. Mock a response

// Mock the first matching request
cy.mockInterceptorResponse(
  "**/api/users",
  { body: { name: "John" }, statusCode: 200 }
);

// Mock indefinitely
cy.mockInterceptorResponse(
  { method: "POST" },
  { statusCode: 400 },
  { times: Number.POSITIVE_INFINITY }
);

4. Throttle a request

// Simulate slow network
cy.throttleInterceptorRequest("**/api/users", 5000); // 5 second delay

5. Log all requests on test failure

afterEach(() => {
  cy.writeInterceptorStatsToLog("./cypress/logs");
});

This creates a JSON file with all requests, responses, timing, and headers—perfect for debugging why tests fail.

6. Count requests

cy.interceptorRequestCalls("**/api/users").should("eq", 1);

7. Get the last request

cy.interceptorLastRequest("**/api/users").then((request) => {
  expect(request?.response?.body).to.include({ status: "active" });
});

8. Verify request performance

// Ensure API calls complete within SLA
cy.interceptorStats("**/api/data").then((stats) => {
  stats.forEach((call) => {
    expect(call.duration).to.be.lt(2000); // Must complete in 2 seconds
  });
});

9. Mock dynamic responses based on request

// Generate response based on what was requested
cy.mockInterceptorResponse(
  "**/api/users",
  {
    generateBody: (request, getJsonRequestBody) => {
      const body = getJsonRequestBody();
      return { id: body.id, name: "User " + body.id };
    },
    statusCode: 200
  }
);

10. Monitor WebSocket connections

import "cypress-interceptor/websocket";

// Wait for WebSocket action
cy.waitUntilWebsocketAction({ url: "**/socket" });

// Get WebSocket stats
cy.wsInterceptorStats({ url: "**/socket" }).then((stats) => {
  expect(stats.length).to.be.greaterThan(0);
});

11. Monitor console errors

import "cypress-interceptor/console";

// Capture console logs and errors
cy.watchTheConsole().then((console) => {
  expect(console.error).to.have.length(0);
  expect(console.jsError).to.have.length(0);
  expect(console.log).to.have.length.greaterThan(0);
});

// Export console logs on failure
afterEach(() => {
  cy.writeConsoleLogToFile("./cypress/logs");
});

Advanced: Filter requests

// Only GET requests
cy.interceptorStats({ method: "GET" });

// Only fetch (not XHR)
cy.interceptorStats({ resourceType: "fetch" });

// Custom matcher
cy.interceptorStats({
  queryMatcher: (query) => query?.page === 5
});

// Body matcher
cy.interceptorStats({
  bodyMatcher: (body) => body.includes("userId")
});

Why it's powerful

Complete visibility - Every HTTP request, response, and timing is logged automatically. No more wondering if a request was made or what it contained.

Performance tracking - Get exact timing data for each request. Identify slow endpoints and catch performance regressions before production.

WebSocket support - Monitor real-time connections alongside HTTP requests with the same reliability.

Console monitoring - Capture console errors and warnings. Export them with network logs for complete debugging context.

Reliable waits - waitUntilRequestIsDone actually waits for completion, not just interception. Eliminates flaky tests.

Export on failure - Automatically save all network activity and console logs when tests fail. Perfect for CI/CD debugging.

Real-world example

describe("User Dashboard", () => {
  beforeEach(() => {
    cy.visit("/dashboard");
  });

  it("should load user data and display it", () => {
    // Reset watch to ignore initial page load requests
    cy.resetInterceptorWatch();

    // Click button and wait for the specific request
    cy.waitUntilRequestIsDone(
      () => cy.get("button#refresh").click(),
      "**/api/user/profile"
    );

    // Verify the request was made correctly
    cy.interceptorStats("**/api/user/profile").then((stats) => {
      expect(stats[0].request.method).to.eq("GET");
      expect(stats[0].duration).to.be.lt(2000);
      expect(stats[0].response?.statusCode).to.eq(200);
    });

    // Verify UI updated
    cy.contains("Welcome, John").should("be.visible");
  });

  it("should handle API errors gracefully", () => {
    // Mock an error response
    cy.mockInterceptorResponse(
      "**/api/user/profile",
      { statusCode: 500, body: { error: "Server error" } }
    );

    cy.get("button#refresh").click();
    cy.contains("Error loading profile").should("be.visible");
  });
});

Key Benefits

✅ Reliable waits - No more flaky tests waiting for requests
✅ Complete visibility - See every request, response, and timing
✅ Easy debugging - Export logs on failure to analyze what went wrong
✅ Better mocking - Mock responses with full control
✅ Performance insights - Track request duration and identify slow endpoints
✅ WebSocket & console monitoring - Full application visibility
✅ Tested thoroughly - 100+ tests, works with Cypress 13+

Documentation

• Full API Reference
• Network Report Generation

Need help?

Check the full README for advanced features like WebSocket interception, console monitoring, and HTML report generation.