7.8 KiB
title, comments, description
| title | comments | description |
|---|---|---|
| request | true |
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
.request() cannot be chained off any other cy commands, so should be chained off of cy for clarity.
{% fa fa-check-circle green %} Valid Usage
cy.request('http://dev.local/seed')
Arguments
{% fa fa-angle-right %} url (String, Glob, RegExp)
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 the .request() to use in the url.
- If you make a
.request()after visiting a page, Cypress assumes the url used for the.visit()is the host.
cy
.visit('http://localhost:8080/app')
.request('users/1.json') // <-- url is http://localhost:8080/users/1.json
```
2. If you make a `.request()` prior to visiting a page, Cypress uses the host configured as the `baseUrl` property inside of `cypress.json`.
***cypress.json***
```json
{
"baseUrl": "http://localhost:1234"
}
cy.request('seed/admin') //<-- url is http://localhost:1234/seed/admin
- 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 the specific method (GET, POST, PUT...). If no method is defined, Cypress will do a GET request by default.
{% fa fa-angle-right %} options (Object)
Pass in an options object to change the default behavior of cy.request.
| Option | Default | Notes |
|---|---|---|
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 |
log |
true |
Whether to log the request in the Command Log |
method |
GET |
The HTTP method to use in the request |
qs |
null |
Query parameters to append to the url of the request |
timeout |
responseTimeout |
Total time to wait for a response (in ms) |
url |
null |
The URL to make the request to |
You can also set options for the .request's baseUrl and responseTimeout globally in configuration.
Yields
.request() yields the response as an object literal containing properties such as status, body, headers, and duration.
Timeout
.request() will wait for the response for the duration of the responseTimeout or the timeout passed in the options object of the command.
Examples
URL
Make a GET request
.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 .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
// Delete a user
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, .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 we have a proper e2e test around logging in, there's no reason to continue going through the application's UI to log in users. .visit() waits for the entire page to load all associated resources before running any other commands. That would mean we'd have to wait before filling in and submitting the login form. Doing so slows down our entire test suite.
Using .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 %} Check out our example recipe using cy.request for HTML form submissions {% endnote %}
Notes
Request is not displayed in the Network Tab of Dev 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 the Dev Tools.
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 .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 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, .request() transparently performs all of the underlying functions as if it came from the browser.