intercept

// spying only
cy.intercept(url)
cy.intercept(method, url)
cy.intercept(routeMatcher)

// spying and response stubbing
cy.intercept(url, staticResponse)
cy.intercept(method, url, staticResponse)
cy.intercept(routeMatcher, staticResponse)
cy.intercept(url, routeMatcher, staticResponse)

// spying, dynamic stubbing, request modification, etc.
cy.intercept(url, routeHandler)
cy.intercept(method, url, routeHandler)
cy.intercept(routeMatcher, routeHandler)
cy.intercept(url, routeMatcher, routeHandler)

// spying
cy.intercept('/users/**')
cy.intercept('GET', '/users*')
cy.intercept({
  method: 'GET',
  url: '/users*',
  hostname: 'localhost',
})

// spying and response stubbing
cy.intercept('POST', '/users*', {
  statusCode: 201,
  body: {
    name: 'Peter Pan',
  },
})

// spying, dynamic stubbing, request modification, etc.
cy.intercept('/users*', { hostname: 'localhost' }, (req) => {
  /* do something with request and/or response */
})

// match any request that exactly matches the URL
cy.intercept('https://prod.cypress.io/users')

// match any request that satisfies a glob pattern
cy.intercept('/users?_limit=*')

// match any request that satisfies a regex pattern
cy.intercept(/\/users\?_limit=(3|5)$/)

cy.intercept('/users')
// matches this: GET http://localhost/users
// ...and this, too: POST http://localhost/users

cy.intercept('GET', '/users')
// matches this: GET http://localhost/users
// ...but not this: POST http://localhost/users

// These both yield the same result:
cy.intercept({ method: 'GET', url: '**/users' })
cy.intercept('GET', '**/users')

// Match any type of request with the pathname `/search`
// and the query paramater 'q=some+terms'
cy.intercept({
  pathname: '/search',
  query: {
    q: 'some terms',
  },
}).as('searchForTerms')

cy.intercept(
  {
    // this RegExp matches any URL beginning with
    // 'http://api.example.com/' and ending with '/edit' or '/save'
    url: /^http:\/\/api\.example\.com\/.*\/(edit|save)/,
    // matching requests must also contain this header
    headers: {
      'x-requested-with': 'exampleClient',
    },
  }
})

// this example will cause 1 request to `/temporary-error`
// to receive a network error and subsequent requests will
// not match this `RouteMatcher`
cy.intercept('/temporary-error', { times: 1 }, { forceNetworkError: true })

// match updates to the `/users` endpoint using glob matching
cy.intercept({
  method: '+(PUT|PATCH)',
  url: '**/users/*',
})
// matches:
//   PUT /users/1
//   PATCH /users/1
//   doesn't match
//   GET /users
//   GET /users/1

// same as above, but using regex
cy.intercept({
  method: '/PUT|PATCH/',
  url: '**/users/*',
})

cy.intercept('GET', '/users').as('getAllUsers')
cy.intercept('POST', '/users').as('createUser')

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

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

cy.intercept('http://example.com/settings').as('getSettings')

// once a request to get settings responds, 'cy.wait' will resolve
cy.wait('@getSettings')

cy.intercept({
  url: 'http://example.com/search*',
  query: { q: 'expected terms' },
}).as('search')

// once any type of request to search with a querystring
// containing 'q=expected+terms' responds, 'cy.wait' will resolve
cy.wait('@search')

cy.wait('@someRoute').then((interception) => {
  // 'interception' is an object with properties
  // 'id', 'request' and 'response'
})

// assert that a request to this route
// was made with a body that included 'user'
cy.wait('@someRoute').its('request.body').should('include', 'user')

// assert that a request to this route
// received a response with HTTP status 500
cy.wait('@someRoute').its('response.statusCode').should('eq', 500)

// assert that a request to this route
// received a response body that includes 'id'
cy.wait('@someRoute').its('response.body').should('include', 'id')

cy.intercept('GET', '/should-err', { forceNetworkError: true }).as('err')

// assert that this request happened
// and that it ended in an error
cy.wait('@err').should('have.property', 'error')

// requests to '/update' will be fulfilled
// with a body of "success"
cy.intercept('/update', 'success')

// requests to '/users.json' will be fulfilled
// with the contents of the "users.json" fixture
cy.intercept('/users.json', { fixture: 'users.json' })

