Skip to content
bun-jest-migration · claude-skills · Flowy
Use when migrating from Jest to Bun's test runner, import compatibility, mocks, and config.
One skill from claude-skills .
$ npx -y skills add secondsky/claude-skills --skill bun-jest-migration --agent claude-codeInstalls just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itself Claude auto-loads it when your prompt matches the work. You can call it Invoke it directly when you want it. Slash command /bun-jest-migration👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Use when migrating from Jest to Bun's test runner, import compatibility, mocks, and config. 📦 Ships with claude-skills
</> SKILL.md
bun-jest-migration.SKILL.md
---
name : bun-jest-migration
description : Use when migrating from Jest to Bun's test runner, import compatibility, mocks, and config.
metadata:
version: "1.0.0"
license : MIT
---
# Bun Jest Migration
Bun's test runner is Jest-compatible. Most Jest tests run without changes.
## Quick Migration
```bash
# 1. Remove Jest dependencies
bun remove jest ts-jest @types/jest babel-jest
# 2. Update test script
# package.json: "test": "bun test"
# 3. Run tests
bun test
```
## Import Changes
```typescript
// Before (Jest)
import { describe, it, expect, jest } from '@jest/globals';
// After (Bun) - No import needed, or explicit:
import { describe, test, expect, mock, spyOn } from "bun:test";
```
## API Compatibility
### Fully Compatible
| Jest | Bun | Notes |
|------|-----|-------|
| `describe()` | `describe()` | Identical |
Flowy AI Flows that just work. Hand-picked Claude Code plugins that fire the right skill as you prompt.
| `it()` / `test()` | `test()` | Use `test()` |
| `expect()` | `expect()` | Same matchers |
| `beforeAll/Each` | `beforeAll/Each` | Identical |
| `afterAll/Each` | `afterAll/Each` | Identical |
| `jest.fn()` | `mock()` | Use `mock()` |
| `jest.spyOn()` | `spyOn()` | Identical |
### Requires Changes
| Jest | Bun Equivalent |
|------|----------------|
| `jest.mock('module')` | `mock.module('module', () => {...})` |
| `jest.useFakeTimers()` | `import { setSystemTime } from "bun:test"` |
| `jest.setTimeout()` | Third argument to `test()` |
| `jest.clearAllMocks()` | Call `.mockClear()` on each mock |
## Mock Migration
### Mock Functions
```typescript
// Jest
const fn = jest.fn().mockReturnValue('value');
// Bun
const fn = mock(() => 'value');
// Or for compatibility:
import { jest } from "bun:test";
const fn = jest.fn(() => 'value');
```
### Module Mocking
```typescript
// Jest (top-level hoisting)
jest.mock('./utils', () => ({
helper: jest.fn(() => 'mocked')
}));
// Bun (inline, no hoisting)
import { mock } from "bun:test";
mock.module('./utils', () => ({
helper: mock(() => 'mocked')
}));
```
### Spy Migration
```typescript
// Jest
jest.spyOn(console, 'log').mockImplementation(() => {});
// Bun (identical)
spyOn(console, 'log').mockImplementation(() => {});
```
## Timer Migration
```typescript
// Jest
jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01'));
jest.advanceTimersByTime(1000);
// Bun - supports Jest-compatible timer APIs
import { setSystemTime } from "bun:test";
import { jest } from "bun:test";
jest.useFakeTimers();
jest.setSystemTime(new Date('2024-01-01'));
jest.advanceTimersByTime(1000); // Now supported
```
## Snapshot Testing
```typescript
// Jest
expect(component).toMatchSnapshot();
expect(data).toMatchInlineSnapshot(`"expected"`);
// Bun (identical)
expect(component).toMatchSnapshot();
expect(data).toMatchInlineSnapshot(`"expected"`);
```
Update snapshots:
```bash
bun test --update-snapshots
```
## Configuration Migration
### jest.config.js → bunfig.toml
```javascript
// jest.config.js (before)
module.exports = {
testMatch: ['**/*.test.ts'],
testTimeout: 10000,
setupFilesAfterEnv: ['./jest.setup.ts'],
collectCoverage: true,
coverageThreshold: { global: { lines: 80 } }
};
```
```toml
# bunfig.toml (after)
[test]
root = "./"
preload = ["./jest.setup.ts"]
timeout = 10000
coverage = true
coverageThreshold = 0.8
```
## Common Migration Issues
### Issue: `jest.mock` Not Working
```typescript
// Jest mock hoisting doesn't exist in Bun
// Move mock.module before imports or use dynamic imports
// Solution 1: Use mock.module at top
mock.module('./api', () => ({ fetch: mock() }));
import { fetch } from './api';
// Solution 2: Dynamic import
const mockFetch = mock();
mock.module('./api', () => ({ fetch: mockFetch }));
const { fetch } = await import('./api');
```
### Issue: Timer Functions Missing
```typescript
// Bun timer support is limited
// Use setSystemTime for date mocking
import { setSystemTime } from "bun:test";
beforeEach(() => {
setSystemTime(new Date('2024-01-01'));
});
afterEach(() => {
setSystemTime(); // Reset to real time
});
```
### Issue: Custom Matchers
```typescript
// Jest
expect.extend({ toBeWithinRange(received, floor, ceiling) {...} });
// Bun (same API)
import { expect } from "bun:test";
expect.extend({
toBeWithinRange(received, floor, ceiling) {
const pass = received >= floor && received <= ceiling;
return {
pass,
message: () => `expected ${received} to be within ${floor}-${ceiling}`
};
}
});
```
## Step-by-Step Migration
1. **Remove Jest packages**
```bash
bun remove jest ts-jest @types/jest babel-jest jest-environment-jsdom
```
2. **Update package.json**
```json
{
"scripts": {
"test": "bun test",
"test:watch": "bun test --watch",
"test:coverage": "bun test --coverage"
}
}
```
3. **Convert jest.config.js to bunfig.toml**
4. **Update imports in test files**
- Find/replace `@jest/globals` → `bun:test`
- Find/replace `jest.fn()` → `mock()`
- Find/replace `jest.mock()` → `mock.module()`
5. **Run and fix**
```bash
bun test 2>&1 | head -50 # Check first errors
```
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| `Cannot find module '@jest/globals'` | Old import | Use `bun:test` |
| `jest is not defined` | Global jest | Import from `bun:test` |
| `mock.module is not a function` | Wrong import | `import { mock } from "bun:test"` |
| `Snapshot mismatch` | Different serialization | Update with `--update-snapshots` |
## When to Load References
Load `references/compatibility-matrix.md` when:
- Full Jest API compatibility details
- Unsupported features list
- Workarounds for missing features
© 2026 Flowy · Free and open source
Built for Claude Code · Not affiliated with Anthropic
