Lexe内置@llrt/test测试框架：为10MB单文件可执行程序编写Jest风格单元测试的完整教程

Lexe内置@llrt/test测试框架：为10MB单文件可执行程序编写Jest风格单元测试的完整教程

【免费下载链接】lexePackage your Node.js application into a single executable file, but only 10MB.🔥项目地址: https://gitcode.com/gh_mirrors/le/lexe

Lexe（原 LLRT）可以将你的 Node.js 应用打包成仅约 10MB 的单个可执行文件，而它的内置测试框架@llrt/test让你无需安装任何依赖，就能以 Jest 风格的describe / it / expect编写并并行运行单元测试。本文带你从零跑通 Lexe 内置测试框架，掌握完整配置方法。

为什么需要内置测试框架？

大多数 Node.js 测试框架（Jest、Vitest）依赖 npm 生态，打包后会显著增加可执行文件体积——这对一个追求 10MB 极小体积的运行时来说是大忌。

Lexe 的思路是：把测试框架直接编译进运行时本身。

• 零依赖：describe、it、expect是全局函数，写测试无需import，无需node_modules
• Jest 风格 API：熟悉 Jest 的开发者几乎零成本上手
• 多 Worker 并行：自动按 CPU 核心数启动多个测试进程并行执行，并带彩色进度条与实时结果
• 与打包流程集成：测试可直接在编译产物目录上运行，验证打包后的行为

核心实现位于 llrt_core/src/modules/js/@llrt/test/index.ts（测试调度服务端）和 worker.ts（测试执行端），断言能力则由 Jest 风格的 jest-expect.ts 提供。

启动测试：一条命令即可

Lexe 可执行文件自带test子命令，指定包含测试文件的目录即可：

llrt test -d path/to/tests

以本项目为例，Makefile 中的test目标就是这样定义的：

test: export JS_MINIFY = 0 test: js cargo run -- test -d bundle/js/__tests__/unit

几个实用细节：

• 用TEST_TIMEOUT环境变量调整单个用例超时时间（默认 5000ms），例如长耗时的端到端测试会设置为 60000
• 支持--nocapture与--show-output参数查看测试过程中的控制台输出
• 失败时会打印具体用例、错误堆栈以及该 Worker 捕获到的 Std Out / Std Err

编写第一个测试：describe + it + expect

测试 API 是全局注入的，一个最小示例如下：

describe("UUID Generation", () => { it("should generate a valid v4 UUID", () => { const uuid = uuidv4(); expect(typeof uuid).toEqual("string"); expect(uuid.length).toEqual(36); expect(uuid).toMatch(UUID_PATTERN); }); });

expect提供了丰富的 Jest 风格断言匹配器，包括toEqual、toMatch、toBe、toBeTruthy等，还支持 Jest 的非对称匹配器（asymmetric matchers），实现见 jest-asymmetric-matchers.ts。

测试钩子：beforeAll 到 afterEach

每个describe套件都支持标准生命周期钩子，同步或异步函数均可：

• beforeAll：套件中所有用例执行前运行一次
• afterAll：套件中所有用例执行后运行一次
• beforeEach：每个用例执行前运行
• afterEach：每个用例执行后运行

执行顺序由 worker.ts 中的runTests/ 套件递归逻辑严格保证：beforeAll → (beforeEach → 用例 → afterEach) × N → afterAll。

高级用法：only、skip 与自定义超时

调试时最常用的三个特性：

describe.only("只跑这个套件", () => { ... }); it.skip("暂时跳过", () => { ... }); it("慢用例", async () => { await slowJob(); }, 10000); // 第三个参数为超时时间

• .only：只执行带标记的套件/用例（describe.only、it.only），方便在 CI 之外聚焦排查
• .skip：跳过尚未稳定或待补充的用例（describe.skip、it.skip）
• 自定义超时：按用例粒度控制，避免全局调大TEST_TIMEOUT

运行结束后，控制台会汇总每个文件的成功/失败/跳过数量与总耗时，失败项以红底高亮展示。

幕后原理：多 Worker 并行执行

@llrt/test的执行模型很值得了解：

1. 测试服务：llrt test启动一个本地 TCP 服务，按 CPU 核心数（os.availableParallelism()）spawn 出等量 Worker 进程
2. 文件级分片：各 Worker 通过 shared.ts 定义的消息协议从文件队列中领取测试文件，实现天然并行
3. 实时反馈：服务端以 15 FPS 刷新彩色进度条，实时显示当前执行的文件与用例
4. 健壮性：每个 Worker 配有连接超时看门狗，卡死的测试不会拖垮整体

这种并行能力在 Lexe 极快的启动速度下收益尤其明显——下图是 Lexe（LLRT）与 Node.js 20 在 DynamoDB 操作上的性能基准对比，可执行文件的冷启动优势让"打包后测试"也变得飞快：

总结

Lexe 的@llrt/test用极小的代价补齐了"单文件可执行 + 自动化测试"的最后一块拼图：Jest 风格 API、生命周期钩子、并行执行、彩色输出一应俱全，且全部内置于运行时之中。对于希望把 Node.js 应用打包成 10MB 左右单文件分发的团队，它是开箱即用的完整测试方案。

📌快速上手清单

1. 编写*.test.js，使用全局describe / it / expect
2. 用llrt test -d <目录>启动测试
3. 需要长时间运行的用例用TEST_TIMEOUT或第三个参数放宽超时
4. 调试时善用.only/.skip聚焦用例

【免费下载链接】lexePackage your Node.js application into a single executable file, but only 10MB.🔥项目地址: https://gitcode.com/gh_mirrors/le/lexe