如何调整Cypress自定义getByRole命令以支持检测元素不存在？

使用以下自定义命令：

Cypress.Commands.add('getByRole', (role, options): Chainable<JQuery<HTMLElement>> => {
  return cy.get('[role]').filter((_, element) => {
    const roles = element.getAttribute('role').split(' ');
    return roles.includes(role);
  }, options);
});

当目标元素存在时，命令可以正常工作：

cy.getByRole('alert').should('exist'); // 正常运行

但当检测不应存在的元素时，命令执行失败：

cy.getByRole('alert').should('not.exist'); // 执行失败

抛出的错误为：Timed out retrying after 4000ms: Expected to find element: [role], but never found it.

问题根源 #

原命令中cy.get('[role]')默认会在找不到匹配元素时直接抛出错误，导致后续的过滤逻辑根本无法执行。当页面中没有任何带有role属性的元素时，这一步就直接失败，无法继续验证特定role的元素是否不存在。

解决方案 #

方案1：修改cy.get的默认行为 #

给cy.get('[role]')添加failOnNotFound: false选项，允许Cypress在找不到元素时返回空集合而非报错，之后的过滤逻辑可以正常处理空集合，最终支持should('not.exist')断言。

修改后的命令：

Cypress.Commands.add('getByRole', (role, options): Chainable<JQuery<HTMLElement>> => {
  // 合并传入的options与failOnNotFound配置
  const getOptions = { ...options, failOnNotFound: false };
  return cy.get('[role]', getOptions).filter((_, element) => {
    const roles = element.getAttribute('role').split(' ');
    return roles.includes(role);
  });
});

方案2：直接基于DOM查询实现 #

绕开cy.get的默认限制，直接通过文档查询元素并过滤，确保无论是否存在带role的元素，逻辑都能正常执行：

Cypress.Commands.add('getByRole', (role, options): Chainable<JQuery<HTMLElement>> => {
  return cy.document().then(doc => {
    // 查询所有带role属性的元素，再过滤出包含目标role的项
    const matchedElements = Array.from(doc.querySelectorAll('[role]')).filter(element => {
      const roles = element.getAttribute('role').split(' ');
      return roles.includes(role);
    });
    // 将结果包装为Cypress可链式调用的对象
    return cy.wrap(matchedElements, options);
  });
});

两种方案均能解决问题：当目标role的元素不存在时，命令会返回空集合，should('not.exist')断言可以正常通过。

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