测试

¥Testing

TLDR

运行 just test-update 以运行所有测试并自动更新快照

¥run just test-update to run all tests and update snapshots automatically

我们有两组测试套件：一个用于 Rust，一个用于 Node.js。

¥We have two groups of test suites: one for Rust, and one for Node.js.

你应该遵循的测试原则

1. 添加带有选项的新功能时，请尽可能在 JavaScript 端添加相关测试。

   ¥When adding new feature with options, always make sure adding related tests in JavaScript side if possible.

以下是如何选择测试技术 details\ 的一些细节

¥Here is some details about how to choose test technique details\

摘要

¥Summary

• just test 表示运行所有测试。

  ¥just test for running all tests.

• just test-update 运行所有测试并自动更新快照

  ¥just test-update running all tests and update snapshots automatically

• just test-rust 表示运行所有 Rust 测试。

  ¥just test-rust for running all Rust tests.

• just test-node 表示运行所有 Node.js 测试。

  ¥just test-node for running all Node.js tests.

• just test-node-rolldown 表示仅运行 Rolldown 的 Node.js 测试。

  ¥just test-node-rolldown for running only Rolldown's Node.js tests.

• just test-node-rollup 表示仅运行 Rollup 的测试。

  ¥just test-node-rollup for running only Rollup's tests.

Rust 测试

¥Rust Tests

Rust 测试用例存储在

¥Rust tests cases are stored in

• /crates/rolldown/tests/esbuild

• /crates/rolldown/tests/fixtures

如何定义测试用例

¥How test cases are defined

测试用例是包含 _config.json 的文件夹。

¥A test case is a folder that contains _config.json.

_config.json 包含测试套件的配置。如果一切正常，由于 config，你应该能够在编辑 _config.json 时启用自动补齐功能。

¥_config.json contains the configuration for the test suite. If everything works right, you should be able to have auto-completion while editing _config.json due to the config.

所有可用选项，你可以参考

¥For all available options, you could refer to

• https://github.com/rolldown/rolldown/blob/main/crates/rolldown_testing_config/src/lib.rs

• https://github.com/rolldown/rolldown/blob/main/crates/rolldown_common/src/inner_bundler_options/mod.rs

• https://github.com/rolldown/rolldown/blob/main/crates/rolldown_testing/_config.schema.json

• 如果 _config.json 中未指定 config.input，则 main.js 是测试用例的默认入口。

  ¥main.js is the default entry of the test case, if config.input is not specified in _config.json.

• Rolldown 会将输入打包到 /dist 中，并按顺序执行 /dist 中的每个入口文件。你可能认为这是在运行 node --import ./dist/entry1.mjs --import ./dist/entry2.mjs --import ./dist/entry3.mjs --eval ""。

  ¥Rolldown will bundle the input into /dist, and execute every entry file in /dist orderly. You might thinking it as running node --import ./dist/entry1.mjs --import ./dist/entry2.mjs --import ./dist/entry3.mjs --eval "".

  • 如果测试用例文件夹中包含 _test.mjs/_test.cjs，则只会执行 _test.mjs/_test.cjs。如果你想执行已编译的条目，则需要在 _test.mjs/_test.cjs 中手动导入它们。

    ¥If there is a _test.mjs/_test.cjs in the test case folder, only _test.mjs/_test.cjs will be executed. If you want to execute compiled entries, you need to import them manually in _test.mjs/_test.cjs.

Rust 中的函数完备测试

¥Function-complete tests in Rust

_config.json 有其局限性，因此我们也支持直接使用 Rust 编写测试。你可以参考

¥_config.json has it's limitations, so we also support writing tests with Rust directly. You could refer to

• https://github.com/rolldown/rolldown/commit/7d32cc70e194c52fa932cefbd4f926a9c3e3315f

快照测试

¥Snapshot testing

Rolldown 使用 insta 进行 Rust 快照测试。你可以使用：

¥Rolldown uses insta for Rust snapshot testing. You can use:

• cargo insta review 逐个审核新快照。

  ¥cargo insta review to review the new snapshot one by one.

• cargo insta accept 一次性接受所有新快照。

  ¥cargo insta accept to accept all new snapshots at once.

