升级到 Jasmine 5.0

概述

大多数用户无需进行任何更改即可升级到 Jasmine 5.0。但它确实包含一些重大的更改，这些更改会影响某些用户。按照此指南中的建议操作，可以最大程度地保证顺畅的升级体验。

Jasmine 5.0 中的重大变化包括 Windows 上文件匹配模式中反斜杠处理方式的更改、Env#execute 调用方式的更改、基于 Node 的库启动 jasmine-core 方式的更改以及系统要求的更改。你可以在 jasmine-core 和 jasmine 的版本说明中找到重大变化的完整列表。

建议所有用户升级到最新的 4.x 版本，并在升级到 5.0 之前解决任何错误或弃用警告。特别是，在 Windows 上使用 jasmine 包的人员应先至少升级到 4.5.0，因为该版本添加了一个重要的弃用警告，会影响 Windows 用户。出于同样的原因，在 Windows 上使用 jasmine-browser-runner 包的人员应将其包至少升级到 1.3.0，然后再将其升级到 2.0。

Jasmine 5.0 中引入的新并行执行模式对规范和报告程序的编写方式带来了更多限制。这些限制仅在以并行模式运行 Jasmine 时才适用。有关详细信息，请参阅并行执行指南。

系统要求

不再支持以下以前支持的环境

Node <18
Safari 14
Firefox 91

虽然 Jasmine 5.0 在某些环境中可能仍然可以工作，但我们不再对其进行测试，并且不会尝试在以后的 5.x 版本中保持与此类环境的兼容性。

升级 jasmine-browser-runner

如果你正在使用 jasmine-browser-runner，请升级到 2.0 版。除非你的 package.json 指定早期版本，否则包管理器 (npm/yarn/等) 应自动安装 jasmine-core 5.0 或更高版本。

Windows 上反斜杠处理的更改

从历史上看，诸如 spec_files 配置属性等文件 glob 中的反斜杠在 Windows 上被视为目录分隔符，而在其他操作系统上则被视为转义序列的开头。从 jasmine 5.0 和 jasmine-browser-runner 2.0 开始，它们在所有操作系统中都将被视为转义序列的开头。此更改使 Jasmine 配置文件更具可移植性，并确保 Windows 用户可以指定碰巧匹配特殊 glob 语法的文件名。有关更多信息，请参阅 glob 包的 changelog 和 README。

与反斜杠相关的弃用警告已添加到 jasmine 4.6.0 和 jasmine-browser-runner 1.3.0 中。Windows 用户应升级到这些版本或更高版本，并在升级到 jasmine 5.x 或 jasmine-browser-runner 2.x 之前解决所有弃用警告。

对并行执行的支持

5.0 中最大的更改是通过 jasmine 包支持在 Node.js 中并行执行。并行执行对测试套件和报告器都施加了一些约束，因此并非每个人在不进行更改的情况下都能采用它。有关更多信息，请参阅并行运行规范。

浏览器中全局错误处理的更改

早期版本的 Jasmine 通过安装 window.onerror 处理程序来检测浏览器中未处理的异常和未处理的 Promise 拒绝。5.0 及更高版本则使用 addEventListener。这意味着 Jasmine 不会再覆盖您的代码在启动之前安装的任何错误处理程序。这也意味着您无法再通过设置 window.onerror 来覆盖 Jasmine 的全局错误处理。如果您需要覆盖 Jasmine 的全局错误处理，请使用 spyOnGlobalErrors。

使用 addEventListener 使 Jasmine 在许多情况下能够提供更好的错误信息。但是，当错误源从 file:// URL 加载时，有些浏览器会限制提供给错误侦听器的信息。如果您使用的是独立发行版，通过 Web 服务器加载 Jasmine 可能更容易调试未处理的异常和 Promise 拒绝。一种简单的方法是从包含 SpecRunner.html 的目录运行 npx serve。

对 `Env#execute` 的更改

Jasmine 5.0 已完成 Env#execute 到 async/await 的迁移。大多数用户无需关心该功能，因为他们既不会直接调用 Env#execute，也不会将其用于“消防演习”模式。然而，任何将回调传递给 Env#execute 或从此回调捕获异常的用户都可能需要进行更改。

之前

try {
    env.execute(null, function () {
        // Handle completion
    });
} catch (e) {
    // Handle failures to start
}

之后

try {
    const jasmineDoneInfo = await env.execute();
} catch (e) {
    // Handle failures to start, which are now delivered via promise rejection
    // rather than synchronous throw
}

给库作者的提示

“之后”的格式可与 jasmine-core 4.0.0 及更高版本配合使用，或者与 3.9.0 及更高版本配合使用（若您忽略 promise 求解的值）。

移除 `node_boot.js`

这一更改主要影响在 Node.js 中包装 jasmine-core 的库的作者，而不是最终用户。在 5.0 之前，用于在 Node 中初始化 jasmine-core 的 boot 函数是通过 jasmine-core/node_boot.js 提供的，同时在 jasmine-core 模块本身上也导出。5.0 中不再存在 node_boot.js。

之前

const boot = require('jasmine-core/node_boot.js');

之后

const boot = require('jasmine-core').boot;

“之后”的版本应可在支持 Node.js 的所有版本的 jasmine-core 中运行。