This document describes the TypeScript type definitions for Bun's testing framework, specifically test.d.ts and related type declarations. These definitions provide type safety and IDE autocomplete for test APIs including test, describe, expect, mock functions, and Jest/Vitest-compatible namespaces.
For information about the actual test runner implementation, see Testing Framework. For the broader Bun API type definitions, see Bun API Types.
Bun's testing type definitions are located in the bun-types package and provide comprehensive TypeScript types for the bun:test module. The definitions support:
test, describe, it)beforeAll, afterAll, beforeEach, afterEach)expect with 100+ matchers)The type definitions are structured to provide both compile-time type safety and runtime compatibility with Jest and Vitest test suites.
Sources: packages/bun-types/test.d.ts1-700 packages/bun-types/index.d.ts1-23
The type definitions follow a layered architecture where test.d.ts exports the primary API surface, while global augmentations in globals.d.ts provide ambient types for Node.js compatibility extensions.
Sources: packages/bun-types/test.d.ts1-16 packages/bun-types/index.d.ts17 src/bun.js/test/jest.zig174-307
The Test<T> interface defines the signature for test() and it() functions with support for parameterized tests:
The interface uses conditional types to properly type the fn parameter based on whether each() is used:
| Property | Type | Description |
|---|---|---|
(label, fn, options?) | Method signature | Base test registration |
only | Test<T> | Skip all other tests |
skip | Test<T> | Skip this test |
todo | Test<T> | Mark as to-be-implemented |
failing | Test<T> | Expect test to fail |
concurrent | Test<T> | Run concurrently |
serial | Test<T> | Force serial execution |
if(condition) | Function | Conditional execution |
skipIf(condition) | Function | Conditional skip |
each<T>(table) | Function | Parameterized tests |
Sources: packages/bun-types/test.d.ts468-540 test/integration/bun-types/fixture/test.ts1-18
The Describe<T> interface is similar to Test<T> but for grouping tests:
The DescribeLabel type allows flexible labeling:
Sources: packages/bun-types/test.d.ts227-280 packages/bun-types/test.d.ts207
Lifecycle hooks are typed with optional timeout configuration:
The hook functions support three callback styles:
() => void() => Promise<unknown>(done: (err?: unknown) => void) => voidSources: packages/bun-types/test.d.ts308-396 test/integration/bun-types/fixture/test.ts21-37
The Matchers<R> interface defines over 100 matcher methods with proper type inference:
The Matchers interface is generic over the return type R, allowing for method chaining with not and promise matchers:
Sources: packages/bun-types/test.d.ts631-1113 test/integration/bun-types/fixture/test.ts52-76
The expect function is overloaded to support multiple invocation patterns:
Key overloads include:
| Signature | Description |
|---|---|
expect<T>(value: T) | Create expectation for value |
expect.extend(matchers) | Add custom matchers |
expect.assertions(count) | Expect exact assertion count |
expect.hasAssertions() | Expect at least one assertion |
expect.anything() | Asymmetric matcher for any value |
expect.any(constructor) | Asymmetric matcher for type |
expect.arrayContaining(array) | Asymmetric matcher for arrays |
Sources: packages/bun-types/test.d.ts566-629 src/bun.js/test/expect.zig18-102
Asymmetric matchers are typed as opaque wrapper types:
These types correspond to runtime implementations in the Zig codebase:
Sources: packages/bun-types/test.d.ts1115-1203 src/bun.js/test/expect.zig234-244 src/bun.js/test/jest.classes.ts1-103
The Mock<T> interface provides full type safety for mock functions:
The Mock<T> interface extends the function type T while adding mock-specific properties:
Sources: packages/bun-types/test.d.ts1247-1442 src/bun.js/bindings/JSMockFunction.cpp231-267
The spyOn function is typed to preserve the original function signature:
This ensures that:
Extract)Sources: packages/bun-types/test.d.ts160-164 src/bun.js/bindings/JSMockFunction.cpp1289-1433
The jest namespace provides Jest-compatible APIs:
Sources: packages/bun-types/test.d.ts91-156 src/bun.js/test/jest.zig174-252
The vi namespace provides Vitest-compatible APIs, aliasing to Jest functionality:
This allows test code written for Vitest to run in Bun without modification:
Sources: packages/bun-types/test.d.ts170-201 src/bun.js/test/jest.zig242-251
The Test<T> and Describe<T> interfaces use generic parameters to type parameterized tests:
Example type inference:
Sources: packages/bun-types/test.d.ts430-443 packages/bun-types/test.d.ts277-279
The matchers use conditional types to provide precise type inference:
Example usage showing type inference:
Sources: packages/bun-types/test.d.ts700-850 test/integration/bun-types/fixture/test.ts52-65
The type system supports custom matcher extensions:
Sources: packages/bun-types/test.d.ts1447-1479 test/js/bun/test/expect.test.js1-50
The bun:test module is declared as:
This module declaration ensures that imports from "bun:test" are properly typed:
Sources: packages/bun-types/test.d.ts16-1560 test/integration/bun-types/fixture/test.ts1-18
The type definitions correspond to runtime implementations:
| Type Definition | Runtime Implementation |
|---|---|
Test<T> interface | src/bun.js/test/jest.zig64-172 |
Matchers<R> interface | src/bun.js/test/expect.zig18-521 |
Mock<T> interface | src/bun.js/bindings/JSMockFunction.cpp231-800 |
jest namespace functions | src/bun.js/test/jest.zig174-307 |
| Asymmetric matchers | src/bun.js/test/jest.classes.ts1-194 |
The Zig and C++ implementations export functions that match the TypeScript signatures, ensuring runtime behavior matches compile-time types.
Sources: packages/bun-types/test.d.ts1-1560 src/bun.js/test/jest.zig1-510 src/bun.js/test/expect.zig1-521
The bun-types package includes comprehensive fixture files for type testing:
The test fixtures verify:
any types leak throughExample fixture usage:
Sources: test/integration/bun-types/fixture/test.ts1-150 test/integration/bun-types/bun-types.test.ts87-130
The type test suite uses TypeScript's compiler API to detect type errors:
This ensures that:
Sources: test/integration/bun-types/bun-types.test.ts132-205 test/integration/bun-types/bun-types.test.ts22-25
Refresh this wiki