Cypress v12.15中@getTexts别名找不到问题修复请求

问题背景 #

升级至Cypress v12.15后，仅第一个测试用例INFOBOX出现cy.wait()无法找到@getTexts别名的错误，第二个测试用例VIEW无异常，此前版本未出现该问题。

相关代码 #

测试文件代码

import { TEXTS_ALIAS } from "./constants";

describe(`Check page`, () => {
  beforeEach(() => {
    let endpoint, fixture;
    switch (Cypress.currentTest.title) {
      case "INFOBOX":
        endpoint = "/api/q4/summary/";
        fixture = "q4/infobox.json";
        break;
      case "VIEW":
        endpoint = "/api/q4/resources/";
        fixture = "q4/resources.json";
        break;
      default:
        break;
    }

    if (endpoint) {
      cy.intercept(endpoint, { fixture }).as("getData");
    }
    cy.interceptTexts();
  });

  it(`INFOBOX`, function () {
    cy.visit("/resources");
    cy.wait([TEXTS_ALIAS, "@getData"]);
    ...
  });

  it(`VIEW`, function () {
    cy.visit("/resources");
    cy.wait([TEXTS_ALIAS, "@getData"]);
    ...
  });
});

自定义命令commands.js代码

import { TEXTS_ALIAS_NAME } from "../e2e/constants";

/**
 * @memberOf cy
 * @method interceptTexts
 * @returns undefined
 */
Cypress.Commands.add("interceptTexts", () => {
  cy.intercept("/api/texts/", { fixture: "texts.json" }).as(TEXTS_ALIAS_NAME);
});

常量文件constants.js代码

export const TEXTS_ALIAS_NAME = "getTexts";
export const TEXTS_ALIAS = "@getTexts";

错误信息 #

INFOBOX:
CypressError: `cy.wait()` could not find a registered alias for: `@getTexts`.
You have not aliased anything yet.
  at $Cy.aliasNotFoundFor (http://localhost:3000/__cypress/runner/cypress_runner.js:140235:74)
  at $Cy.getAlias (http://localhost:3000/__cypress/runner/cypress_runner.js:140178:12)
  at waitForXhr (http://localhost:3000/__cypress/runner/cypress_runner.js:151465:23)
  at <unknown> (http://localhost:3000/__cypress/runner/cypress_runner.js:151568:14)
  at tryCatcher (http://localhost:3000/__cypress/runner/cypress_runner.js:18744:23)
  at MappingPromiseArray._promiseFulfilled (http://localhost:3000/__cypress/runner/cypress_runner.js:15864:38)
  at PromiseArray._iterate (http://localhost:3000/__cypress/runner/cypress_runner.js:17066:31)
  at MappingPromiseArray.init (http://localhost:3000/__cypress/runner/cypress_runner.js:17030:10)
  at MappingPromiseArray._asyncInit (http://localhost:3000/__cypress/runner/cypress_runner.js:15833:10)
  at _drainQueueStep (http://localhost:3000/__cypress/runner/cypress_runner.js:13455:12)
  at _drainQueue (http://localhost:3000/__cypress/runner/cypress_runner.js:13444:9)
  at ../../node_modules/bluebird/js/release/async.js.Async._drainQueues (http://localhost:3000/__cypress/runner/cypress_runner.js:13460:5)
  at Async.drainQueues (http://localhost:3000/__cypress/runner/cypress_runner.js:13330:14)
From Your Spec Code:
  at Context.eval (webpack:///./cypress/e2e/q4-worldwide-resources.cy.js:69:7)

问题原因 #

Cypress v12+ 对别名注册的时序和测试上下文隔离做了更严格的校验：

1. beforeEach中依赖Cypress.currentTest.title的分支判断，在第一个测试用例初始化时可能存在上下文绑定延迟
2. 自定义命令cy.interceptTexts()未明确返回异步执行结果，导致后续cy.visit和cy.wait提前执行时，别名尚未完成注册

修复方案 #

方案1：优化测试配置逻辑（推荐） #

将测试用例的拦截配置提前定义，避免在beforeEach中依赖动态判断，确保所有别名在页面访问前完成注册：

import { TEXTS_ALIAS } from "./constants";

describe(`Check page`, () => {
  // 预定义每个测试用例的拦截配置
  const testConfigs = {
    INFOBOX: { endpoint: "/api/q4/summary/", fixture: "q4/infobox.json" },
    VIEW: { endpoint: "/api/q4/resources/", fixture: "q4/resources.json" }
  };

  beforeEach(function() {
    // 通过当前测试用例上下文获取配置，避免动态判断的时序问题
    const config = testConfigs[this.currentTest.title];
    if (config) {
      cy.intercept(config.endpoint, { fixture: config.fixture }).as("getData");
    }
    // 确保文本拦截别名注册完成
    cy.interceptTexts();
  });

  it(`INFOBOX`, function () {
    cy.visit("/resources");
    cy.wait([TEXTS_ALIAS, "@getData"]);
    ...
  });

  it(`VIEW`, function () {
    cy.visit("/resources");
    cy.wait([TEXTS_ALIAS, "@getData"]);
    ...
  });
});

方案2：修改自定义命令确保异步完成 #

让interceptTexts命令返回执行结果，确保别名注册完成后再执行后续步骤：

// commands.js
import { TEXTS_ALIAS_NAME } from "../e2e/constants";

Cypress.Commands.add("interceptTexts", () => {
  // 返回链式调用结果，确保命令执行完成后再继续
  return cy.intercept("/api/texts/", { fixture: "texts.json" }).as(TEXTS_ALIAS_NAME);
});

在beforeEach中等待命令完成：

beforeEach(() => {
  let endpoint, fixture;
  switch (Cypress.currentTest.title) {
    case "INFOBOX":
      endpoint = "/api/q4/summary/";
      fixture = "q4/infobox.json";
      break;
    case "VIEW":
      endpoint = "/api/q4/resources/";
      fixture = "q4/resources.json";
      break;
    default:
      break;
  }

  if (endpoint) {
    cy.intercept(endpoint, { fixture }).as("getData");
  }
  // 等待文本拦截别名注册完成
  cy.interceptTexts();
});

方案3：兜底方案——将别名注册移到测试用例内 #

如果上述方案无效，可直接在测试用例内注册别名，确保绑定到当前测试上下文：

it(`INFOBOX`, function () {
  cy.interceptTexts();
  cy.visit("/resources");
  cy.wait([TEXTS_ALIAS, "@getData"]);
  ...
});

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