TypeScript Cypress项目：带then功能的自定义命令文档编写规范

你的问题核心是自定义命令的返回值类型标注错误，Cypress的所有自定义命令都返回Chainable<T>类型（而非直接返回原始值），因为Cypress命令是异步链式执行的，不是同步返回结果。

错误原因 #

当前文档里标注返回string，但实际cy.restGetUserId()返回的是包裹了string的Chainable对象，TypeScript类型检查会不匹配，导致报错。

正确的文档写法 #

/**
 * 通过用户邮箱获取对应的用户ID（支持普通用户调用）
 * 
 * @example cy.restGetUserId('some@email.com').then(userId => { /* 使用userId */ });
 * @param userEmail - 用于查询用户ID的邮箱地址
 * @returns 包裹用户ID的Cypress链式对象，需通过`.then()`提取实际值
 */
restGetUserId(userEmail: string): Cypress.Chainable<string>;

额外说明 #

你的命令实现本身没问题，cy.wrap(response.body.id)确实会把ID包装成Chainable返回，和修正后的文档类型一致，这样TypeScript就能正确识别类型，不会再报错。

内容的提问来源于stack exchange，提问作者Bambi