Skip to main content
Cypress应用

type

向DOM元素输入内容。

.type()之后继续链式调用依赖于该主题的命令是不安全的

语法

.type(text)
.type(text, options)

用法

正确用法

cy.get('input').type('Hello, World') // 在'input'中输入'Hello, World'

错误用法

cy.type('Welcome') // 错误,不能从'cy'链式调用
cy.clock().type('www.cypress.io') // 错误,'clock'不返回DOM元素

参数

text (String)

要输入到DOM元素中的文本。

传递给.type()的文本可以包含以下任何特殊字符序列。这些字符将在.type()期间触发的事件中传递正确的keyCodekeywhich码。一些特殊字符序列在输入时可能会执行操作,如{moveToEnd}{moveToStart}{selectAll}

info

要禁用解析特殊字符序列,请将parseSpecialCharSequences选项设置为false

序列说明
{{}输入字面量{
{backspace}删除光标左侧的字符
{del}删除光标右侧的字符
{downArrow}光标下移
{end}光标移至行尾
{enter}输入Enter键
{esc}输入Escape键
{home}光标移至行首
{insert}在光标右侧插入字符
{leftArrow}光标左移
{moveToEnd}光标移至可输入元素的末尾
{moveToStart}光标移至可输入元素的起始位置
{pageDown}向下滚动
{pageUp}向上滚动
{rightArrow}光标右移
{selectAll}通过创建selection range选中所有文本
{upArrow}光标上移

传递给.type()的文本还可以包含以下修饰符字符序列:

序列说明
{alt}激活altKey修饰符。别名:{option}
{ctrl}激活ctrlKey修饰符。别名:{control}
{meta}激活metaKey修饰符。别名:{command}, {cmd}
{shift}激活shiftKey修饰符。

options (Object)

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

选项默认值说明
animationDistanceThresholdanimationDistanceThreshold元素必须随时间超过的像素距离才能被视为动画
delay10每次按键后的延迟
forcefalse强制操作,禁用等待可操作性
logtrue命令日志中显示命令
parseSpecialCharSequencestrue解析由{}包围的特殊字符,如{esc}。设置为false以输入字面字符
releasetrue在命令之间保持修饰符激活
scrollBehaviorscrollBehavior在执行命令前,元素应滚动到的视口位置
timeoutdefaultCommandTimeout等待.type()解析的时长,超过则超时
waitForAnimationswaitForAnimations是否在命令执行前等待元素完成动画

生成结果 了解主题管理

  • .type()返回与给定主题相同的主题。
  • .type()之后继续链式调用依赖于该主题的命令是不安全的

示例

输入框/文本域

在文本域中输入内容。

cy.get('textarea').type('Hello world') // 返回 <textarea>

在登录表单中输入内容

模拟用户输入行为

默认情况下,每次按键之间有10ms的延迟,以模拟快速用户的输入行为!

cy.get('[contenteditable]').type('some text!')

从数据列表'选择'选项

对于'选择'选项,只需在输入框中输入即可。

<input list="fruit" />
<datalist id="fruit">
<option>Apple</option>
<option>Banana</option>
<option>Cantaloupe</option>
</datalist>
cy.get('input').type('Apple')

Tabindex

在具有tabindex的非输入或非文本域元素中输入内容

<body>
<div id="el" tabindex="1">这个div可以接收焦点!</div>
</body>
cy.get('#el').type('supercalifragilisticexpialidocious')

日期输入

在日期输入框(<input type="date">)上使用.type()需要指定以下格式的有效日期:

  • yyyy-MM-dd (例如 1999-12-31)

这并不是用户输入日期输入框的确切方式,但由于日期输入支持因浏览器和地区而异,这是一个变通方法。yyyy-MM-ddW3规范要求的格式,无论浏览器或地区如何,输入框的value都将设置为该格式。

{upArrow}{downArrow}可以根据提供的"step"参数增加和减少日期值。使用.type(){upArrow}{downArrow}模拟了stepUpstepDown输入方法的行为。

不允许使用特殊字符({leftArrow}, {selectAll}等)。

月份输入

在月份输入框(<input type="month">)上使用.type()需要指定以下格式的有效月份:

  • yyyy-MM (例如 1999-12)

这并不是用户输入月份输入框的确切方式,但由于月份输入支持因浏览器和地区而异,这是一个变通方法。yyyy-MMW3规范要求的格式,无论浏览器或地区如何,输入框的value都将设置为该格式。

{upArrow}{downArrow}可以根据提供的"step"参数增加和减少月份值。使用.type(){upArrow}{downArrow}模拟了stepUpstepDown输入方法的行为。

不允许使用特殊字符({leftArrow}, {selectAll}等)。

周输入

在周输入框(<input type="week">)上使用.type()需要指定以下格式的有效周:

  • yyyy-Www (例如 1999-W23)

其中W是字面字符'W',ww是周数(01-53)。

这并不是用户输入周输入框的确切方式,但由于周输入支持因浏览器和地区而异,这是一个变通方法。yyyy-WwwHTML规范要求的格式,无论浏览器或地区如何,输入框的value都将设置为该格式。

不允许使用特殊字符({leftArrow}, {selectAll}等)。

{upArrow}{downArrow}可以根据提供的"step"参数增加和减少周值。使用.type(){upArrow}{downArrow}模拟了stepUpstepDown输入方法的行为。

时间输入

在时间输入框(<input type="time">)上使用.type()需要指定以下格式的有效时间:

  • HH:mm (例如 01:3023:15)
  • HH:mm:ss (例如 10:00:30)
  • HH:mm:ss.SSS (例如 12:00:00.384)

其中HH是00-23,mm是00-59,ss是00-59,SSS是000-999。

{upArrow}{downArrow}可以根据提供的"step"参数增加和减少秒值。使用.type(){upArrow}{downArrow}模拟了stepUpstepDown输入方法的行为。

不允许使用特殊字符({leftArrow}, {selectAll}等)。

组合键

当使用特殊字符序列时,可以激活修饰键并输入组合键,例如CTRL+RSHIFT+ALT+b。单个组合键可以使用{modifier+key}语法指定。

激活修饰键时会触发keydown事件,释放时会触发keyup事件。

info

你也可以在.click().rightclick().dblclick()中使用组合键,通过它们的选项。更多信息请参阅各自的文档。

输入组合键

// 这与用户按住SHIFT和ALT,然后按b相同
// 在输入'hello'之前释放修饰符
cy.get('input').type('{shift+alt+b}hello')

当单独指定修饰符时,它将在.type()命令的持续时间内保持激活状态,并在所有后续字符输入后释放。但是,可以传递{release: false}作为选项

// 这与用户按住SHIFT和ALT,然后输入'hello'相同
// 修饰符在整个命令期间保持激活。
cy.get('input').type('{shift}{alt}hello')

输入字面量{}字符

要禁用解析特殊字符序列,将parseSpecialCharSequences选项设置为false

cy.get('#code-input')
// 不会转义{ }字符
.type('function (num) {return num * num;}', {
parseSpecialCharSequences: false,
})

按住修饰键并输入单词

// {ctrl}之后的所有字符在其键盘事件中都将设置'ctrlKey'为'true'
cy.get('input').type('{ctrl}test')

释放行为

默认情况下,修饰符在每个type命令后释放。

// 在输入'test'时,'ctrlKey'对每个事件都为true
// 但在输入'everything'时为false
cy.get('input').type('{ctrl}test').type('everything')

要在命令之间保持修饰符激活,在选项中指定{release: false}

// 在输入'foo'时,'altKey'为true
cy.get('input').type('{alt}foo', { release: false })
// 在'get'和'click'命令期间,'altKey'也为true
cy.get('button').click()

修饰符在测试之间自动释放,即使使用{release: false}

it('有激活的修饰符', () => {
// 在输入'foo'时,'altKey'为true
cy.get('input').type('{alt}foo', { release: false })
})

it('没有激活的修饰符', () => {
// 在输入'bar'时,'altKey'为false
cy.get('input').type('bar')
})

要在测试中手动释放使用{release: false}后的修饰符,使用另一个type命令,修饰符将在之后释放。

// 在输入'foo'时,'altKey'为true
cy.get('input').type('{alt}foo', { release: false })
// 在'get'和'click'命令期间,'altKey'为true
cy.get('button').click()
// 在此命令后释放'altKey'
cy.get('input').type('{alt}')
// 在'get'和'click'命令期间,'altKey'为false
cy.get('button').click()

全局快捷键

.type()需要一个可聚焦的元素作为主题,因为它通常用于输入到输入框或文本域中。尽管_有_一些情况下,在非输入框或文本域的元素上"输入"是有效的:

  • 监听器在documentbody上的键盘快捷键。
  • 按住修饰键并点击任意元素。

为了支持这一点,可以使用body作为要输入到的DOM元素(即使它_不是_一个可聚焦的元素)。

在body中使用键盘快捷键

// 所有type事件都在body上触发
cy.get('body').type(
'{upArrow}{upArrow}{downArrow}{downArrow}{leftArrow}{rightArrow}{leftArrow}{rightArrow}ba'
)

执行shift + 点击

// 在第一个<li>上执行SHIFT + 点击
// {release: false}是必要的,以便
// SHIFT不会在type命令后释放
cy.get('body').type('{shift}', { release: false }).get('li:first').click()

选项

强制输入,无论其可操作状态如何

强制输入会覆盖Cypress应用的可操作性检查,并自动触发事件。

cy.get('input[type=text]').type('Test all the things', { force: true })

说明

支持的元素

  • ^HTML <body><textarea>元素。
  • 具有tabindex属性的元素。
  • 具有contenteditable属性的元素。
  • ^HTML <input>元素,具有以下type属性之一:
    • text
    • password
    • email
    • number
    • date
    • week
    • month
    • time
    • datetime-local
    • search
    • url
    • tel

可操作性

.type()是一个"操作命令",遵循可操作性的所有规则。

事件

当元素未聚焦时

如果元素当前未聚焦,Cypress会在发出任何键盘输入之前先发出.click()以使其聚焦。

触发的事件

一旦元素聚焦,Cypress将开始触发键盘事件。

根据按下的键,将触发以下事件,与事件规范相同:

  • keydown
  • keypress
  • beforeinput
  • textInput
  • input
  • keyup

此外,当按下{enter}键(且自上次聚焦事件以来值已更改)或元素失去焦点时,将触发change事件。这与浏览器行为一致。

不应在非输入类型(如具有tabindex的元素)上触发的事件不会触发其textInputinput事件。只有输入到实际导致值或文本更改的元素才会触发这些事件。

事件触发

已实现以下规则以匹配真实浏览器行为(及规范):

  1. Cypress尊重如果先前事件被取消,则不触发后续事件。
  2. Cypress仅在键确实应该触发keypress时才触发keypress
  3. Cypress仅在键入键会插入实际字符时才触发textInput
  4. Cypress仅在键入键修改或更改元素的值时才触发input

事件取消

Cypress尊重所有默认浏览器行为当事件被取消时。

// 通过取消keydown、keypress或textInput阻止字符插入
$('#username').on('keydown', (e) => {
e.preventDefault()
})

// 如果keydown、keypress或textInput被取消,Cypress不会插入任何字符 - 这与默认浏览器行为一致
cy.get('#username').type('bob@gmail.com').should('have.value', '') // true

阻止mousedown不会阻止输入

在真实浏览器中,阻止表单字段上的mousedown会阻止其接收焦点,从而阻止其被输入。目前,Cypress未考虑这一点。提出问题如果你需要修复此问题。

键事件表

Cypress在命令日志中点击type时打印一个键事件表,详细说明按下的键。每个字符将包含which字符码和该按键触发的事件。

defaultPrevented的事件可能会阻止其他事件的触发,这些将显示为空。例如,取消keydown将不会触发keypresstextInputinput,但会触发keyup(这与规范一致)。

此外,导致change事件触发的事件(如键入{enter})将在change事件列中显示为true

任何为事件激活的修饰符也列在modifiers列中。

Cypress .type()键事件表

Tab键

键入tab键无效

目前,你可以使用实验性的cypress-plugin-tab并对此问题点赞。

修饰符

修饰符效果

在真实浏览器中,如果用户按住SHIFT并键入a,输入框中将输入大写的A。目前,Cypress不模拟此行为。

修饰符通过为其对应的事件设置true来模拟。因此,例如,激活{shift}修饰符将为任何键事件(如keydown)设置event.shiftKey为true。

// 应用代码
document.querySelector('input:first').addEventListener('keydown', (e) => {
// e.shiftKey将为true
})

// 在测试中
cy.get('input:first').type('{shift}a')

在上面的示例中,将输入小写的a,因为这是指定的字面字符。要输入大写的A,可以使用.type('{shift}A')(或.type('A')如果你不关心任何键事件上的shiftKey属性)。

这对于其他特殊组合键(可能是操作系统特定的)也是如此。例如,在OSX上,键入ALT + SHIFT + K会创建特殊字符。与大小写一样,.type()不会输出,而是字母k

同样,修饰符不会影响箭头键或删除键。例如{ctrl}{backspace}不会删除整个单词。提出问题如果你需要实现修饰符效果。

表单提交

隐式表单提交行为

当输入属于<form>时,Cypress自动匹配规范并按{enter}键的浏览器行为。

此行为在此定义:表单隐式提交

例如,以下将提交表单。

<form action="/login">
<input id="username" />
<input id="password" />
<button type="submit">Log In</button>
</form>
cy.get('#username').type('bob@burgers.com')
cy.get('#password').type('password123{enter}')

因为有多个inputs和一个submit按钮,Cypress提交表单(并触发提交事件)以及向button触发一个合成的click事件。

规范将"submit"按钮定义为表单中的第一个input[type=submit]button[type!=button]

此外,Cypress处理以下4种情况,如规范所定义:

  1. 如果有多个输入且没有submit按钮,则不提交表单。
  2. 如果submit按钮被禁用,则不提交表单。
  3. 如果有1个input且没有submit按钮,则提交表单,但不触发合成click事件。
  4. 如果存在submit按钮,则提交表单并触发合成click事件。

如果表单的submit事件被preventDefault,表单实际上不会被提交。

规则

要求 了解命令链

  • .type()需要从返回DOM元素(s)的命令链式调用。

断言 了解断言

  • .type()将自动等待元素达到可操作状态
  • .type()将自动重试直到所有链式断言通过。

超时设置 了解超时机制

  • .type()可能因等待元素达到可操作状态而超时。
  • .type()可能因等待你添加的断言通过而超时。

命令日志

在输入框中输入内容

cy.get('input[name=firstName]').type('Jane Lane')

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

命令日志 type

当点击命令日志中的type时,控制台输出以下内容:

控制台日志 type

历史

版本变更
13.14.0添加了对.type({upArrow}).type({downArrow})在日期、月份、周、时间、datetime-local和范围输入类型上的支持
6.1.0添加了scrollBehavior选项
5.6.0支持单键组合语法
5.5.0支持beforeinput事件
3.4.1添加了parseSpecialCharSequences选项
3.3.0添加了{insert}{pageup}{pagedown}字符序列
3.2.0添加了{home}{end}字符序列
0.20.0支持在类型为datetimemonthweek的输入框中输入
0.17.1添加了ctrlcmdshiftalt键盘修饰符
0.16.3支持在具有tabindex属性的元素中输入
0.16.2添加了{downarrow}{uparrow}字符序列
0.8.0点击时在控制台输出键事件表
0.8.0添加了{selectall}{del}{backspace}{esc}{{}{enter}{leftarrow}{rightarrow}字符序列
0.8.0cy.type()期间每次按键之间添加了小延迟(10ms)
0.6.12添加了force选项

另请参阅