---
title: "Introducing cy.intercept - Next Generation Network Stubbing in Cypress 6.0"
url: "https://www.cypress.io/blog/introducing-cy-intercept-next-generation-network-stubbing-in-cypress-6-0"
description: "Today, we're elevating the power and scope of Cypress' network handling capabilities with the introduction of the cy.intercept command in Cypress 6.0."
---

# Introducing cy.intercept - Next Generation Network Stubbing in Cypress 6.0

November 24, 2020

By The Cypress Team

Today, we're elevating the power and scope of Cypress' network handling capabilities with the introduction of the `[cy.intercept](https://on.cypress.io/intercept?ref=cypress-io.ghost.io)` command in [Cypress 6.0](http://on.cypress.io/changelog?ref=cypress-io.ghost.io#6-0-0).

One of the most powerful and beloved features of Cypress are easy network stubbing and spying APIs via `[cy.route](https://on.cypress.io/route?ref=cypress-io.ghost.io)` and `[cy.server](https://on.cypress.io/server?ref=cypress-io.ghost.io)` commands. These commands enable mocking of network responses with test data or fixtures, creation of testing scenarios by delaying response times or manipulating status codes, and much more.

`[cy.intercept](https://on.cypress.io/intercept?ref=cypress-io.ghost.io)` is the next-generation successor to `[cy.route](https://on.cypress.io/route?ref=cypress-io.ghost.io)` by offering much more flexibility and granular control over handling of the network layer. You will now have out-of-the-box support for intercepting  [fetch calls](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API?ref=cypress-io.ghost.io), page loads, and resource loads in addition to the pre-existing support for [XMLHttpRequests (XHR)](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest?ref=cypress-io.ghost.io).

## A Quick Dive Into cy.intercept

At first glance, the `cy.route` and `cy.intercept` APIs may seem similar. For example, to stub a network route with data from a fixture:

```jsx
// With cy.route
cy.server()
cy.route("/articles", "fixture:great-articles.json")

// With cy.intercept
cy.intercept("/articles", { fixture: "great-articles.json" })
```

There are three differences between the use of these commands in the above snippet:

-   `cy.intercept` does not require the use of `cy.server`. You can stop using `cy.server` once you fully switch to `cy.intercept`.
-   `cy.route` can use a shorthand string pattern (`fixture:*`) for specifying fixtures as the stubbed response. With `cy.intercept`, the same convenience is achieved with the second or `[StaticResponse](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#With-a-StaticResponse-object)` argument.
-   The third and invisible difference is that the default request method type with `cy.route` is `GET`. This is not the case for `cy.intercept`. In the above usage, the response would apply to all request method types. We would need to explicitly specify the method type we wish to intercept with `cy.intercept`. Here is one way to do so:

```jsx
// Stub GET requests to /articles with fixture
cy.intercept("GET", "/articles", { fixture: "great-articles.json" })
```

Now that we have seen some surface level differences, let's dive in a bit deeper. `cy.intercept` offers two new powerful mechanisms: `[routeMatcher](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#routeMatcher-RouteMatcher)` and `[routeHandler](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#routeHandler-string-object-Function-StaticResponse)`. These two are input arguments, and are used like so:

```jsx
cy.intercept(routeMatcher, routeHandler?)
```

`[routeMatcher](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#routeMatcher-RouteMatcher)` is an object that declares granular matching of network calls. Beyond matching against a specific URL or path, you can also match routes against distinct headers and even basic auth credentials. For example, you can intercept and spy on a request to a specific URL that has a specific header:

```jsx
cy.intercept({
  // this RegExp matches any URL beginning with '<http://api.example.com/widgets>'
  url: /^http:\\/\\/api\\.example\\.com\\/widgets/
  headers: {
    'x-requested-with': 'exampleClient'
  }
}).as("widgets")
```

Check out the [docs for a full list of matcher properties and usage patterns](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#routeMatcher-RouteMatcher).

Once a route is matched, an associated `[routeHandler](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#routeHandler-string-object-Function-StaticResponse)` can flexibly define what should happen with the interception. An interception can be used to make [assertions on requests/responses](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#Asserting-on-a-request), statically or dynamically [stub responses](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#Stubbing-a-response), [modify outgoing requests](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#Modifying-an-outgoing-request), and [more](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#Examples). Let's take a look at some examples.

A `[routeHandler](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#routeHandler-string-object-Function-StaticResponse)` can be defined as a function that receives a request (`req`) object. For example, we can use this function to make assertions:

```jsx
// Assert request body
cy.intercept('POST', '/organization', (req) => {
  expect(req.body).to.include('Acme Company')
})

// Assert response body
cy.intercept('/projects', (req) => {
  req.reply((res) => {
    expect(res.body).to.include('My Project')
  })
})
```

A `routeHandler` function can also be used to dynamically modify an incoming response:

```jsx
cy.intercept('/notification', (req) => {
  req.reply((res) => {
    // sends a fixture body instead of the existing 'res.body'
    res.send({ fixture: 'success.json' })

    // delays the response by 1000ms
    res.delay(1000)

    // throttles the response to 64kbps
    res.throttle(64)
  })
})
```

If dynamic stubbing is not desired, we can achieve the same behavior with a `[StaticResponse](https://docs.cypress.io/api/commands/intercept.html?ref=cypress-io.ghost.io#With-a-StaticResponse-object)` object in place of a function for the `routeHandler`:

```jsx
cy.intercept('/notification', {
	fixture: 'success.json',
	delayMs: 1000
	throttleKbps: 64
})
```

The versatility to dynamically handle interceptions is quite useful. For example, this functionality can be used to easily intercept specific GraphQL calls:

```jsx
cy.intercept('POST', '/graphql', (req) => {
  if (req.body.includes('mutation')) {
    req.alias = 'gqlMutation'
  }
})

// assert that a matching request has been made
cy.wait('@gqlMutation')
```

We've only seen a quick glance at what the new `cy.intercept` API unlocks. Check out the docs and recipes for examples and usage patterns.

## Migrating to cy.intercept

You may have already been enjoying the capabilities of `cy.intercept` since v5.1 via its experimental predecessor, `cy.route2`. After [upgrading to v6.0](http://on.cypress.io/changelog?ref=cypress-io.ghost.io#6-0-0), you can simply switch all instances of `cy.route2` in your tests to `cy.intercept`.

If you're currently happy with `cy.route`, there is no rush to switch to `cy.intercept` immediately, as `cy.route` and `cy.server` will be deprecated in the _next major version release_. However, switching over to the new `cy.intercept` from `cy.route` should be [straightforward along with our docs](https://on.cypress.io/intercept?ref=cypress-io.ghost.io). If you are ready to make the switch here are two tips to assist your migration:

-   When stubbing responses of network routes protected by CORS and/or authentication make sure to include to appropriate headers:

```jsx
cy.intercept(
  { method: "GET", url: "/bankAccounts" },
  {
    headers: {
      "access-control-allow-origin": window.location.origin,
      "Access-Control-Allow-Credentials": "true",
    },
    body: { results: [] },
  }
);
```

-   A [304 Not Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304?ref=cypress-io.ghost.io) status should be considered when making status code assertions on responses cached routes:

```jsx
cy.wait('@getComment').its('response.statusCode').should('be.oneOf', [200, 304])
```

## Upgrade to Cypress 6.0

In addition to `cy.intercept` check out [6.0 changelog](http://on.cypress.io/changelog?ref=cypress-io.ghost.io#6-0-0) for a full list of fixes and breaking changes. Also make sure to [check out the docs](https://on.cypress.io/intercept?ref=cypress-io.ghost.io) and the [migration guide](https://docs.cypress.io/guides/references/migration-guide.html?ref=cypress-io.ghost.io#Migrating-to-Cypress-6-0) to assist with your upgrade.

The Cypress team has been working hard to deliver this versatile and truly useful network handling experience. We're excited to bring these new APIs to Cypress users, and as always we're eager to hear your feedback.

Happy Testing.