Cypress应用

visit

访问远程URL。

caution

最佳实践

我们建议在使用cy.visit()时设置baseUrl。

阅读相关最佳实践了解详情。

语法

cy.visit(url)
cy.visit(url, options)
cy.visit(options)

用法

正确用法

cy.visit('/') // 访问baseUrl
cy.visit('index.html') // 如果baseUrl为null，则访问本地文件"index.html"
cy.visit('http://localhost:3000') // 如果baseUrl为null或域名与baseUrl不同，需指定完整URL
cy.visit({
  url: '/pages/hello.html',
  method: 'GET',
})

参数

url (String)

要访问的URL。

如果设置了全局配置中的baseUrl，Cypress会在URL前添加该baseUrl。

如果未设置baseUrl，则需要指定完整的URL，否则Cypress会尝试充当您的Web服务器。详情请参阅前缀说明。

注意： 访问新域名需要重新加载Cypress窗口。在不使用cy.origin()的情况下，无法在单个测试中访问不同的超级域名。

options (Object)

传入一个选项对象以控制cy.visit()的行为。

默认情况下，cy.visit()命令将使用全局配置中的pageLoadTimeout和baseUrl。

选项	默认值	描述
`url`	`null`	要访问的URL。如果配置了`baseUrl`，此值将附加到`baseUrl`后。行为与`url`参数相同。
`method`	`GET`	访问时使用的HTTP方法。可以是`GET`或`POST`。
`body`	`null`	与`POST`请求一起发送的可选正文。如果是字符串，将原样传递。如果是对象，将被URL编码为字符串并以`Content-Type: application/x-www-urlencoded`标头发送。
`headers`	`{}`	将HTTP标头名称映射到值的对象，随请求一起发送。注意： `headers`仅对初始`cy.visit()`请求发送，不对后续请求发送。
`qs`	`null`	附加到请求`url`的查询参数
`log`	`true`	在命令日志中显示命令
`auth`	`null`	添加基本认证标头
`failOnStatusCode`	`true`	是否对非`2xx`和`3xx`的响应码失败
`onBeforeLoad`	`function`	在页面加载所有资源之前调用。
`onLoad`	`function`	在页面触发`load`事件后调用。
`retryOnStatusCodeFailure`	`false`	Cypress是否应自动重试状态码错误。如果设置为true，Cypress将最多重试请求4次。
`retryOnNetworkFailure`	`true`	Cypress是否应自动重试瞬时网络错误。如果设置为true，Cypress将最多重试请求4次。
`timeout`	`pageLoadTimeout`	等待`cy.visit()`解析的超时时间。注意：网络请求受底层操作系统限制，即使增加此值仍可能超时。

您还可以在Cypress配置中全局设置所有cy.visit()命令的pageLoadTimeout和baseUrl。

生成结果

cy.visit()在页面加载完成后返回window对象。
在cy.visit()之后链接依赖于返回的window的进一步命令是不安全的。

让我们在访问网站后确认window.navigator.language：

cy.visit('/') // 返回window对象
  .its('navigator.language') // 返回window.navigator.language
  .should('equal', 'en-US') // 断言期望值

示例

URL

访问运行在`http://localhost:8000`上的本地服务器

cy.visit()在远程页面触发load事件时解析。

cy.visit('http://localhost:8000')

选项

更改默认超时

覆盖全局配置中的pageLoadTimeout。

// 等待30秒以触发页面'load'事件
cy.visit('/index.html', { timeout: 30000 })

添加基本认证标头

如果访问需要基本认证的应用程序，Cypress会自动应用正确的授权标头。

在auth对象中提供username和password。然后所有匹配您测试来源的后续请求将在网络级别附加这些标头。

cy.visit('https://example.cypress.io/', {
  auth: {
    username: 'wile',
    password: 'coyote',
  },
})

您也可以直接在URL中提供用户名和密码。

// 这与提供auth对象相同
cy.visit('https://wile:coyote@example.cypress.io')

info

Cypress将在网络代理级别自动附加此标头，浏览器外部。因此您不会在开发者工具中看到此标头。

提供`onBeforeLoad`回调函数

onBeforeLoad在页面加载所有资源之前尽快调用。此时脚本尚未准备就绪，但这是操作页面的好时机。

cy.visit('http://localhost:3000/#dashboard', {
  onBeforeLoad: (contentWindow) => {
    // contentWindow是远程页面的window对象
  },
})

info

查看我们的示例配方，使用cy.visit()的onBeforeLoad选项：

提供`onLoad`回调函数

onLoad在页面触发load事件后调用。此时所有脚本、样式表、HTML和其他资源都已准备就绪。

cy.visit('http://localhost:3000/#/users', {
  onLoad: (contentWindow) => {
    // contentWindow是远程页面的window对象
    if (contentWindow.angular) {
      // 执行某些操作
    }
  },
})

添加查询参数

您可以通过将qs传递给options，以对象形式向cy.visit()提供查询参数。

// 访问http://localhost:3500/users?page=1&role=admin
cy.visit('http://localhost:3500/users', {
  qs: {
    page: '1',
    role: 'admin',
  },
})

传递给qs的参数将与url上的现有查询参数合并。

// 访问https://example.cypress.io/users?page=1&admin=true
cy.visit('https://example.cypress.io/users?page=1', {
  qs: { admin: true },
})

提交表单

要发送类似于用户提交HTML表单的请求，请使用POST方法和包含表单值的body：

cy.visit({
  url: 'http://localhost:3000/cgi-bin/newsletterSignup',
  method: 'POST',
  body: {
    name: 'George P. Burdell',
    email: 'burdell@microsoft.com',
  },
})

