Skip to main content
Cypress应用

viewport

控制应用程序屏幕的尺寸和方向。

info

您可以通过在Cypress配置中定义viewportWidth和viewportHeight来全局设置视口的宽度和高度。

语法​

cy.viewport(width, height)
cy.viewport(preset, orientation)
cy.viewport(width, height, options)
cy.viewport(preset, orientation, options)

用法​

正确用法

cy.viewport(550, 750) // 将视口设置为550px x 750px
cy.viewport('iphone-6') // 将视口设置为375px x 667px

参数​

width (Number)

视口宽度（像素），必须为非负有限数。

height (Number)

视口高度（像素），必须为非负有限数。

preset (String)

预设尺寸来设置视口。支持以下选项：

预设宽度高度
ipad-27681024
ipad-mini7681024
iphone-3320480
iphone-4320480
iphone-5320568
iphone-6375667
iphone-6+414736
iphone-7375667
iphone-8375667
iphone-x375812
iphone-xr414896
iphone-se2375667
macbook-111366768
macbook-131280800
macbook-151440900
macbook-161536960
samsung-note9414846
samsung-s10360760

orientation (String)

屏幕方向。_默认方向_为portrait。传入landscape会交换宽度/高度。

options (Object)

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

选项默认值描述
logtrue在命令日志中显示命令

生成结果 了解主题管理​

  • cy.viewport()返回null。

示例​

宽度、高度​

将视口调整为1024px x 768px​

cy.viewport(1024, 768)

分别组织桌面和移动端测试​

describe('导航菜单', () => {
  context('720p分辨率', () => {
    beforeEach(() => {
      // 以720p显示器桌面浏览器运行这些测试
      cy.viewport(1280, 720)
    })

    it('显示完整头部', () => {
      cy.get('nav .desktop-menu').should('be.visible')
      cy.get('nav .mobile-menu').should('not.be.visible')
    })
  })

  context('iphone-5分辨率', () => {
    beforeEach(() => {
      // 以移动浏览器运行这些测试
      cy.viewport('iphone-5')
    })

    it('点击显示移动菜单', () => {
      cy.get('nav .desktop-menu').should('not.be.visible')
      cy.get('nav .mobile-menu')
        .should('be.visible')
        .find('i.hamburger')
        .click()

      cy.get('ul.slideout-menu').should('be.visible')
    })
  })
})

动态测试多个视口​

const sizes = ['iphone-6', 'ipad-2', [1024, 768]]

describe('Logo', () => {
  sizes.forEach((size) => {
    it(`应在${size}屏幕上显示Logo`, () => {
      if (Cypress._.isArray(size)) {
        cy.viewport(size[0], size[1])
      } else {
        cy.viewport(size)
      }

      cy.visit('https://example.cypress.io')
      cy.get('#logo').should('be.visible')
    })
  })
})
多视口命令日志

预设​

将视口调整为iPhone 6尺寸​

cy.viewport('iphone-6') // 视口将变为414px x 736px

方向​

将方向改为横屏​

// 视口将变为736px x 414px
// 模拟用户横向持握iPhone
cy.viewport('iphone-6', 'landscape')

注意事项​

devicePixelRatio​

不支持devicePixelRatio模拟​

如果需要此功能，请关注#7075。

恢复​

Cypress会在快照中恢复视口​

当悬停在每个命令上时，Cypress会自动以命令运行时的视口尺寸显示快照。

默认值​

默认尺寸​

默认情况下，在未执行cy.viewport()命令前，Cypress将宽度设为1000px，高度设为660px。

您可以通过在Cypress配置中添加以下内容来更改这些默认尺寸：

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  viewportWidth: 1000,
  viewportHeight: 660,
})

此外，Cypress会在每个测试之间自动将视口重置为默认尺寸。

缩放​

自动缩放​

默认情况下，如果屏幕不足以显示当前尺寸的所有像素，Cypress会在预览窗格中缩放并居中您的应用程序。

缩放不会影响应用程序的任何计算或行为（实际上应用程序甚至不会知道正在被缩放）。

这样做的好处是无论开发者的屏幕尺寸如何，测试都能一致地通过或失败。在CI中测试也能一致运行，因为所有视口在不同机器上都是相同的。

通过Cypress.config()重置视口​

您可以通过在Cypress.config()中设置viewportHeight或viewportWidth的新值来更改剩余测试的视口高度和宽度。

Cypress.config('viewportWidth', 800)
Cypress.config('viewportWidth') // => 800

在测试配置中设置视口​

您可以通过在测试配置中传入新的配置值来在测试套件或测试中配置视口高度和宽度。

这将在测试期间设置高度和宽度，完成后恢复为默认的viewportHeight和viewportWidth。

describe(
  '中等尺寸屏幕的页面显示',
  {
    viewportHeight: 1000,
    viewportWidth: 400,
  },
  () => {
    it('不显示侧边栏', () => {
      cy.get('#sidebar').should('not.be.visible')
    })

    it('显示汉堡菜单', () => {
      cy.get('#header').find('i.menu').should('be.visible')
    })
  }
)

规则​

要求 了解命令链​

  • cy.viewport()必须链接到cy。

断言 了解断言​

  • cy.viewport()不能链接任何断言。

超时设置 了解超时机制​

  • cy.viewport()不会超时。

命令日志​

更改视口尺寸以测试响应式导航

cy.get('#navbar').should('be.visible')

cy.viewport(320, 480)

// 由于屏幕较小，导航栏应折叠
cy.get('#navbar').should('not.be.visible')
cy.get('.navbar-toggle').should('be.visible')
cy.get('.navbar-toggle').click()
cy.get('.nav').find('a').should('be.visible')

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

视口命令日志

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

视口控制台日志

历史​

版本变更
5.5.0新增macbook-16预设支持。
5.4.0新增iphone-7、iphone-8和iphone-se2预设支持。
3.8.0移除最大视口尺寸限制并将最小视口尺寸降至0。
3.5.0新增iphone-xr、iphone-x、samsung-s10和samsung-note9预设支持
3.5.0将最大视口尺寸增至4000
0.9.0新增cy.viewport()命令

另请参阅​

目录