Cypress - 基本命令

Cypress - 常用命令概览

Cypress 提供了一系列丰富的命令来与你的 Web 应用进行交互。以下是一些最常用的命令：

.and()

将断言链接到上一个断言。它是 .should() 命令的别名，在对同一主题进行多个断言时可以提高可读性。

用法：

// 元素应该是可见的 AND 可用
cy.get('#submit-button').should('be.visible').and('be.enabled');

// 具有特定值的复选框应该被选中
cy.get('input[type="checkbox"][value="newsletter"]').should('be.checked');

.as()

为一个主题（例如，DOM 元素、网络请求、测试数据）分配一个别名，以便在测试中后续引用。使用 cy.get('@aliasName') 来访问别名。

用法：

// 将第一个列表项起别名为 'firstItem'
cy.get('ul#my-list > li').first().as('firstItem');
// 在测试的后面...
cy.get('@firstItem').should('have.class', 'active');

.blur()

从当前具有焦点的 DOM 元素上移除焦点。

用法：

// 在输入框中输入文本，然后使其失去焦点
cy.get('#username').type('jane.doe').blur();

.check()

选中单选按钮或复选框。适用于 <input type="radio"> 或 <input type="checkbox"> 元素。

用法：

// 选中类为 'terms-checkbox' 的复选框
cy.get('.terms-checkbox').check();

// 选中具有特定值的单选按钮
cy.get('input[type="radio"][value="female"]').check();

.children()

获取一个或一组 DOM 元素的子元素。可以选择提供一个选择器来过滤子元素。

用法：

// 获取 <ul> 的所有直接子元素 <li>
cy.get('ul#main-menu').children('li');

.clear()

清除输入字段或文本区域的值。

用法：

// 在输入框中输入，然后清除它
cy.get('#search-box').type('initial text').clear().should('have.value', '');

cy.clearCookie()

按名称清除特定的浏览器 Cookie。

用法：

// 清除 'session_id' Cookie
cy.clearCookie('session_id');

cy.clearCookies()

清除当前域名和子域名的所有浏览器 Cookie。

用法：

// 在测试前清除所有 Cookie
cy.clearCookies();

cy.clearLocalStorage()

清除当前源（origin）的所有 localStorage 数据。如果提供了键名，也可以清除指定的键。

用法：

// 清除所有 local storage 数据
cy.clearLocalStorage();

// 清除 local storage 中的特定项
cy.clearLocalStorage('userPreferences');

.click()

点击一个 DOM 元素。Cypress 会确保元素是可操作的（actionable）之后再执行点击。

用法：

// 点击 ID 为 'login-btn' 的按钮
cy.get('#login-btn').click();

cy.contains()

获取包含指定文本的 DOM 元素。如果先提供了选择器，它会在这些元素中搜索。

用法：

// 获取包含文本 'Welcome' 的元素
cy.contains('Welcome');

// 在 ID 为 'user-form' 的表单中获取包含文本 'Submit' 的按钮
cy.get('form#user-form').contains('button', 'Submit');

.dblclick()

双击一个 DOM 元素。

用法：

// 双击 ID 为 'edit-icon' 的元素
cy.get('#edit-icon').dblclick();

.debug()

暂停测试并打开浏览器开发者工具，同时记录当前的主题（subject）。对于调试非常有用。

用法：

// 获取元素后暂停并调试
cy.get('#user-profile').debug();

cy.document()

获取当前活动页面的 window.document 对象。

用法：

cy.document().should('have.property', 'charset').and('eq', 'UTF-8');

.each()

遍历一个类数组的主题（例如，DOM 元素集合）。

用法：

// 遍历每个列表项并检查其文本
cy.get('ul#todo-list > li').each(($li, index, $list) => {
  cy.log(`Item ${index}: ${$li.text()}`);
});

.end()

结束当前的命令链。这很少需要，因为 Cypress 命令通常会自然地衔接。如果你暂时更改了主题（例如，在 .within() 块中，尽管 .within() 会自动处理），可以使用它来恢复到之前的主题。