const staticResponse = {
  /* some StaticResponse properties here... */
}

cy.intercept('/projects', staticResponse)

cy.intercept('/projects', {
  body: [{ projectId: '1' }, { projectId: '2' }],
})

cy.intercept('/not-found', {
  statusCode: 404,
  body: '404 Not Found!',
  headers: {
    'x-not-found': 'true',
  },
})

cy.intercept('/not-found', {
  fixture: 'media/gif.mp4,null',
})

cy.intercept('/users*', (req) => {
  /* do something with request and/or response */
})

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

// set the request body to something different
// before it's sent to the destination
cy.intercept('POST', '/login', (req) => {
  req.body = 'username=janelane&password=secret123'
})

// dynamically set the alias
cy.intercept('POST', '/login', (req) => {
  req.alias = 'login'
})

cy.intercept('/req-headers', (req) => {
  req.headers['x-custom-headers'] = 'added by cy.intercept'
})

cy.intercept('/req-headers', (req) => {
  req.headers['x-custom-headers'] = 'added by cy.intercept'
}).as('headers')

// the application makes the call ...
// confirm the custom header was added
cy.wait('@headers')
  .its('request.headers')
  .should('have.property', 'x-custom-headers', 'added by cy.intercept')

beforeEach(() => {
  cy.intercept(
    { url: 'http://localhost:3001/**', middleware: true },
    // Delete 'if-none-match' header from all outgoing requests
    (req) => delete req.headers['if-none-match']
  )
})

cy.intercept('/billing', (req) => {
  // functions on 'req' can be used to
  // dynamically respond to a request here

  // send the request to the destination server
  req.reply()

  // respond to the request with a JSON object
  req.reply({ plan: 'starter' })

  // send the request to the destination server
  // and intercept the response
  req.continue((res) => {
    // 'res' represents the real destination's response
    // See "Intercepting a response" for more details and examples
  })
})

cy.intercept('POST', '/login', (req) => {
  // you could asynchronously fetch test data...
  return getLoginCredentials().then((credentials) => {
    // ...and then, use it to supplement the outgoing request
    req.headers['authorization'] = credentials
  })
})

// you could have a top-level middleware handler that
// sets an auth token on all requests
// but remember setting `middleware: true` will
// cause this to always be called first
cy.intercept('http://api.company.com/', { middleware: true }, (req) => {
  req.headers['authorization'] = `token ${token}`
})

// and then have another handler that
// more narrowly asserts on certain requests
cy.intercept('POST', 'http://api.company.com/widgets', (req) => {
  expect(req.body).to.include('analytics')
})

// a POST request to http://api.company.com/widgets would hit both
// of those callbacks, middleware first, then the request would be
// sent out with the modified request headers to the
// real destination

cy.intercept('/integrations', (req) => {
  // req.continue() with a callback will send the request to
  // the destination server
  req.continue((res) => {
    // 'res' represents the real destination response
    // you can manipulate 'res' before it's sent to the browser
  })
})

cy.intercept('/projects/2', (req) => {
  req.continue((res) => {
    expect(res.body).to.include('My Project')
  })
})

cy.intercept('/users', (req) => {
  req.continue((res) => {
    // the response will not be sent to the browser until
    // 'waitForSomething()' resolves
    return waitForSomething()
  })
})

// Throttle API responses to simulate real-world conditions
beforeEach(() => {
  cy.intercept(
    {
      url: 'http://localhost:3001/**',
      middleware: true,
    },
    (req) => {
      req.on('response', (res) => {
        // Throttle the response to 1 Mbps to simulate a
        // mobile 3G connection
        res.setThrottle(1000)
      })
    }
  )
})

cy.intercept('/api', (req) => {
  // do something with the intercepted request
})

// match requests to create a user
cy.intercept('POST', '/users', (req) => {
  // make an assertion on the payload contents
  expect(req.body).to.include('Peter Pan')
})

// modify the request body before it's sent to its destination
cy.intercept('POST', '/users', (req) => {
  req.body = {
    name: 'Peter Pan',
  }
})

// add a header to an outgoing request
cy.intercept('POST', '/users', (req) => {
  req.headers['x-custom-header'] = 'added by cy.intercept'
})

// modify an existing header
cy.intercept('POST', '/users', (req) => {
  req.headers['authorization'] = 'Basic YWxhZGRpbjpvcGVuc2VzYW1l'
})

