5.4.0 • Published 5d ago

cypress-interceptor

Licence

MIT

Version

5.4.0

Deps

Size

310 kB

Vulns

Weekly

Summary Dependency Versions

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
Delay requests before send		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: the request hits the back-end, then the response is
// held for 5 seconds before it returns to your code
cy.throttleInterceptorRequest("**/api/users", 5000); // 5 second delay

5. Delay a request before it is sent

// Hold the request for 5 seconds BEFORE it reaches the back-end
cy.delayInterceptorRequest("**/api/users", 5000); // 5 second delay

Delay vs. Throttle

A request has three phases. delayInterceptorRequest waits before the back-end is hit, throttleInterceptorRequest waits after:

  1. request starts          2. request hits               3. request done
     (your code)               the back-end              (back to your code)
         │                          │                             │
         │ <-- delayInterceptor --> │ <-- throttleInterceptor --> │
         │         Request          │          Request            │

6. 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.

7. Count requests

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

8. Get the last request

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

9. 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
  });
});

10. 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
  }
);

11. 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);
});

12. 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");
  });
});

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+