Agent skill

bun-test

Configure Bun's built-in test runner with Jest-compatible APIs. Use when setting up testing infrastructure, writing unit/integration/snapshot tests, migrating from Jest, or configuring test coverage. 3-10x faster than Jest.

View SKILL.md on GitHub Repository

Stars 3

Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/DaleSeo/bun-skills/tree/main/skills/bun-test

Metadata

Additional technical details for this skill

tags: bun testing jest unit-tests tdd
author: dale
category: bun-runtime

SKILL.md

Bun Test Configuration

Set up Bun's built-in test runner with Jest-compatible APIs and significantly faster execution (3-10x faster than Jest).

Quick Reference

For detailed patterns, see:

Jest Migration: jest-migration.md - Complete Jest to Bun migration guide
Mocking: mocking.md - Mock functions, spies, module mocking
Examples: examples.md - Test patterns for APIs, databases, async code

Core Workflow

1. Check Prerequisites

bash

# Verify Bun installation
bun --version

# Check if project exists
ls -la package.json

2. Determine Testing Needs

Ask the user what type of testing they need:

Unit Testing: Test individual functions and modules
Integration Testing: Test component interactions
API Testing: Test HTTP endpoints
Snapshot Testing: Test output consistency

3. Create Test Directory Structure

bash

# Create test directories
mkdir -p tests/{unit,integration,fixtures}

Recommended structure:

project/
├── src/
│   ├── utils.ts
│   └── components/
├── tests/
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   ├── fixtures/          # Test data
│   └── setup.ts          # Global setup
├── package.json
└── bunfig.toml           # Test configuration

4. Configure Bun Test

Create bunfig.toml in project root:

toml

[test]
# Preload files before running tests
preload = ["./tests/setup.ts"]

# Code coverage
coverage = true
coverageDir = "coverage"
coverageThreshold = 80

# Timeouts (in milliseconds)
timeout = 5000

# Bail after first failure
bail = false

5. Create Test Setup File

Create tests/setup.ts:

typescript

import { beforeAll, afterAll, beforeEach, afterEach } from "bun:test";

// Global test setup
beforeAll(() => {
  console.log("🧪 Starting test suite");
  process.env.NODE_ENV = "test";
});

afterAll(() => {
  console.log("✅ Test suite complete");
});

// Reset mocks before each test
beforeEach(() => {
  // Clear mock state
});

afterEach(() => {
  // Cleanup after each test
});

// Global test utilities
globalThis.testHelpers = {
  wait: (ms: number) => new Promise(resolve => setTimeout(resolve, ms)),
};

6. Write First Test

Create tests/unit/example.test.ts:

typescript

import { describe, it, expect, test } from "bun:test";

// Simple test
test("addition works", () => {
  expect(1 + 1).toBe(2);
});

// Describe blocks for organization
describe("Array utilities", () => {
  it("should filter even numbers", () => {
    const numbers = [1, 2, 3, 4, 5, 6];
    const evens = numbers.filter(n => n % 2 === 0);

    expect(evens).toEqual([2, 4, 6]);
    expect(evens).toHaveLength(3);
  });
});

// Async tests
describe("Async operations", () => {
  it("should handle promises", async () => {
    const result = await Promise.resolve(42);
    expect(result).toBe(42);
  });
});

For more test examples (API testing, database testing, etc.), see examples.md.

7. Add Mocking (If Needed)

typescript

import { describe, it, expect, mock, spyOn } from "bun:test";

describe("Mock functions", () => {
  it("should create mock functions", () => {
    const mockFn = mock((x: number) => x * 2);

    const result = mockFn(5);

    expect(result).toBe(10);
    expect(mockFn).toHaveBeenCalledTimes(1);
    expect(mockFn).toHaveBeenCalledWith(5);
  });

  it("should spy on methods", () => {
    const obj = {
      method: (x: number) => x * 2,
    };

    const spy = spyOn(obj, "method");

    obj.method(5);

    expect(spy).toHaveBeenCalledWith(5);
    expect(spy).toHaveReturnedWith(10);
  });
});

For advanced mocking patterns, see mocking.md.

8. Update package.json

Add test scripts:

json

{
  "scripts": {
    "test": "bun test",
    "test:watch": "bun test --watch",
    "test:coverage": "bun test --coverage",
    "test:ui": "bun test --coverage --reporter=html"
  }
}

9. Run Tests

bash

# Run all tests
bun test

# Run specific file
bun test tests/unit/utils.test.ts

# Watch mode
bun test --watch

# With coverage
bun test --coverage

# Filter by name
bun test --test-name-pattern="should handle"

Jest Migration

If migrating from Jest, see jest-migration.md for:

Import updates (@jest/globals → bun:test)
Mock syntax changes (jest.fn() → mock())
Configuration migration
Compatibility notes

Key changes:

typescript

// Before (Jest)
import { describe, it, expect } from '@jest/globals';
const mockFn = jest.fn();

// After (Bun)
import { describe, it, expect, mock } from 'bun:test';
const mockFn = mock();

Common Test Patterns

Testing Functions

typescript

import { test, expect } from "bun:test";

function add(a: number, b: number): number {
  return a + b;
}

test("add function", () => {
  expect(add(2, 3)).toBe(5);
  expect(add(-1, 1)).toBe(0);
});

Testing Errors

typescript

test("should throw errors", () => {
  const throwError = () => {
    throw new Error("Something went wrong");
  };

  expect(throwError).toThrow("Something went wrong");
  expect(throwError).toThrow(Error);
});

