Skip to main content
Cypress应用

press

在应用中触发原生按键事件以模拟键盘交互。

keydown、press 和 keyup 事件将直接派发到浏览器窗口。

与最适合输入字符键的 cy.type() 不同，cy.press() 会派发真实的键盘事件而非模拟事件。该命令在测试对无障碍测试和优秀键盘用户体验至关重要的焦点管理和键盘导航模式时特别有用。

当前仅支持 Tab 键。

caution

支持的浏览器： 该命令在 Chromium 浏览器和 Firefox >= v135 版本中受支持。WebKit 不受支持。在不支持该命令的浏览器中执行时会失败。

语法​

cy.press(key)
cy.press(key, options)

签名​

interface PressCommand {
  (
    key: KeyPressSupportedKeys,
    options?: Partial<Cypress.Loggable> & Partial<Cypress.Timeoutable>
  ): void
}

用法​

正确用法

cy.get('input.first').focus()
cy.press(Cypress.Keyboard.Keys.TAB)
cy.get('input.second').should('have.focus')

错误用法

cy.get('input.first').focus()
cy.press(Cypress.Keyboard.Keys.TAB)
  // 错误，因为 press 返回 null
  .should('have.focus')

参数​

key (String)

要按下的键。支持的值可在 Cypress.Keyboard.Keys 中找到，并可能随时间变化。建议从 Cypress.Keyboard.Keys 引用这些值，而非直接传入字符串。

支持的按键​

引用值
Cypress.Keyboard.Keys.TAB"Tab"

options (Object)

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

选项默认值描述
logtrue在命令日志中显示该命令
timeoutdefaultCommandTimeout等待 cy.press() 解析的超时时间

生成结果 了解主题管理​

  • cy.press() 返回 null。

示例​

测试 Tab 键的焦点顺序​

it('按下 Tab 键时将焦点移动到下一个表单元素', () => {
  cy.visit('/my-login')
  cy.get('input.email').type('username')
  cy.press(Cypress.Keyboard.Keys.TAB)
  cy.get('input.password').should('have.focus')
})

测试 Tab 键触发的搜索输入自动补全​

it('按下 Tab 键时自动补全搜索输入', () => {
  cy.get('[data-cy="search"]').type('cy')
  cy.press(Cypress.Keyboard.Keys.TAB)
  cy.get('[data-cy="search"]').should('have.value', 'cypress')
})

注意事项​

瞬时激活​

通过向浏览器派发原生键盘事件，该命令会使浏览器进入瞬时激活状态。

如果你的应用阻止了 beforeunload 事件的默认行为，这可能在离开当前页面时导致问题。

历史​

版本变更
14.3.0新增 .press() 命令

另请参阅​

目录