测试运行器

相关源文件

• packages/bun-types/test.d.ts
• src/bun.js/test/expect.zig
• src/bun.js/test/jest.classes.ts
• src/bun.js/test/jest.zig
• src/bun.js/test/snapshot.zig
• test/bundler/transpiler/__snapshots__/transpiler.test.js.snap
• test/integration/bun-types/fixture/test.ts
• test/js/bun/test/__snapshots__/test-interop.js.snap
• test/js/bun/test/__snapshots__/test-test.test.ts.snap
• test/js/bun/test/expect.test.js
• test/js/bun/test/jest-extended.test.js
• test/js/bun/test/jest-hooks.test.ts
• test/js/bun/test/snapshot-tests/snapshots/__snapshots__/snapshot.test.ts.snap
• test/js/bun/test/snapshot-tests/snapshots/more.test.ts
• test/js/bun/test/snapshot-tests/snapshots/snapshot.test.ts
• test/js/bun/test/test-fixture-diff-indexed-properties.js
• test/js/bun/test/test-test.test.ts

Test Runner 是 Bun 兼容 Jest 的测试框架，提供全面的测试执行、断言和快照测试功能。该系统处理测试发现、执行编排、生命周期管理和结果报告，同时保持与 Jest API 兼容。

有关调用测试运行器的 CLI 界面的信息，请参阅 CLI Architecture。有关测试期间 shell 命令执行的详细信息，请参阅 Shell Interpreter。

架构概述

Test Runner 由几个相互关联的组件组成，主要用 Zig 实现以获得高性能，并带有 JavaScript 兼容层以实现 Jest API 合规性。

核心组件架构

Sources: src/bun.js/test/jest.zig42-261 src/bun.js/test/expect.zig53-128 src/bun.js/test/snapshot.zig15-56

测试执行流程

Sources: src/bun.js/test/jest.zig126-153 src/bun.js/test/jest.zig654-783

Test Organization and Lifecycle

Test Structure Hierarchy

Test Runner 以类似 Jest 的组织方式，以分层结构组织测试。

• File: Top-level test file (*.test.js, *.spec.js)
• DescribeScope: Test suites created by describe() calls
• TestScope: Individual tests created by test() or it() calls

Sources: src/bun.js/test/jest.zig230-238 src/bun.js/test/jest.zig795-812 src/bun.js/test/jest.zig517-541

Lifecycle Hooks Execution

Test Runner 支持与 Jest 兼容的生命周期钩子，并具有正确的执行顺序。

钩子	执行计时	范围
beforeAll	在作用域内的所有测试运行之前执行一次	DescribeScope
beforeEach	在每个单独的测试之前执行	DescribeScope
afterEach	在每个单独的测试之后执行	DescribeScope
afterAll	在作用域内的所有测试运行之后执行一次	DescribeScope

Sources: src/bun.js/test/jest.zig857-970 packages/bun-types/test.d.ts275-313

Jest Compatibility Layer

API Surface Mapping

Jest 兼容层公开了熟悉的测试 API，同时委托给 Bun 的原生实现。

Sources: src/bun.js/test/jest.zig293-394 src/bun.js/test/jest.zig455-515 packages/bun-types/test.d.ts179-259

Test Registration Functions

Test Runner 提供了多种具有不同行为的测试注册函数。

功能	行为	实现
test() / it()	Normal test execution	TestScope.call
test.only()	Exclusive test execution	TestScope.only
test.skip()	Skip test execution	TestScope.skip
test.todo()	Mark as todo/unimplemented	TestScope.todo
test.failing()	Expect test to fail	TestScope.failing

Sources: src/bun.js/test/jest.zig551-585 packages/bun-types/test.d.ts369-442

Assertion System

Expect Implementation

The Expect system provides Jest-compatible assertions with support for synchronous and asynchronous testing

Sources: src/bun.js/test/expect.zig53-128 src/bun.js/test/expect.zig357-395 src/bun.js/test/jest.classes.ts213-279

Core Matchers

Test Runner 包含全面的内置匹配器。

类别	Matchers	描述
等号	toBe, toEqual, toStrictEqual	Value comparison
Truthiness	toBeTruthy, toBeFalsy, toBeNull	Boolean evaluation
数字	toBeGreaterThan, toBeCloseTo	Numeric comparison
字符串	toMatch, toContain	String/regex matching
Arrays/Objects	toContainEqual, toHaveProperty	Collection testing
函数	toThrow, toHaveBeenCalled	Function behavior
Promises	.resolves, .rejects	异步测试

Sources: src/bun.js/test/jest.classes.ts280-514 packages/bun-types/test.d.ts654-1330

快照测试

Snapshot Management

Snapshot system handles both external snapshot files and inline snapshots

Sources: src/bun.js/test/snapshot.zig15-56 src/bun.js/test/snapshot.zig69-111 src/bun.js/test/snapshot.zig249-348

错误处理与报告

Test Execution Results

Test Runner tracks multiple result types and provides detailed error reporting

来源： src/bun.js/test/jest.zig240-258 src/bun.js/test/jest.zig172-202 src/bun.js/test/jest.zig90-124

超时管理

测试运行器提供可配置的超时处理，包括全局和每个测试的超时控件。

• 默认超时：5000毫秒（可通过 setDefaultTimeout 进行配置）
• 每个测试的超时：在测试选项中指定或通过 jest.setTimeout 指定
• 超时执行：事件循环计时器集成
• 超时报告：详细的超时错误消息

来源： src/bun.js/test/jest.zig63-124 src/bun.js/test/jest.zig496-509 packages/bun-types/test.d.ts315-333

测试运行器与 Bun 的 JavaScript 虚拟机和事件循环深度集成，提供高性能、兼容 Jest 的测试体验，同时保持与现有 Jest 测试套件的完全兼容。