Jasmine/Karma 测试中模拟全局 window 对象属性的最佳实践

本文探讨在 Jasmine 和 Karma 单元测试环境中，如何有效模拟 window 对象上定义的外部库或全局属性。针对常见的模拟失败尝试，文章提出并详细阐述了使用 beforeEach 和 afterEach 生命周期钩子直接赋值来创建临时模拟对象的最佳实践，确保测试隔离性，并提供代码示例和注意事项，帮助开发者构建健壮的单元测试。

模拟全局 window 对象属性的挑战

在 javascript 应用开发中，尤其是在构建 sdk 或集成第三方库时，我们经常会遇到通过 window 对象暴露的全局属性或方法。例如，一个外部库可能将其功能封装在 window.ats 对象中。在进行单元测试时，为了隔离被测代码与外部依赖，模拟这些全局属性是必不可少的。然而，直接使用 jasmine 的 spyon 方法来模拟 window 对象上的非方法属性或尚未存在的对象可能会遇到挑战。

常见的模拟尝试可能包括：

1. spyOn(window.ats, 'retrieveEnvelope'): 这种方法假设 window.ats 对象及其 retrieveEnvelope 方法已经存在。如果 window.ats 在测试环境中不存在，或者你想要模拟整个 ats 对象，这种方法就不适用。
2. spyOn(window, 'ats'): spyOn 主要用于监视或替换对象上的方法。尝试对 window 对象上的一个属性（而非方法）使用 spyOn 来替换其整个值，通常无法达到预期效果。
3. Object.defineProperty 或创建临时 window 对象：虽然 Object.defineProperty 可以修改属性，但它可能不够简洁，且在测试框架中可能需要更复杂的清理逻辑。直接替换 window 对象本身（如 window = Object.create(window)）在浏览器环境中是不可行的，因为它是一个宿主对象，通常不允许被重新赋值。

这些方法之所以无效，根本原因在于它们没有正确处理 window 对象作为全局宿主环境的特殊性，或者混淆了 spyOn 的使用场景（通常用于方法而非整个对象属性的替换）。

最佳实践：利用 beforeEach 和 afterEach 直接赋值

针对模拟 window 对象上外部库或全局属性的需求，最直接且有效的方法是在每个测试用例运行之前，通过直接赋值的方式在 window 对象上创建或覆盖所需的模拟对象，并在每个测试用例运行之后进行清理。Jasmine 提供了 beforeEach 和 afterEach 这两个生命周期钩子，非常适合实现这种模式。

实现步骤：

1. 在 beforeEach 中设置模拟对象： 在每个测试用例开始执行之前，将你希望模拟的 window 属性（例如 window.ats）直接赋值为一个包含模拟逻辑的对象。
2. 在 afterEach 中清理： 在每个测试用例执行完毕之后，将该 window 属性重置为 undefined 或其原始值，以确保测试之间的隔离性，避免一个测试的模拟状态影响到后续的测试。

示例代码：

假设我们有一个方法 getFromATS 依赖于 window.ats.retrieveEnvelope：

// 原始代码片段
class MySDK {
  private getFromATS(): string {
    return window.ats.retrieveEnvelope(function (envelope: string) {
      console.log('Located ATS.js');
      return JSON.parse(envelope).envelope;
    });
  }

  // ... 其他方法
}

现在，我们可以这样编写其单元测试：

describe('MySDK', () => {
  let mySDK: MySDK; // 假设 MySDK 是要测试的类

  // 定义一个接口，以便在 TypeScript 中正确类型化模拟对象
  interface MockATS {
    retrieveEnvelope: (callback: (envelope: string) => any) => any;
  }

  // 在每个测试用例运行前设置模拟的 window.ats
  beforeEach(() => {
    // 确保 MySDK 实例在模拟对象设置后创建，以使用模拟的 window.ats
    mySDK = new MySDK(); 

    // 直接在 window 对象上定义模拟的 ats
    // 使用 as any 绕过 TypeScript 的类型检查，因为我们正在模拟全局对象
    (window as any).ats = {
      retrieveEnvelope: function (callback: (envelope: string) => any) {
        // 模拟 retrieveEnvelope 的行为，例如返回一个预设的 JSON 字符串
        return callback('{"envelope":"mocked_envelope_data"}');
      },
    } as MockATS; // 明确类型为 MockATS
  });

  // 在每个测试用例运行后清理 window.ats
  afterEach(() => {
    // 将 window.ats 重置为 undefined，确保测试隔离
    (window as any).ats = undefined;
  });

  it('should retrieve envelope from mocked ATS', () => {
    // 假设 MySDK 有一个 public 方法调用 getFromATS
    // 或者直接测试 getFromATS (如果它是 public 的)
    // const result = mySDK.somePublicMethodThatCallsGetFromATS();
    // expect(result).toBe('mocked_envelope_data');

    // 如果 getFromATS 是 private 的，你需要测试其公共接口，或者在测试时将其临时改为 public
    // 这里我们假设可以某种方式触发 getFromATS
    const privateGetFromATS = (mySDK as any).getFromATS; // 临时访问 private 方法
    const result = privateGetFromATS.call(mySDK); // 调用私有方法

    expect(result).toBe('mocked_envelope_data');
    // 你也可以使用 Jasmine.createSpy 来进一步控制和验证模拟方法的调用
    // spyOn((window as any).ats, 'retrieveEnvelope').and.callThrough();
    // ... 然后验证 spy 被调用
  });

  // 更多测试用例...
});

工作原理：

• 直接赋值： window.ats = {...} 操作符会直接在全局 window 对象上创建或覆盖 ats 属性。这正是我们希望模拟外部库存在时的行为。
• beforeEach 的作用： 确保在每个 it 块（测试用例）执行之前，window.ats 都已经被设置为我们定义的模拟对象。这样，被测代码在执行时总能找到并使用这个模拟的 ats 对象。
• afterEach 的作用： afterEach 至关重要，它保证了每个测试用例结束后，window.ats 被重置。这避免了“测试泄漏”——即一个测试用例中对全局状态的修改影响到后续测试用例的结果，从而维护了测试的独立性和可靠性。

注意事项与总结

1. 测试隔离性： afterEach 的清理步骤是确保测试隔离的关键。如果省略这一步，一个测试用例中设置的 window.ats 模拟可能会意外地影响到下一个测试用例，导致测试结果不稳定或难以调试。
2. TypeScript 类型： 在 TypeScript 项目中，直接对 window 对象进行属性赋值可能会遇到类型错误。可以使用类型断言 (window as any).propertyName 来绕过类型检查，或者为模拟对象定义接口以提供更好的类型提示。
3. 适用场景： 这种直接赋值模拟的方法适用于模拟简单的全局对象或属性。对于更复杂的场景，例如需要模拟 window.location、window.localStorage 等浏览器 API，或者当你的代码设计已经采用了依赖注入（Dependency Injection, DI）模式时，通常会有更优雅和可维护的解决方案。例如，将 window 对象作为参数传入函数或类中，然后在测试时传入一个模拟的 window 对象。虽然本教程的初始需求是避免修改主代码，但在大型复杂应用中，采用 DI 模式通常是更好的长期选择。
4. spyOn 的局限性： 再次强调，spyOn 主要用于监视或替换对象上的 方法。如果你需要模拟一个 不存在 的全局对象，或者需要替换整个对象而不仅仅是其方法，直接赋值是更合适的选择。

通过在 beforeEach 中设置模拟对象并在 afterEach 中清理，我们可以在 Jasmine 和 Karma 测试环境中有效且安全地模拟 window 对象上的外部库和全局属性，从而实现高质量的单元测试。