HMR 测试

¥HMR tests

如果测试用例文件夹包含任何名为 *.hmr-*.js 的文件，则测试将在启用 HMR 模式下运行。

¥If a test case folder contains any files named *.hmr-*.js, the test will run in HMR enabled mode.

HMR 编辑文件

¥HMR edit files

• 与模式 *.hmr-*.js 匹配的文件称为 HMR 编辑文件。

  ¥Files that match the pattern *.hmr-*.js are called HMR edit files.

• 这些文件表示对现有源文件的更改。

  ¥These files represent changes to existing source files.

• hmr- 之后的部分表示更改的步骤号。例如，main.hmr-1.js 表示在步骤 1 中应用的更改。

  ¥The part after hmr- indicates the step number of the change. For example, main.hmr-1.js means a change applied in step 1.

测试如何工作

¥How the test works

1. 所有非 HMR 文件均复制到临时目录。

   ¥All non-HMR files are copied to a temporary directory.

2. 初始构建由这些文件生成。

   ¥An initial build is generated from these files.

3. 然后，HMR 步骤 1 开始：带有 .hmr-1.js 的文件用于覆盖临时目录中的相应文件，并生成 HMR 补丁。

   ¥Then, HMR step 1 begins: files with .hmr-1.js are used to overwrite the corresponding files in the temporary directory, and an HMR patch is generated.

4. 此过程重复执行步骤 2、3，依此类推。像 *.hmr-2.js、*.hmr-3.js 等文件将逐步应用。

   ¥This process repeats for step 2, 3, and so on. Files like *.hmr-2.js, *.hmr-3.js, etc., are applied step by step.

示例

如果测试文件夹包含以下文件：

¥If the test folder has these files:

• main.js

• sub.js

• main.hmr-1.js

• sub.hmr-1.js

• sub2.hmr-2.js

测试将执行以下步骤：

¥The test will go through these steps:

1. 初始构建：main.js, sub.js

   ¥Initial build: main.js, sub.js

2. 步骤 1：

   ¥Step 1:

   • main.js 被替换为 main.hmr-1.js

     ¥main.js is replaced with main.hmr-1.js

   • sub.js 被替换为 sub.hmr-1.js

     ¥sub.js is replaced with sub.hmr-1.js

3. 步骤 2：

   ¥Step 2:

   • main.js 和 sub.js 与步骤 1 相同。

     ¥main.js and sub.js remain as in Step 1

   • sub2.js 是使用 sub2.hmr-2.js 的内容添加的。

     ¥sub2.js is added using the contents of sub2.hmr-2.js

Node.js 测试

¥Node.js Tests

提示

运行这些测试之前，请确保已安装 构建 Node.js 绑定。

¥Make sure to build Node.js bindings before running these tests.

Node.js API 测试

¥Node.js API tests

位于 packages/rolldown/tests 的测试用于测试 Rolldown 的 Node.js API（即 NPM 上发布的 rolldown 包的 API）。

¥Tests located in packages/rolldown/tests are used to test Rolldown's Node.js API (i.e. the API of the rolldown package published on NPM).

我们的目标是尽可能使 Rolldown 的 Node.js API 与 Rollup 的 API 保持一致，并通过测试来验证 API 的一致性并跟踪进度。目前，许多 Rollup 选项尚不受支持。如果你实现了对 rollup 中其他选项的支持，请为它们添加相应的测试用例。

¥It is our goal to align Rolldown's Node.js API with that of Rollup's as much as possible, and the tests are used to verify API alignment and track the progress. Currently, there are many Rollup options that are not yet supported. If you implemented support for additional options from rollup, please add corresponding test cases for them.

• just test-node-rolldown 将运行下滚测试。

  ¥just test-node-rolldown will run rolldown tests.

• just test-node-rolldown --update 将运行测试并更新快照。

  ¥just test-node-rolldown --update will run tests and update snapshots.

运行特定文件的测试

¥Run tests of the specific file

要运行特定文件的测试，你可以使用

¥To run tests of the specific file, you could use

just test-node-rolldown test-file-name

例如，要在 fixture.test.ts 中运行测试，你可以使用 just test-node-rolldown fixture。