cy.intercept('POST', '/users', (req) => {
  req.headers['x-custom-header'] = 'added by cy.intercept'
}).as('createUser')

cy.get('button.save').click()
// you can see the headers in the console output by selecting
// this line in the command log:
cy.wait('@createUser')
  // ...or make an assertion:
  .its('request.headers')
  .should('have.property', 'x-custom-header', 'added by cy.intercept')

// stub out the response without interacting with a real back-end
cy.intercept('POST', '/users', (req) => {
  req.reply({
    headers: {
      Set-Cookie: 'newUserName=Peter Pan;'
    },
    statusCode: 201,
    body: {
      name: 'Peter Pan'
    },
    delay: 10, // milliseconds
    throttleKbps: 1000, // to simulate a 3G connection
    forceNetworkError: false // default
  })
})

// stub out a response body using a fixture
cy.intercept('GET', '/users', (req) => {
  req.reply({
    statusCode: 200, // default
    fixture: 'users.json'
  })
})

// equivalent to `req.reply({ body })`
req.reply(body)

// equivalent to `req.reply({ body, headers })`
req.reply(body, headers)

// equivalent to `req.reply({ statusCode, body, headers})`
req.reply(statusCode, body, headers)

// pass the request through and make an assertion on
// the real response
cy.intercept('POST', '/users', (req) => {
  req.continue((res) => {
    expect(res.body).to.include('Peter Pan')
  })
})

// dynamically destroy the request and
// respond with a network error
cy.intercept('POST', '/users', (req) => {
  if (mustDestroy(req)) {
    req.destroy()
  }

  function mustDestroy(req) {
    // code that determines whether to force a network error
    // based on the contents of `req`
  }
})

// respond to this request with a redirect to a new 'location'
cy.intercept('GET', '/users', (req) => {
  // statusCode defaults to `302`
  req.redirect('/customers', 301)
})

cy.intercept('GET', '/users', (req) => {
  req.on('before:response', (res) => {
    // do something when the `before:response` event is triggered
  })
})
cy.intercept('POST', '/users', (req) => {
  req.on('response', (res) => {
    // do something when the `response` event is triggered
  })
})

cy.intercept('POST', '/users', (req) => {
  // asynchronously fetch test data
  return getAuthToken().then((token) => {
    // ...and apply it to the outgoing request
    req.headers['Authorization'] = `Basic ${token}`
  })
})

cy.intercept('POST', '/users', (req) => {
  req.continue((res) => {
    // the response will not be sent to the browser until
    // `waitForSomething()` resolves:
    return waitForSomething()
  })
})

// requests to create a user will be fulfilled
// with a body of 'success'
cy.intercept('POST', '/users', 'success')
// { body: 'sucess' }

cy.intercept('/api', (req) => {
  // `req` represents the intercepted HTTP request
})

{
  /**
   * The body of the request.
   * If a JSON Content-Type was used and the body was valid JSON,
   * this will be an object.
   * If the body was binary content, this will be a buffer.
   */
  body: string | object | any
  /**
   * The headers of the request.
   */
  headers: { [key: string]: string }
  /**
   * Request HTTP method (GET, POST, ...).
   */
  method: string
  /**
   * Request URL.
   */
  url: string
  /**
   * URL query string as object.
   */
  query: Record<string, string|number>
  /**
   * The HTTP version used in the request. Read only.
   */
  httpVersion: string
}

{
  /**
   * If provided, the number of milliseconds before an upstream
   * response to this request will time out and cause an error.
   * By default, `responseTimeout` from config is used.
   */
  responseTimeout?: number
  /**
   * Set if redirects should be followed when this request is made.
   * By default, requests will not follow redirects before
   * yielding the response (the 3xx redirect is yielded).
   */
  followRedirect?: boolean
  /**
   * If set, `cy.wait` can be used to await the request/response
   * cycle to complete for this request via `cy.wait('@alias')`.
   */
  alias?: string
}

cy.intercept('POST', '/submitStory', (req) => {
  req.body.storyName = 'some name'
  // send the modified request and skip any other
  // matching request handlers
  req.continue()
})

cy.intercept('/billing', (req) => {
  // dynamically get billing plan name at request-time
  const planName = getPlanName()
  // this object will automatically be JSON.stringified and
  // sent as the response
  req.reply({ plan: planName })
})