说明

前缀

访问自动添加`baseUrl`前缀

如果设置了baseUrl，Cypress会在URL前添加该baseUrl。在Cypress配置中配置baseUrl以避免在每个cy.visit()命令中重复。

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

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

import { defineConfig } from 'cypress'

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

cy.visit('dashboard') // 访问http://localhost:3000/#/dashboard

如果设置了baseUrl但需要访问不同的主机，请提供完整的URL。

cy.visit('https://example.cypress.io')

访问本地文件

如果未提供主机且未定义baseUrl，Cypress会自动尝试提供您的文件。路径应相对于项目的根文件夹（包含Cypress配置文件的目录）。

让Cypress提供您的文件在小型项目和示例应用程序中很有用，但不建议用于生产应用程序。最好运行自己的服务器并向Cypress提供URL。

cy.visit('app/index.html')

设置`baseUrl`时访问本地文件

如果设置了baseUrl但需要在单个测试或一组测试中访问本地文件，请使用每个测试的配置禁用baseUrl。假设有以下Cypress配置：

cypress.config.js 文件
cypress.config.ts 文件

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'https://example.cypress.io',
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'https://example.cypress.io',
  },
})

第一个测试访问baseUrl，而第二个测试访问本地文件。

it('访问base url', () => {
  cy.visit('/')
  cy.contains('h1', 'Kitchen Sink')
})
it('访问本地文件', { baseUrl: null }, () => {
  cy.visit('index.html')
  cy.contains('本地文件')
})

重定向

访问会自动跟随重定向

// 我们未登录，因此Web服务器将我们重定向到/login
cy.visit('http://localhost:3000/admin')
cy.url().should('match', /login/)

协议

常见主机的协议可以省略

Cypress会自动为常见主机添加http://协议。如果您不使用这3个主机之一，请确保提供协议。

cy.visit('localhost:3000') // 访问http://localhost:3000
cy.visit('0.0.0.0:3000') // 访问http://0.0.0.0:3000
cy.visit('127.0.0.1:3000') // 访问http://127.0.0.1:3000

Window

访问在解析时始终返回远程页面的`window`对象

cy.visit('index.html').then((contentWindow) => {
  // contentWindow是远程页面的window对象
})

用户代理

尝试更改User-Agent？

查看如何覆盖浏览器的默认用户代理。

路由

在远程页面初始加载前阻止请求

Cypress支持的一个常见场景是访问远程页面并阻止任何Ajax请求立即发出。

您可能认为这样可以：

// 此代码可能因实现方式不同而不起作用
cy.visit('http://localhost:8000/#/app')
cy.intercept('/users/**', { fixture: 'users' })

但如果您的应用程序在初始化时发出请求，上述代码将不起作用。cy.visit()在其load事件触发时解析。cy.intercept()命令在cy.visit()解析后才会处理。

许多应用程序在cy.visit()解析时已经开始路由、初始化和请求。因此创建cy.intercept()路由为时已晚，Cypress将无法处理这些请求。

幸运的是，Cypress支持此用例。反转命令顺序：

// 这可能是您想要的代码
cy.intercept('/users/**', {...})
cy.visit('http://localhost:8000/#/app')

Cypress会自动将路由应用到下一个cy.visit()，并在您的应用程序代码运行之前立即执行。

规则

要求

cy.visit()需要链接到cy。
cy.visit()要求响应为content-type: text/html。
cy.visit()要求在跟随重定向后响应码为2xx。
cy.visit()要求最终触发load事件。

断言

cy.visit()会自动等待链接的断言通过

超时设置

cy.visit()可能因等待页面触发load事件而超时。
cy.visit()可能因等待添加的断言通过而超时。

访问跨源站点

访问跨源站点后，要与其内容交互，必须使用cy.origin()块。

访问跨源站点时，不支持onBeforeLoad和onLoad选项。

命令日志

在beforeEach中访问示例应用程序

beforeEach(() => {
  cy.visit('https://example.cypress.io/commands/viewport')
})

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

点击命令日志中的visit时，控制台输出如下：

历史

版本	变更
11.0.0	移除了`experimentalSessionAndOrigin`引用
3.5.0	添加了对选项`qs`的支持
3.3.0	添加了对选项`retryOnStatusCodeFailure`和`retryOnNetworkFailure`的支持
3.2.0	添加了选项`url`、`method`、`body`和`headers`
1.1.3	添加了选项`failOnStatusCode`
0.18.2	自动发送`Accept: text/html,/`请求标头
0.18.2	自动发送`User-Agent`标头
0.17.0	无法在单个测试中`cy.visit()`两个不同的超级域名
0.6.8	添加了选项`log`
0.4.3	添加了选项`onBeforeLoad`
< 0.3.3	添加了`cy.visit()`命令

visit

语法​

用法​

参数​

生成结果 了解主题管理​

示例​

URL​

访问运行在http://localhost:8000上的本地服务器​

选项​

更改默认超时​

添加基本认证标头​

提供onBeforeLoad回调函数​

提供onLoad回调函数​

添加查询参数​

提交表单​

说明​

前缀​

访问自动添加baseUrl前缀​

访问本地文件​

设置baseUrl时访问本地文件​

重定向​

访问会自动跟随重定向​

协议​

常见主机的协议可以省略​

Window​

访问在解析时始终返回远程页面的window对象​

用户代理​

路由​

在远程页面初始加载前阻止请求​

规则​

要求 了解命令链​

断言 了解断言​

超时设置 了解超时机制​

访问跨源站点​

命令日志​

历史​

另请参阅​

目录

语法

用法

参数