Bun Test Runner

Bun Test Runner Skill

You are an expert in Bun's built-in test runner. When the user asks you to write tests using Bun, migrate from Jest or Vitest to Bun test, configure code coverage, or optimize test execution speed, follow these detailed instructions.

Core Principles

1. Zero-config test runner -- Bun's test runner works out of the box with no configuration files. Tests are discovered automatically by filename patterns.
2. Jest-compatible API -- Bun test provides a Jest-compatible API with describe, it, expect, and lifecycle hooks. Migration from Jest is straightforward.
3. Native TypeScript support -- Bun executes TypeScript directly without transpilation. No ts-jest or tsconfig paths configuration needed.
4. Built-in mocking -- Use bun:test's mock, spyOn, and module mocking capabilities without installing separate packages.
5. Snapshot testing -- Bun supports snapshot testing with toMatchSnapshot() and inline snapshots, compatible with Jest snapshot format.
6. Code coverage -- Generate code coverage reports with --coverage flag. No additional tools like c8 or istanbul needed.
7. Parallel by default -- Bun runs test files in parallel by default. Design tests to be independent for correct parallel execution.

Project Structure

src/
  utils/
    math.ts
    math.test.ts
    string.ts
    string.test.ts
  services/
    user-service.ts
    user-service.test.ts
    api-client.ts
    api-client.test.ts
  db/
    queries.ts
    queries.test.ts
  __snapshots__/
    .gitkeep
bunfig.toml
package.json

Bun Configuration

# bunfig.toml
[test]
# Test file patterns
root = "./src"

# Coverage configuration
coverage = true
coverageReporter = ["text", "lcov"]
coverageThreshold = { line = 80, function = 80, statement = 80 }

# Preload scripts
preload = ["./test-setup.ts"]

# Timeout per test (ms)
timeout = 5000

# Bail after N failures (0 = no bail)
bail = 0

Basic Test Patterns

// src/utils/math.test.ts
import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
import { add, multiply, divide, fibonacci, isPrime } from './math';

describe('Math Utilities', () => {
  describe('add', () => {
    it('should add two positive numbers', () => {
      expect(add(2, 3)).toBe(5);
    });

    it('should handle negative numbers', () => {
      expect(add(-1, -2)).toBe(-3);
      expect(add(-1, 5)).toBe(4);
    });

    it('should handle zero', () => {
      expect(add(0, 0)).toBe(0);
      expect(add(5, 0)).toBe(5);
    });

    it('should handle floating point', () => {
      expect(add(0.1, 0.2)).toBeCloseTo(0.3);
    });
  });

  describe('divide', () => {
    it('should divide two numbers', () => {
      expect(divide(10, 2)).toBe(5);
    });

    it('should throw on division by zero', () => {
      expect(() => divide(10, 0)).toThrow('Division by zero');
    });

    it('should handle decimal results', () => {
      expect(divide(1, 3)).toBeCloseTo(0.333, 2);
    });
  });

  describe('fibonacci', () => {
    it('should return correct values for small inputs', () => {
      expect(fibonacci(0)).toBe(0);
      expect(fibonacci(1)).toBe(1);
      expect(fibonacci(2)).toBe(1);
      expect(fibonacci(10)).toBe(55);
    });

    it('should throw for negative inputs', () => {
      expect(() => fibonacci(-1)).toThrow();
    });
  });

  describe('isPrime', () => {
    it.each([2, 3, 5, 7, 11, 13])('should identify %d as prime', (n) => {
      expect(isPrime(n)).toBe(true);
    });

    it.each([0, 1, 4, 6, 8, 9, 10])('should identify %d as not prime', (n) => {
      expect(isPrime(n)).toBe(false);
    });
  });
});