UnexpectedJS 迁移指南：从旧版本升级到 v11 的最佳实践

2025-07-06 02:17:20作者：齐冠琰

前言

UnexpectedJS 作为一个专注于测试领域的断言库，始终将向后兼容性视为核心设计原则。本文旨在帮助开发者理解从旧版本迁移到 Unexpected v11 时需要注意的关键变化，并提供详细的迁移策略。

版本兼容性策略

Unexpected 严格遵循语义化版本控制（Semver），这意味着：

主版本号变更包含不兼容的 API 修改
次版本号新增向下兼容的功能
修订号仅包含向下兼容的问题修正

v11 是首个包含用户可见 API 变更的主版本，这些变更都经过精心设计，以最小化对现有测试套件的影响。

环境要求变化

Node.js 版本要求

v11 将最低 Node.js 版本要求提升至 6.x 以上，主要原因包括：

核心依赖库已放弃对 Node 4 的支持
需要利用 ES6+ 特性改进代码质量
提升开发工具链效率

注意：浏览器兼容性保持不变，仍支持 ES5 和 IE11。

API 变更详解

1. 扩展机制变更

旧版本行为：

const unexpected = require('unexpected');
// 直接添加断言
unexpected.addAssertion(...);

v11 新规范：

const unexpected = require('unexpected');
// 必须先克隆实例
const expect = unexpected.clone();  
expect.addAssertion(...);

技术背景：这种变更防止了全局污染问题，确保扩展操作具有明确的上下文边界。通过冻结顶层 API，避免了意外修改全局状态的风险。

2. 属性断言语法升级

旧模式（已废弃）：

expect(obj, 'to satisfy', {
  greeting: function(value) {
    expect(value, 'to start with', 'hello');
  }
});

新模式（推荐）：

expect(obj, 'to satisfy', {
  greeting: expect.it(function(value) {
    expect(value, 'to start with', 'hello');
  })
});

优势分析：

更清晰的语义表达
支持链式调用：

expect.it('to be string')
  .and('to match', /pattern/)
  .and(value => {...})

更好的类型安全性
更一致的 API 设计

3. 函数比较语义变化

重要变更： v11 开始，所有函数比较都基于严格相等（===）而非特殊处理。

典型场景示例：

// 旧版本会通过（不推荐）
expect(throwingFn, 'to throw error', ErrorConstructor);

// v11 正确写法
expect(throwingFn, 'to throw error', 
  expect.it('to be an', ErrorConstructor));

影响范围：

对象属性比较
数组元素比较
所有包含函数比较的断言

4. 废弃特性移除

已移除功能：

expect.async 辅助方法
- 替代方案：使用 Promise 或 async/await
this.errorMode 语法
- 替代方案：使用 expect.errorMode

迁移示例：

// 废弃写法
expect.addAssertion('...', function(expect, subject) {
  this.errorMode = 'nested';
  // ...
});

// 新写法
expect.addAssertion('...', (expect, subject) => {
  expect.errorMode = 'nested';
  // ...
});