Mocking and Stubbing in Bun.js

🧪 Mocking and Stubbing in Bun.js: Mastering Test Isolation

Testing in modern JavaScript applications requires more than just checking if a function returns the correct value. To ensure reliability and performance, we often need to **isolate code behavior**—especially when dealing with APIs, databases, or other services. That's where mocking and stubbing come into play. In this guide, we’ll explore how to handle mocking and stubbing in Bun.js, a lightning-fast JavaScript runtime making waves in the dev world 🚀.

🔍 What are Mocks and Stubs?

Before we dive into Bun.js specifics, let’s clarify the basics:

• Mocks are fake implementations that track interactions (calls, parameters).
• Stubs are fixed responses to simulate specific scenarios (e.g., API errors).

Both are essential when writing unit tests that avoid real network/database calls and instead focus purely on logic.

⚙️ Native Testing in Bun.js

Bun comes with a built-in test runner and assertion system. While it doesn’t yet have full-fledged mocking libraries like Jest, you can still implement mocks/stubs using JavaScript’s functional flexibility.

Let’s walk through examples for both mocking and stubbing in a Bun testing environment.

🔧 Manual Mocking in Bun.js

Suppose you have a module that fetches user data from an API:

// api.js
export async function fetchUser(id) {
  const response = await fetch(`https://api.example.com/users/${id}`);
  return await response.json();
}

To test a function that depends on fetchUser, you can mock it like this:

// test.js
import { expect, test } from "bun:test";
import * as api from "./api.js";

test("mocking fetchUser", async () => {
  // Mock the function
  api.fetchUser = async (id) => {
    return { id, name: "Mocked User" };
  };

  const user = await api.fetchUser(1);
  expect(user.name).toBe("Mocked User");
});

Here, we manually override the function to return mock data instead of performing the actual fetch. Bun executes it fast and clean.

🧱 Creating Reusable Stubs

Let’s say you want to simulate an API failure. You can stub the method to return an error:

test("stubbing API failure", async () => {
  api.fetchUser = async () => {
    throw new Error("API is down");
  };

  try {
    await api.fetchUser();
  } catch (err) {
    expect(err.message).toBe("API is down");
  }
});

This stub helps test how your application behaves when the external service fails—something that’s hard to simulate with live calls.

📦 Using Mock Helpers (Custom Utilities)

You can build helper utilities to make mocking/stubbing easier in your Bun projects:

// mockUtils.js
export function mockFn(returnValue) {
  const fn = (...args) => {
    fn.calls.push(args);
    return returnValue;
  };
  fn.calls = [];
  return fn;
}

Now use this in your test:

import { mockFn } from "./mockUtils.js";

test("custom mock utility", () => {
  const mockedLog = mockFn(undefined);
  mockedLog("hello", "world");

  expect(mockedLog.calls.length).toBe(1);
  expect(mockedLog.calls[0]).toEqual(["hello", "world"]);
});

You’ve now got simple Jest-like mocking inside your Bun tests without external libraries!

🚀 Bun with External Libraries (Future-Proofing)

Right now, many mature mocking tools like sinon or jest-mock don’t work out of the box with Bun. However, as Bun improves its Node.js compatibility layer, these tools may become usable soon.

Until then, Bun’s fast and native execution still makes manual mocking/stubbing easy and efficient.

🧠 Best Practices

• 🔄 Reset mocks between tests to avoid bleed-over
• 📚 Keep mocks simple and focused
• 🧪 Test real services separately using integration tests

✅ Conclusion

Mocking and stubbing are essential tools for writing **isolated, fast, and reliable tests**, and Bun.js supports them well—even if not with full libraries (yet). With native speed and flexible test structure, you can build robust test suites that scale from simple mocks to complex test logic. 🔍🧪

Start small with custom mocks, build reusable stubbing patterns, and gear up for the ever-evolving ecosystem around Bun.js!