cypress/docs/source/api/commands/request.md

title, comments

title	comments
request	false

Make an HTTP request.

Syntax

cy.request(url)
cy.request(url, body)
cy.request(method, url)
cy.request(method, url, body)
cy.request(options)

Usage

{% fa fa-check-circle green %} Correct Usage

cy.request('http://dev.local/seed')    

Arguments

{% fa fa-angle-right %} url (String)

The url to make the request to.

If you provide a non fully qualified domain name (FQDN), Cypress will make its best guess as to which host you want cy.request() to use in the url.

1. If you make a cy.request() after visiting a page, Cypress assumes the url used for the cy.visit() is the host.

cy.visit('http://localhost:8080/app')
cy.request('users/1.json') //  url is  http://localhost:8080/users/1.json

2. If you make a cy.request() prior to visiting a page, Cypress uses the host configured as the baseUrl property inside of cypress.json.

// cypress.json

{
  "baseUrl": "http://localhost:1234"
}

cy.request('seed/admin') // url is http://localhost:1234/seed/admin

3. If Cypress cannot determine the host it will throw an error.

{% fa fa-angle-right %} body (String, Object)

A request body to be sent in the request. Cypress sets the Accepts request header and serializes the response body by its Content-Type.

{% fa fa-angle-right %} method (String)

Make a request using a specific method (GET, POST, PUT, etc). If no method is defined, Cypress uses the GET method by default.

{% fa fa-angle-right %} options (Object)

Pass in an options object to change the default behavior of cy.request.

Option	Default	Description
log	true	{% usage_options log %}
url	null	The URL to make the request to
method	GET	The HTTP method to use in the request
auth	null	Any auth to send; Accepts object literal
body	null	Body to send along with the request
failOnStatusCode	true	Whether to fail on response codes other than 2xx and 3xx
followRedirect	true	Whether to automatically follow redirects
form	false	Whether to convert the body values to url encoded content and set the x-www-form-urlencoded header
gzip	true	Whether to accept the gzip encoding
headers	null	Additional headers to send; Accepts object literal
qs	null	Query parameters to append to the url of the request
timeout	{% url responseTimeout configuration#Timeouts %}	{% usage_options timeout cy.request %}

You can also set options for cy.request's baseUrl and responseTimeout globally in {% url 'configuration' configuration %}.

Yields {% helper_icon yields %}

cy.request() yields the response as an object literal containing properties such as:

• status
• body
• headers
• duration

Examples

URL

Make a GET request

cy.request() is great for talking to an external endpoint before your tests to seed a database.

beforeEach(function(){
  cy.request('http://localhost:8080/db/seed')
})

Issue a simple HTTP request

Sometimes it is quicker to simply test the contents of a page rather than {% url cy.visit() visit %} and wait for the entire page and all of it's resource to load.

cy.request('/admin').its('body').should('include', '<h1>Admin</h1>')

Method and URL

Send a DELETE request

cy.request('DELETE', 'http://localhost:8888/users/827')

Method, URL, and Body

Send a POST request with a JSON body

cy.request('POST', 'http://localhost:8888/users/admin', {name: 'Jane'})
  .then(function(response){
    // response.body is automatically serialized into JSON
    expect(response.body).to.have.property('name', 'Jane') // true
})

Options

Request a page while disabling auto redirect

To test the redirection behavior of a login without a session, cy.request can be used to check the status and redirectedToUrl property.

The redirectedToUrl property is a special Cypress property that normalizes the url the browser would normally follow during a redirect.

cy.request({
    url: '/dashboard',
    followRedirect: false // turn off following redirects
  })
  .then((resp) => {
    // redirect status code is 302
    expect(resp.status).to.eq(302)
    expect(resp.redirectedToUrl).to.eq('http://localhost:8082/unauthorized')
  })

HTML form submissions using form option

Oftentimes, once you have a proper e2e test around logging in, there's no reason to continue to cy.visit() the login and wait for the entire page to load all associated resources before running any other commands. Doing so can slow down our entire test suite.

Using cy.request(), we can bypass all of this because it automatically gets and sets cookies just as if the requests had come from the browser.

cy.request({
    method: 'POST',
    url: '/login_with_form', // baseUrl is prepended to url
    form: true, // indicates the body should be form urlencoded and sets Content-Type: application/x-www-form-urlencoded headers
    body: {
      username: 'jane.lane',
      password: 'password123'
    }
  })

// just to prove we have a session
cy.getCookie('cypress-session-cookie').should('exist')

Using cy.request for HTML Forms

{% note info %} {% url "Check out our example recipe using cy.request() for HTML form submissions" logging-in-recipe %} {% endnote %}

Notes

Debugging

Request is not displayed in the Network Tab of Developer Tools

Cypress does not actually make an XHR request from the browser. We are actually making the HTTP request from the Cypress desktop application (in Node.js). So, you won't see the request inside of your Developer Tools.

Cors

CORS is bypassed

Normally when the browser detects a cross-origin HTTP request, it will send an OPTIONS preflight check to ensure the server allows cross-origin requests, but cy.request() bypasses CORS entirely.

// we can make requests to any external server, no problem.
cy.request('https://www.google.com/webhp?#q=cypress.io+cors')
  .its('body').should('include', 'Testing, the way it should be') // true

Cookies

Cookies are automatically sent and received

Before sending the HTTP request, we automatically attach cookies that would have otherwise been attached had the request come from the browser. Additionally, if a response has a Set-Cookie header, these are automatically set back on the browser cookies.

In other words, cy.request() transparently performs all of the underlying functions as if it came from the browser.

Rules

Requirements {% helper_icon requirements %}

{% requirements request cy.request %}

Assertions {% helper_icon assertions %}

{% assertions once cy.request %}

Timeouts {% helper_icon timeout %}

{% timeouts request cy.request %}

Command Log

Request comments endpoint and test response

cy.request('https://jsonplaceholder.typicode.com/comments').then(function(response){
  expect(response.status).to.eq(200)
  expect(response.body).to.have.length(500)
  expect(response).to.have.property('headers')
  expect(response).to.have.property('duration')
})

The commands above will display in the command log as:

When clicking on request within the command log, the console outputs the following:

See also

• {% url cy.exec() exec %}
• {% url cy.visit() visit %}
• {% url "Recipe: Logging In - CSRF Tokens" logging-in-recipe %}
• {% url "Recipe: Logging In - HTML Web Form" logging-in-recipe %}
• {% url "Recipe: Logging In - Single Sign on" logging-in-recipe %}
• {% url "Recipe: Logging In - XHR Web Form" logging-in-recipe %}