test("should reject promises", async () => {
  const asyncReject = async () => {
    throw new Error("Async error");
  };

  await expect(asyncReject()).rejects.toThrow("Async error");
});

Snapshot Testing

typescript

test("should match snapshot", () => {
  const data = {
    id: 1,
    name: "Test User",
    email: "test@example.com",
  };

  expect(data).toMatchSnapshot();
});

test("should match inline snapshot", () => {
  const config = { theme: "dark", language: "en" };

  expect(config).toMatchInlineSnapshot(`
    {
      "theme": "dark",
      "language": "en"
    }
  `);
});

Matchers Reference

Common matchers available:

typescript

// Equality
expect(value).toBe(expected);           // ===
expect(value).toEqual(expected);        // Deep equality

// Truthiness
expect(value).toBeTruthy();
expect(value).toBeFalsy();
expect(value).toBeDefined();
expect(value).toBeUndefined();

// Numbers
expect(number).toBeGreaterThan(3);
expect(number).toBeLessThan(5);

// Strings
expect(string).toMatch(/pattern/);
expect(string).toContain("substring");

// Arrays
expect(array).toContain(item);
expect(array).toHaveLength(3);

// Objects
expect(object).toHaveProperty("key");
expect(object).toMatchObject({ subset });

// Promises
await expect(promise).resolves.toBe(value);
await expect(promise).rejects.toThrow();

// Mock functions
expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledTimes(3);
expect(mockFn).toHaveBeenCalledWith(arg1, arg2);

Test Organization

Setup and Teardown

typescript

import { beforeAll, afterAll, beforeEach, afterEach, describe, it } from "bun:test";

describe("User service", () => {
  let db: Database;

  beforeAll(async () => {
    // Setup before all tests
    db = await connectToDatabase();
  });

  afterAll(async () => {
    // Cleanup after all tests
    await db.close();
  });

  beforeEach(async () => {
    // Reset before each test
    await db.clear();
  });

  it("should create user", async () => {
    const user = await db.users.create({ name: "Test" });
    expect(user.id).toBeDefined();
  });
});

Coverage Configuration

View coverage report:

bash

# Generate coverage
bun test --coverage

# View HTML report
bun test --coverage --reporter=html
open coverage/index.html

Set coverage thresholds in bunfig.toml:

toml

[test]
coverage = true
coverageThreshold = 80  # Fail if coverage < 80%

Debugging Tests

bash

# Run with debugger
bun test --inspect

# Verbose output
bun test --verbose

# Show all test results
bun test --reporter=tap

Performance

Bun test is significantly faster than Jest:

Jest: ~15 seconds for 100 tests
Bun: ~2 seconds for 100 tests

3-10x faster execution!

Completion Checklist

✅ Test directory structure created
✅ bunfig.toml configured
✅ Test setup file created
✅ Example tests written
✅ Package.json scripts updated
✅ Tests run successfully
✅ Coverage configured (if needed)

Next Steps

After basic setup:

Write tests: Add tests for critical business logic
CI/CD: Configure tests to run in your pipeline
Coverage: Set up coverage reporting
Pre-commit: Add pre-commit hooks to run tests
Documentation: Document testing patterns for the team

For detailed implementations, see the reference files linked above.

Maintainer

DaleSeo Core maintainer

Source details

Full Name: DaleSeo/bun-skills
Branch: main
Path in repo: skills/bun-test
License: MIT License
Topics: agent-skills bun

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

DaleSeo/bun-skills

deno-to-bun

Migrate Deno projects to Bun with API compatibility analysis. Use when converting Deno.* APIs to Bun equivalents, migrating from Deno Deploy, or updating permissions model and import maps.

3 1

Explore

DaleSeo/bun-skills

bun-build

Create optimized production bundles with Bun's native bundler. Use when building applications for production, optimizing bundle sizes, setting up multi-environment builds, or replacing webpack/esbuild/rollup.

3 1

Explore

DaleSeo/bun-skills

bun-init

Initialize a new Bun project with TypeScript and optimal configuration. Use when starting a new Bun project or converting a directory to a Bun project.

3 1

Explore

DaleSeo/bun-skills

cloudflare-to-bun

Migrate Cloudflare Workers to Bun with runtime compatibility analysis. Use when converting Workers to Bun, migrating from Cloudflare bindings, or moving from edge to server deployment.

3 1

Explore

DaleSeo/bun-skills

bun-deploy

Generate optimized Docker images for Bun applications. Use when deploying to containers, minimizing image sizes, setting up CI/CD pipelines, or deploying to Kubernetes.

3 1

Explore

DaleSeo/bun-skills

bun-dev-server

Set up high-performance development servers with Hot Module Replacement. Use when creating dev servers for web apps, setting up React Fast Refresh, or configuring API servers with live reload.

3 1

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

Metadata

SKILL.md

Bun Test Configuration

Quick Reference

Core Workflow

1. Check Prerequisites

2. Determine Testing Needs

3. Create Test Directory Structure

4. Configure Bun Test

5. Create Test Setup File

6. Write First Test

7. Add Mocking (If Needed)

8. Update package.json

9. Run Tests

Jest Migration

Common Test Patterns

Testing Functions

Testing Errors

Snapshot Testing

Matchers Reference

Test Organization

Setup and Teardown

Coverage Configuration

Debugging Tests

Performance

Completion Checklist

Next Steps

Recommended Agent Skills

deno-to-bun

bun-build

bun-init

cloudflare-to-bun

bun-deploy

bun-dev-server