¥For example, to run tests in fixture.test.ts, you could use just test-node-rolldown fixture.

运行特定测试

¥Run the specific test

要运行特定测试，你可以使用

¥To run specific test, you could use

just test-node-rolldown -t test-name

fixture.test.ts 中的测试名称由其文件夹名称定义。tests/fixtures/resolve/alias 的测试名称为 resolve/alias。

¥Names of tests in fixture.test.ts are defined with their folder names. tests/fixtures/resolve/alias will has test name resolve/alias.

要运行 tests/fixtures/resolve/alias 测试，你可以使用 just test-node-rolldown -t resolve/alias。

¥To run the tests/fixtures/resolve/alias test, you could use just test-node-rolldown -t resolve/alias.

信息

• just test-node-rolldown -t aaa bbb 与 just test-node-rolldown -t "aaa bbb" 不同。前者将运行包含 aaa 或 bbb 的测试，而后者将运行名称包含 aaa bbb 的测试。

  ¥just test-node-rolldown -t aaa bbb is different from just test-node-rolldown -t "aaa bbb". The former will run tests that either contains aaa or bbb, while the latter will run tests, whose name contain aaa bbb.

• 如需了解更多高级用法，请参阅 https://vitest.dev/guide/filtering。

  ¥For more advanced usage, please refer to https://vitest.dev/guide/filtering.

Rollup 行为一致性测试

¥Rollup behavior alignment tests

我们还致力于通过针对 Rolldown 运行 Rollup 自身的测试，使其行为与 Rollup 保持一致。

¥We also aim for behavior alignment with Rollup by running Rollup's own tests against Rolldown.

为了实现这一点，packages/rollup-tests/test 中的每个测试用例都代理了项目根目录中 rollup git 子模块中相应的测试。

¥To achieve this, each test case in packages/rollup-tests/test proxies to the corresponding test in the rollup git submodule in project root.

在设置项目时，运行 just setup 后应该已经初始化了 git 子模块，但在运行 Rollup 测试之前，你还应该运行 just update-submodule 来更新子模块。

¥The git submodule should have been initialized after running just setup when setting up the project, but you should also run just update-submodule to update the submodule before running the Rollup tests.

在 /packages/rollup-tests 中：

¥In /packages/rollup-tests:

• just test-node-rollup 将运行上滚测试。

  ¥just test-node-rollup will run rollup tests.

• just test-node-rollup --update 将运行并更新测试状态。

  ¥just test-node-rollup --update will run and update the tests' status.

如何选择测试技术

¥How to choose test technique

我们的 Rust 测试基础设施足够强大，可以覆盖大多数 JavaScript 用例（插件、在配置中传递函数）。但由于 JavaScript 端用户仍然是我们的一等公民，因此如果可能，请尝试在 JavaScript 端进行测试。以下是一些关于你应该使用哪种测试技术的经验。

¥Our Rust test infra is powerful enough to cover most of the case of JavaScript (plugin, passing function inside config). But since JavaScript side user is still our first class user, try to put tests in JavaScript side if possible. Here are some experience about what test technique you should use.

TLDR

如果你不想浪费时间决定使用哪种方式，请在 JavaScript 端添加测试。

¥Add test in JavaScript side if you don't want to wasting time on deciding which way to use.

首选 Rust

¥Prefer Rust

1. 测试 rolldown 核心触发的警告或错误。

   ¥Test warning or error emitted by rolldown core.

   • error

   • warning

2. 矩阵测试，假设你想要测试一个与 format 不同的套件，使用 configVariants，你只需一次测试即可完成。

   ¥Matrix testing, assume you want to test a suite different format, with configVariants you could do that with only one test.

3. 与链接算法（摇树、代码块拆分）相关的测试可能需要大量调试，在 Rust 端添加测试可以减少“编码-调试-编码”工作循环的时间。

   ¥Tests related to linking algorithm(tree shaking, chunk splitting) Those may require a lot of debugging, add test on Rust side could reduce the time of coding-debug-coding work loop.

首选 JavaScript

¥Prefer JavaScript

以上未提及的任何类别都应放在 JavaScript 端。

¥Any category not mentioned above should put in JavaScript side.