A TypeScript library that provides automatic mocking utilities for Bun's test framework, enabling easy creation of type-safe mocks for complex objects and nested structures.
npm install bun-automock!Quality Gate
!Coverage
!Sonar Violations
A TypeScript library that provides automatic mocking utilities for Bun's test framework, enabling easy creation of type-safe mocks for complex objects and nested structures. Inspired by jest-mock-extended & vitest-mock-extended.
> Warning
> This library is still in development and the readme was mostly generated by AI.
- ✨ Automatic mocking of complex objects and nested structures
- 🔒 Type-safe mocks for interfaces, classes, and objects
- 🎯 Easy to use API for creating mocks
- 📊 Built-in support for test assertions
- ⚡ Compatible with Bun's test framework
- 📦 Dual package exports - supports both ESM and CommonJS
- Features
- Table of Contents
- Installation
- Usage
- mockFn()
- mockDeepFn()
- .spy()
- API Reference
- mockFn
- mockDeepFn
- Contributing to the project
- Available Scripts
- Development
- Testing
- License
- Author
``bash`
bun add -D bun-automockor
pnpm add -D bun-automockor
npm install --save-dev bun-automock
The package supports both ESM and CommonJS imports:
`typescript
// ESM (recommended)
import { mockFn, mockDeepFn } from 'bun-automock';
// CommonJS
const { mockFn, mockDeepFn } = require('bun-automock');
`
Creates a shallow mock of an object where each property becomes a Bun mock function. Perfect for mocking services, classes, or interfaces where you need to control the behavior of individual methods.
`typescript
import { mockFn } from 'bun-automock';
interface UserService {
getName(): string;
getEmail(): string;
updateProfile(data: any): Promise
}
// Create a mock with type safety
const userServiceMock = mockFn
// Configure mock behavior
userServiceMock.getName.mockReturnValue('John Doe');
userServiceMock.getEmail.mockReturnValue('john@example.com');
userServiceMock.updateProfile.mockResolvedValue(undefined);
// Use in tests
expect(userServiceMock.getName()).toBe('John Doe');
expect(userServiceMock.getEmail()).toBe('john@example.com');
await expect(userServiceMock.updateProfile({})).resolves.toBe(undefined);
// Use .spy() for test assertions
expect(userServiceMock.getName.spy()).toHaveBeenCalledTimes(1);
expect(userServiceMock.updateProfile.spy()).toHaveBeenCalledWith({});
`
Creates a deep mock that automatically mocks nested objects and their properties. Each property at any level becomes a callable mock function while preserving the ability to access nested properties.
`typescript
import { mockDeepFn } from 'bun-automock';
interface DatabaseService {
users: {
repository: {
findById(id: string): Promise
save(user: User): Promise
};
cache: {
get(key: string): string | null;
set(key: string, value: string): void;
};
};
}
// Create a deep mock
const dbMock = mockDeepFn
// Configure nested mock behavior
dbMock.users.repository.findById.mockResolvedValue({ id: '1', name: 'John' });
dbMock.users.repository.save.mockResolvedValue(undefined);
dbMock.users.cache.get.mockReturnValue('cached-value');
// Use in tests - basic functionality
await expect(dbMock.users.repository.findById('1')).resolves.toEqual({ id: '1', name: 'John' });
expect(dbMock.users.cache.get('key')).toBe('cached-value');
`
Each mocked property includes a .spy() method that returns the underlying Bun mock function, enabling you to use all standard Bun test assertions:
`typescript
const dbMock = mockDeepFn
// Call the mocked function
await dbMock.users.repository.findById('123');
await dbMock.users.repository.findById('456');
// Use spy() for clean test assertions
expect(dbMock.users.repository.findById.spy()).toHaveBeenCalledTimes(2);
expect(dbMock.users.repository.findById.spy()).toHaveBeenNthCalledWith(1, '123');
expect(dbMock.users.repository.findById.spy()).toHaveBeenNthCalledWith(2, '456');
expect(dbMock.users.repository.findById.spy()).toHaveReturnedTimes(2);
`
Creates a shallow mock where each property of type T becomes a Bun mock function.
Parameters:
- T - The type to mock (interface, class, or object type)
Returns:
- MockProxy - A proxy object where each property is a Bun mock function
Additional Methods:
- .spy() - Available on each mocked property, returns the underlying Bun mock function for test assertions
Creates a deep mock that automatically handles nested objects, making every property at any depth a callable mock function.
Parameters:
- T - The type to mock (interface, class, or object type)
Returns:
- DeepMockProxy - A proxy object with deep mocking capabilities
Additional Methods:
- .spy() - Available on each mocked property, returns the underlying Bun mock function for test assertions
The project uses Bun as the package manager and runtime, with tsdown for modern dual-package building.
External dependencies are kept minimal and added only for compelling reasons.
- bun run test - Run the test suite oncebun run tdd
- - Run tests in watch mode for continuous developmentbun run test:coverage
- - Run tests with coverage reportingbun run build
- - Build the project with dual package exports (ESM + CJS)bun run dev
- - Build in watch mode for developmentbun run clean
- - Clean the dist and coverage directories
To start developing run the following commands:
`bash`
bun install # install dependencies
bun dev # build in watch mode for development
bun tdd # run tests in watch mode for continuous development
This will:
1. Clean the dist directoryindex.js
2. Bundle the source code using tsdown
3. Generate both ESM () and CommonJS (index.cjs) outputsindex.d.ts
4. Create TypeScript declaration files for both formats (, index.d.cts)
5. Generate source maps for debugging
The built files will be available in the dist directory:index.js
- - ESM bundleindex.cjs
- - CommonJS bundleindex.d.ts
- - TypeScript declarations for ESMindex.d.cts
- - TypeScript declarations for CommonJS
- Source maps for debugging
Run the test suite:
`bash``
bun test # Run tests once
bun run tdd # Run tests in watch mode for continuous development
bun test:coverage # Run tests with coverage reporting
The tests are written using Bun's test framework.
This project is licensed under the MIT License - see the LICENSE file for details.