用法：

// 示例：（虽然通常不需要）
cy.get('form').within(() => {
  cy.get('input[name="username"]').type('test');
}).end() // 主题恢复为 'form'
.should('have.class', 'submitted');

.eq()

获取元素集合中特定索引处的 DOM 元素。

用法：

// 获取表格行中的第三个 <td> 元素
cy.get('table#data-table tr:first-child td').eq(2).should('contain', 'Status');

cy.exec()

从项目根目录运行一个系统命令。对于诸如初始化数据库或运行脚本等任务很有用。

用法：

// 示例：运行脚本重置数据库状态
cy.exec('npm run db:reset');

.find()

获取当前主题的后代 DOM 元素，并按选择器进行过滤。

用法：

// 在特定的表格行中查找所有 <td> 元素
cy.get('tr#user-row-123').find('td');

.first()

获取元素集合中的第一个 DOM 元素。

用法：

// 获取每行表格中的第一个 <td>
cy.get('table#data-table tr td').first();

cy.get()

通过选择器或别名获取一个或多个 DOM 元素。这是最基础的命令之一。

用法：

// 按 ID 获取元素
cy.get('#main-content');
// 获取所有类为 'item' 的元素
cy.get('.item');
// 获取别名元素
cy.get('@myAlias');

cy.getCookie()

按名称获取特定的浏览器 Cookie。

用法：

cy.getCookie('user_session').should('have.property', 'value', 'abcdef12345');

cy.getCookies()

获取所有浏览器 Cookie。

用法：

cy.getCookies().should('not.be.empty');

cy.go()

在浏览器的历史记录中向前或向后导航。

用法：

// 返回
cy.go('back');
// 前进
cy.go('forward');
// 后退 2 页
cy.go(-2);

cy.visit()

访问一个远程 URL 或本地 HTML 文件。

用法：

cy.visit('https://www.example.com');
cy.visit('/about-us'); // 相对于 cypress.config.js 中的 baseUrl
cy.visit('app/index.html'); // 本地文件

.next()

获取当前主题的紧随其后的同级 DOM 元素。

用法：

// 获取下一个列表项同级元素
cy.get('li.active-item').next().should('have.class', 'next-item');

.parent()

获取当前主题的父级 DOM 元素。

用法：

// 获取类为 'child-element' 的元素的父级 <div>
cy.get('.child-element').parent('div.parent-container');

.should()

创建一个断言。Cypress 会重试此断言直到它通过或超时。

用法：

// 断言元素可见
cy.get('#error-message').should('be.visible');
// 断言输入框具有特定值
cy.get('#name-input').should('have.value', 'John Doe');

cy.wait()

暂停测试指定毫秒数，或等待别名资源（如网络请求）完成。通常不建议为了任意暂停而使用 cy.wait(milliseconds)；更推荐使用会重试的断言或等待别名路由（aliased routes）。

用法：

// 等待 1 秒（谨慎使用）
cy.wait(1000);

// 等待一个别名网络请求
cy.intercept('GET', '/api/users').as('getUsers');
cy.visit('/users');
cy.wait('@getUsers').its('response.statusCode').should('eq', 200);

cy.title()

获取当前活动页面的 document.title。

用法：

cy.title().should('eq', 'My Application - Dashboard');

cy.viewport()

控制测试期间的屏幕尺寸和方向。可以接受宽/高的数值或预设名称（例如，‘iphone-6’）。

用法：

// 设置视口宽度为 1280px，高度为 720px
cy.viewport(1280, 720);

// 使用预设的视口大小
cy.viewport('macbook-15');

cy.log()

在 Cypress 命令日志（Command Log）中打印消息。对于调试或在测试执行期间提供上下文信息很有用。

用法：

cy.log('Starting login sequence...');
cy.get('#username').type('user');
cy.log('Username entered.');

cy.reload()

重新加载当前页面，类似于浏览器的刷新按钮。

用法：

cy.reload();
// 不使用缓存重新加载
cy.reload(true);