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

``bash
npm install cypress-interceptor
`

Add to cypress/support/e2e.ts:

`typescript
import "cypress-interceptor";
`

Common Use Cases

$3

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

$3

`typescript
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

`typescript
// 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 }
);
`

$3

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

$3

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

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

$3

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

$3

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

$3

`typescript
// 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
});
});
`

$3

`typescript
// 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
}
);
`

$3

`typescript
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);
});
`

$3

`typescript
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

`typescript
// 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

`typescript
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.