cy.intercept('/api/users/*', async (req) => {
  // asynchronously retrieve fixture filename at request-time
  const fixtureFilename = await getFixtureFilenameForUrl(req.url)
  req.reply({
    fixture: fixtureFilename,
    delay: 500,
  })
})

// equivalent to `req.reply({ body })`
req.reply(body)

// equivalent to `req.reply({ body, headers })`
req.reply(body, headers)

// equivalent to `req.reply({ statusCode, body, headers})`
req.reply(statusCode, body, headers)

{
  /**
   * Destroy the request and respond with a network error.
   */
  destroy(): void
  /**
   * Respond to this request with a redirect to a new 'location'.
   * @param statusCode HTTP status code to redirect with. Default: 302
   */
  redirect(location: string, statusCode?: number): void
}

cy.intercept('/shop', (req) => {
  req.on('before:response', (res) => {
    /**
     * Emitted before `response` and before any `req.continue`
     * handlers. Modifications to `res` will be applied to the
     * incoming response. If a promise is returned, it will be
     * awaited before processing other event handlers.
     */
  })

  req.on('response', (res) => {
    /**
     * Emitted after `before:response` and after any
     * `req.continue` handlers - before the response is sent
     * to the browser. Modifications to `res` will be applied
     * to the incoming response. If a promise is returned, it
     * will be awaited before processing other event handlers.
     */
  })

  req.on('after:response', (res) => {
    /**
     * Emitted once the response to a request has finished
     * sending to the browser. Modifications to `res` have no
     * impact. If a promise is returned, it will be awaited
     * before processing other event handlers.
     */
  })
})

cy.intercept('/url', (req) => {
  req.on('before:response', (res) => {
    // this will be called before any `req.continue` or
    // `response` handlers
  })

  req.continue((res) => {
    // this will be called after all `before:response`
    // handlers and before any `response` handlers
    // by calling `req.continue`, we signal that this
    // request handler will be the last one, and that
    // the request should be sent outgoing at this point.
    // for that reason, there can only be one
    // `req.continue` handler per request.
  })

  req.on('response', (res) => {
    // this will be called after all `before:response`
    // handlers and after the `req.continue` handler
    // but before the response is sent to the browser
  })
})

cy.intercept('/notification', (req) => {
  req.continue((res) => {
    if (res.body.status === 'failed') {
      // sends a fixture body instead of the existing 'res.body'
      res.send({ fixture: 'success.json' })
    }
  })
})

// equivalent to `res.send({ body })`
res.send(body)

// equivalent to `res.send({ body, headers })`
res.send(body, headers)

// equivalent to `res.send({ statusCode, body, headers})`
res.send(statusCode, body, headers)

{
  /**
   * Wait for 'delay' milliseconds before sending the
   * response to the client.
   */
  setDelay: (delay: number) => IncomingHttpResponse
  /**
   * Serve the response at 'throttleKbps' kilobytes per second.
   */
  setThrottle: (throttleKbps: number) => IncomingHttpResponse
}

// match any request that exactly matches the URL
cy.intercept('https://prod.cypress.io/users')
// matches this: https://prod.cypress.io/users
// ...but not this: https://staging.cypress.io/users
// ...or this: http://localhost/users

cy.intercept('/users')
// matches all of these:
//   https://prod.cypress.io/users
//   https://staging.cypress.io/users
//   http://localhost/users

cy.intercept('/users?_limit=+(3|5)')
// matches all of these:
//   https://prod.cypress.io/users?_limit=3
//   http://localhost/users?_limit=5

expect(
  Cypress.minimatch('http://localhost/users?_limit=3', '**/users?_limit=+(3|5)')
).to.be.true
expect(
  Cypress.minimatch('http://localhost/users?_limit=5', '/users?_limit=+(3|5)', {
    matchBase: true,
  })
).to.be.true
expect(
  Cypress.minimatch('http://localhost/users?_limit=7', '**/users?_limit=+(3|5)')
).to.be.false

Cypress.minimatch('http://localhost/users?_limit=3', '**/users?_limit=+(3|5)', {
  debug: true,
})
// true (plus debug messages)

cy.intercept('/accounts*').as('accountsGet')
cy.intercept('/company', { companyId: 1 }).as('companyGet')
cy.intercept('/teams*', [{ teamId: 2 }]).as('teamsGet')