Cypress应用

request

发起HTTP请求。

语法

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

用法

正确用法

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

参数

url (String)

请求的目标URL。

如果未提供完全限定的域名(FQDN)URL，Cypress会尽力猜测您希望cy.request()使用的URL主机。

1. 如果在访问页面后发起cy.request()，Cypress会假设cy.visit()使用的URL为主机。

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

2. 如果在访问页面前发起cy.request()，Cypress会假设主机为配置文件中配置的baseUrl属性。

cypress.config.js 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:1234',
  },
})

cypress.config.ts 文件

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:1234',
  },
})

cy.request('seed/admin') // URL为 http://localhost:1234/seed/admin

3. 如果Cypress无法确定主机，则会抛出错误。

body (String, Object)

请求中发送的body。Cypress会根据encoding选项设置Accepts请求头并序列化响应体。

method (String)

使用特定方法发起请求。如果未定义方法，Cypress默认使用GET方法。

支持的方法包括：

• GET
• POST
• PUT
• DELETE
• PATCH
• HEAD
• OPTIONS
• TRACE
• COPY
• LOCK
• MKCOL
• MOVE
• PURGE
• PROPFIND
• PROPPATCH
• UNLOCK
• REPORT
• MKACTIVITY
• CHECKOUT
• MERGE
• M-SEARCH
• NOTIFY
• SUBSCRIBE
• UNSUBSCRIBE
• SEARCH
• CONNECT

options (Object)

传入选项对象以更改cy.request()的默认行为。

您还可以在配置中全局设置cy.request()的baseUrl和responseTimeout选项。

选项	默认值	描述
log	true	在命令日志中显示命令
url	null	请求的目标URL
method	GET	请求中使用的HTTP方法
auth	null	添加Authorization头。接受这些选项。
body	null	随请求发送的body
failOnStatusCode	true	是否在响应码非2xx和3xx时失败
followRedirect	true	是否自动跟随重定向
form	false	是否将body值转换为URL编码内容并设置x-www-form-urlencoded头
encoding	utf8	序列化响应体时使用的编码。支持的编码包括：ascii, base64, binary, hex, latin1, utf8, utf-8, ucs2, ucs-2, utf16le, utf-16le
gzip	true	是否接受gzip编码
headers	null	发送的额外头；接受对象字面量。注意： headers仅对cy.request()的初始请求发送，不对后续请求发送。
qs	null	附加到请求url的查询参数
retryOnStatusCodeFailure	false	Cypress是否应自动重试状态码错误。如果设置为true，Cypress会重试请求最多4次。
retryOnNetworkFailure	true	Cypress是否应自动重试瞬时网络错误。如果设置为true，Cypress会重试请求最多4次。
timeout	responseTimeout	在超时前等待cy.request()解析的时间

您还可以在Cypress配置中全局设置cy.request()的baseUrl和responseTimeout选项。

生成结果

cy.request()将response作为包含以下属性的对象字面量返回：

• status
• body
• headers
• duration

示例

URL

发起GET请求

cy.request()非常适合在测试前与外部端点通信以填充数据库。

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

发起HTTP请求

有时测试页面内容比cy.visit()并等待整个页面及其所有资源加载更快。

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

方法和URL

发送DELETE请求

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

使用.as()别名请求

cy.request('https://jsonplaceholder.cypress.io/comments').as('comments')

cy.get('@comments').should((response) => {
  expect(response.body).to.have.length(500)
  expect(response).to.have.property('headers')
  expect(response).to.have.property('duration')
})

方法、URL和Body

发送带有JSON body的POST请求

cy.request('POST', 'http://localhost:8888/users/admin', { name: 'Jane' }).then(
  (response) => {
    // response.body会自动序列化为JSON
    expect(response.body).to.have.property('name', 'Jane') // true
  }
)

选项

发起请求时禁用自动重定向

要测试没有会话时的登录重定向行为，可以使用cy.request检查status和redirectedToUrl属性。

redirectedToUrl属性是Cypress的特殊属性，用于规范化浏览器在重定向期间通常会跟随的URL。

cy.request({
  url: '/dashboard',
  followRedirect: false, // 关闭跟随重定向
}).then((resp) => {
  // 重定向状态码为302
  expect(resp.status).to.eq(302)
  expect(resp.redirectedToUrl).to.eq('http://localhost:8082/unauthorized')
})

下载PDF文件

通过传递encoding: binary选项，response.body将是文件的二进制内容。您可以使用此方法通过.request()访问各种文件类型，如.pdf、.zip或.doc文件。

