Ember-QUnit 迁移指南：从旧版本到现代测试实践

概述

Ember-QUnit 是 Ember.js 生态系统中重要的测试工具，随着框架的发展，其 API 也经历了多次重大变革。本文将详细介绍从旧版本迁移到现代测试实践的关键步骤和注意事项，帮助开发者平滑过渡。

迁移到 v6.1.0 的 TypeScript 原生支持

类型系统变更的背景

在 v6.1.0 版本中，Ember-QUnit 引入了对 TypeScript 的原生支持，这带来了更严格的类型检查。之前的类型定义为了开发便利性，允许在测试上下文中访问所有可能的属性和方法，而不管实际测试设置中是否真的可用。

具体变更内容

新的类型系统会严格检查 this 上下文中的可用成员。例如，在渲染测试中访问 this.element 时，如果未正确声明测试上下文类型，将会产生类型错误。

解决方案

方案一：显式声明上下文类型

import type { RenderingTestContext } from '@ember/test-helpers';

test('greets', async function(this: RenderingTestContext, assert) {
  await render(hbs`<Greeting />`);
  assert.equal(this.element.textContent?.trim(), 'Hello!');
});

方案二：使用 qunit-dom 替代

更推荐的做法是使用 qunit-dom 这样的断言库，它提供了更友好的 API 且无需处理上下文类型问题：

test('greets', async function(assert) {
  await render(hbs`<Greeting />`);
  assert.dom().hasText('Hello!');
});

类型系统变更的意义

虽然这种更严格的类型检查可能会带来一些迁移成本，但它能有效防止开发者在编写测试时使用实际上不可用的 API，提高了代码的健壮性。

从 v4.x 迁移到 v5.0.0

重大变更概述

v5.0.0 版本包含了多项重大变更，主要涉及依赖管理、测试基础设施和 API 设计：

1. 依赖关系调整
2. DOM 测试基础设施变更
3. 废弃旧版 API
4. Node.js 版本支持调整

详细迁移步骤

1. 处理依赖关系变更

v5 将 qunit 和 @ember/test-helpers 从直接依赖改为 peer 依赖，需要手动安装：

npm install --save-dev qunit "@ember/test-helpers"
# 或
yarn add --dev qunit "@ember/test-helpers"

2. 配置 DOM 测试基础设施

在 tests/index.html 中添加必要的 DOM 结构：

<div id="qunit"></div>
<div id="qunit-fixture">
  <div id="ember-testing-container">
    <div id="ember-testing"></div>
  </div>
</div>

3. QUnit DOM 配置

如果使用 QUnit DOM，需要在 test-helper.js 中初始化：

import * as QUnit from 'qunit';
import { setup } from 'qunit-dom';

setup(QUnit.assert);

4. 废弃 API 处理

• 将 ember-test-helpers 导入改为 @ember/test-helpers
• 完全移除 moduleFor* 系列 API

迁移旧版测试代码

单元测试迁移示例

旧版代码：

moduleFor('controller:sidebar', 'SidebarController');

test('exists', function(assert) {
  let controller = this.subject();
  assert.ok(controller);
});

新版代码：

module('SidebarController', function(hooks) {
  setupTest(hooks);

  test('exists', function(assert) {
    let controller = this.owner.lookup('controller:sidebar');
    assert.ok(controller);
  });
});

组件测试迁移示例

旧版代码：

moduleForComponent('GravatarImageComponent', {
  integration: true
});

test('it renders', function(assert) {
  this.render(hbs`{{gravatar-image}}`);
  assert.equal(this.$('img').length, 1);
});

新版代码：

module('GravatarImageComponent', function(hooks) {
  setupRenderingTest(hooks);

  test('renders', async function(assert) {
    await render(hbs`{{gravatar-image}}`);
    assert.ok(this.element.querySelector('img'));
  });
});

验收测试迁移示例

旧版代码：

moduleForAcceptance('basic acceptance test');

test('can visit /', function() {
  visit('/');
  andThen(() => {
    assert.equal(currentURL(), '/');
  });
});

新版代码：

module('basic acceptance test', function(hooks) {
  setupApplicationTest(hooks);

  test('can visit /', async function(assert) {
    await visit('/');
    assert.equal(currentURL(), '/');
  });
});

迁移注意事项

1. 异步处理：新版 API 全面采用 async/await 模式，移除了 andThen 辅助函数
2. DOM 操作：不再依赖 jQuery，推荐使用原生 DOM API 或测试辅助方法
3. 测试上下文：使用 setupTest、setupRenderingTest 和 setupApplicationTest 明确区分不同类型的测试
4. 全局变量：Ember.testing 现在只在测试运行时设置为 true

迁移工具推荐

虽然本文提供了手动迁移的指南，但对于大型项目，可以考虑使用以下自动化迁移工具：

1. ember-qunit-codemod：自动转换测试模块结构
2. ember-test-helpers-codemod：转换测试辅助方法调用

总结

Ember-QUnit 的现代化演进带来了更清晰、更类型安全的测试 API，虽然迁移过程可能需要一些投入，但最终会带来更健壮、更易维护的测试代码。建议开发者按照本文指南逐步迁移，充分利用新版本提供的优势。