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()
期间触发的事件中传递正确的keyCode
、key
和which
码。一些特殊字符序列在输入时可能会执行操作,如{moveToEnd}
、{moveToStart}
或{selectAll}
。
要禁用解析特殊字符序列,请将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()
的默认行为。
选项 | 默认值 | 说明 |
---|---|---|
animationDistanceThreshold | animationDistanceThreshold | 元素必须随时间超过的像素距离才能被视为动画。 |
delay | 10 | 每次按键后的延迟 |
force | false | 强制操作,禁用等待可操作性 |
log | true | 在命令日志中显示命令 |
parseSpecialCharSequences | true | 解析由{} 包围的特殊字符,如{esc} 。设置为false 以输入字面字符 |
release | true | 在命令之间保持修饰符激活 |
scrollBehavior | scrollBehavior | 在执行命令前,元素应滚动到的视口位置 |
timeout | defaultCommandTimeout | 等待.type() 解析的时长,超过则超时 |
waitForAnimations | waitForAnimations | 是否在命令执行前等待元素完成动画。 |
生成结果
.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-dd
是W3规范要求的格式,无论浏览器或地区如何,输入框的value
都将设置为该格式。
{upArrow}
和{downArrow}
可以根据提供的"step"参数增加和减少日期值。使用.type()
与{upArrow}
和{downArrow}
模拟了stepUp
和stepDown
输入方法的行为。
不允许使用特殊字符({leftArrow}
, {selectAll}
等)。
月份输入
在月份输入框(<input type="month">
)上使用.type()
需要指定以下格式的有效月份:
yyyy-MM
(例如1999-12
)
这并不是用户输入月份输入框的确切方式,但由于月份输入支持因浏览器和地区而异,这是一个变通方法。yyyy-MM
是W3规范要求的格式,无论浏览器或地区如何,输入框的value
都将设置为该格式。
{upArrow}
和{downArrow}
可以根据提供的"step"参数增加和减少月份值。使用.type()
与{upArrow}
和{downArrow}
模拟了stepUp
和stepDown
输入方法的行为。
不允许使用特殊字符({leftArrow}
, {selectAll}
等)。
周输入
在周输入框(<input type="week">
)上使用.type()
需要指定以下格式的有效周:
yyyy-Www
(例如1999-W23
)
其中W
是字面字符'W',ww
是周数(01-53)。
这并不是用户输入周输入框的确切方式,但由于周输入支持因浏览器和地区而异,这是一个变通方法。yyyy-Www
是HTML规范要求的格式,无论浏览器或地区如何,输入框的value
都将设置为该格式。
不允许使用特殊字符({leftArrow}
, {selectAll}
等)。
{upArrow}
和{downArrow}
可以根据提供的"step"参数增加和减少周值。使用.type()
与{upArrow}
和{downArrow}
模拟了stepUp
和stepDown
输入方法的行为。
时间输入
在时间输入框(<input type="time">
)上使用.type()
需要指定以下格式的有效时间:
HH:mm
(例如01:30
或23: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}
模拟了stepUp
和stepDown
输入方法的行为。
不允许使用特殊字符({leftArrow}
, {selectAll}
等)。
组合键
当使用特殊字符序列时,可以激活修饰键并输入组合键,例如CTRL+R
或SHIFT+ALT+b
。单个组合键可以使用{modifier+key}
语法指定。
激活修饰键时会触发keydown
事件,释放时会触发keyup
事件。
你也可以在.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()
需要一个可聚焦的元素作为主题,因为它通常用于输入到输入框或文本域中。尽管_有_一些情况下,在非输入 框或文本域的元素上"输入"是有效的:
- 监听器在
document
或body
上的键盘快捷键。 - 按住修饰键并点击任意元素。
为了支持这一点,可以使用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
的元素)上触发的事件不会触发其textInput
或input
事件。只有输入到实际导致值或文本更改的元素才会触发这些事件。
事件触发
已实现以下规则以匹配真实浏览器行为(及规范):
- Cypress尊重如果先前事件被取消,则不触发后续事件。
- Cypress仅在键确实应该触发
keypress
时才触发keypress
。 - Cypress仅在键入键会插入实际字符时才触发
textInput
。 - 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