cy.request({
  url: 'http://localhost:8080/some-document.pdf',
  encoding: 'binary',
}).then((response) => {
  cy.writeFile('path/to/save/document.pdf', response.body, 'binary')
})

获取图片的Data URL

通过传递encoding: base64选项，response.body将是图片的base64编码内容。您可以使用此方法构建Data URI以供其他地方使用。

cy.request({
  url: 'https://docs.cypress.io/img/logo.png',
  encoding: 'base64',
}).then((response) => {
  const base64Content = response.body
  const mime = response.headers['content-type'] // 或 'image/png'
  // 参见 https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
  const imageDataUrl = `data:${mime};base64,${base64Content}`
})

使用form选项提交HTML表单

通常，一旦您有了关于登录的适当端到端测试，就没有必要继续cy.visit()登录并等待整个页面加载所有相关资源后再运行其他命令。这样做会减慢整个测试套件的速度。

使用cy.request()，我们可以绕过所有这些，因为它会自动获取和设置cookie，就像请求来自浏览器一样。

cy.request({
  method: 'POST',
  url: '/login_with_form', // baseUrl会预置到URL
  form: true, // 表示body应为表单URL编码，并设置Content-Type: application/x-www-form-urlencoded头
  body: {
    username: 'jane.lane',
    password: 'password123',
  },
})

// 证明我们有会话
cy.getCookie('cypress-session-cookie').should('exist')

使用cy.request()处理HTML表单

info

查看我们使用cy.request()处理HTML网页表单的示例配方

请求轮询

反复调用cy.request()

这在您轮询服务器以获取可能需要一段时间才能完成的响应时非常有用。

我们在这里所做的只是创建一个递归函数。没有比这更复杂的了。

// 一个普通的函数
function req () {
  cy
    .request(...)
    .then((resp) => {
      // 如果我们得到了想要的内容

      if (resp.status === 200 && resp.body.ok === true)
        // 跳出递归循环
        return

      // 否则递归
      req()
    })
}

cy
  // 执行引起副作用的事情
  .get('button').click()

  // 现在开始请求
  .then(req)

注意事项

调试

请求未显示在开发者工具的网络标签中

Cypress并不_实际_从浏览器发起XHR请求。我们实际上是从Cypress（在Node中）发起HTTP请求。因此，您不会在开发者工具中看到请求。

CORS

CORS被绕过

通常，当浏览器检测到跨源HTTP请求时，它会发送OPTIONS预检检查以确保服务器允许跨源请求，但cy.request()完全绕过CORS。

// 我们可以向任何外部服务器发起请求，没有问题。
cy.request('https://www.google.com/webhp?#q=cypress.io+cors')
  .its('body')
  .should('include', 'Testing, the way it should be') // true

Cookies

Cookies自动发送和接收

在发送HTTP请求之前，我们会自动附加那些如果请求来自浏览器本应附加的cookie。此外，如果响应中有Set-Cookie头，这些会自动设置回浏览器cookie。

换句话说，cy.request()透明地执行所有底层功能，就像它来自浏览器一样。

cy.intercept()

cy.request()向实际端点发送请求，绕过使用cy.intercept()定义的请求

cy.request()的意图是用于检查实际运行服务器上的端点，而无需启动前端应用程序。

用户代理

尝试更改User-Agent？

参见如何覆盖浏览器的默认用户代理。

规则

要求

• cy.request()需要链接到cy。
• cy.request()要求服务器发送响应。
• cy.request()要求当failOnStatusCode为true时，响应状态码为2xx或3xx。

断言

• cy.request()只会运行您链接的断言一次，不会重试。

超时设置

• cy.request()可能会因等待服务器响应而超时。

命令日志

请求评论端点并测试响应

cy.request('https://jsonplaceholder.typicode.com/comments').then((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')
})

上述命令将在命令日志中显示为：

当点击命令日志中的request时，控制台会输出以下内容：

历史

版本	变更
4.7.0	添加了对encoding选项的支持。
3.3.0	添加了对选项retryOnStatusCodeFailure和retryOnNetworkFailure的支持。
3.2.0	添加了对任何有效HTTPmethod参数的支持，包括TRACE, COPY, LOCK, MKCOL, MOVE, PURGE, PROPFIND, PROPPATCH, UNLOCK, REPORT, MKACTIVITY, CHECKOUT, MERGE, M-SEARCH, NOTIFY, SUBSCRIBE, UNSUBSCRIBE, SEARCH, 和CONNECT。

另请参阅

• cy.exec()
• cy.task()
• cy.visit()
• 配方：登录 - 单点登录
• 配方：登录 - HTML网页表单
• 配方：登录 - XHR网页表单
• 配方：登录 - CSRF令牌