bun.sh/docs/test/writing.md

Define tests with a Jest-like API imported from the built-in bun:test module. Long term, Bun aims for complete Jest compatibility; at the moment, a limited set of expect matchers are supported.

Basic usage

To define a simple test:

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

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

{% details summary="Jest-style globals" %} As in Jest, you can use describe, test, expect, and other functions without importing them. Unlike Jest, they are not injected into the global scope. Instead, the Bun transpiler will automatically inject an import from bun:test internally.

typeof globalThis.describe; // "undefined"
typeof describe; // "function"

This transpiler integration only occurs during bun test, and only for test files & preloaded scripts. In practice there's no significant difference to the end user. {% /details %}

Tests can be grouped into suites with describe.

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

describe("arithmetic", () => {
  test("2 + 2", () => {
    expect(2 + 2).toBe(4);
  });

  test("2 * 2", () => {
    expect(2 * 2).toBe(4);
  });
});

Tests can be async.

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

test("2 * 2", async () => {
  const result = await Promise.resolve(2 * 2);
  expect(result).toEqual(4);
});

Alternatively, use the done callback to signal completion. If you include the done callback as a parameter in your test definition, you must call it or the test will hang.

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

test("2 * 2", done => {
  Promise.resolve(2 * 2).then(result => {
    expect(result).toEqual(4);
    done();
  });
});

Skip individual tests with test.skip. These tests will not be run.

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

test.skip("wat", () => {
  // TODO: fix this
  expect(0.1 + 0.2).toEqual(0.3);
});

Mark a test as a todo with test.todo. These tests will be run, and the test runner will expect them to fail. If they pass, you will be prompted to mark it as a regular test.

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

test.todo("fix this", () => {
  myTestFunction();
});

Matchers

Bun implements the following matchers. Full Jest compatibility is on the roadmap; track progress here.

{% table %}

---

• 🟢
• .not

---

• 🟢
• .toBe()

---

• 🟢
• .toEqual()

---

• 🟢
• .toBeNull()

---

• 🟢
• .toBeUndefined()

---

• 🟢
• .toBeNaN()

---

• 🟢
• .toBeDefined()

---

• 🟢
• .toBeFalsy()

---

• 🟢
• .toBeTruthy()

---

• 🟢
• .toContain()

---

• 🟢
• .toStrictEqual()

---

• 🟢
• .toThrow()

---

• 🟢
• .toHaveLength()

---

• 🟢
• .toHaveProperty()

---

• 🔴
• .extend

---

• 🟢
• .anything()

---

• 🟢
• .any()

---

• 🔴
• .arrayContaining()

---

• 🔴
• .assertions()

---

• 🔴
• .closeTo()

---

• 🔴
• .hasAssertions()

---

• 🔴
• .objectContaining()

---

• 🟢
• .stringContaining()

---

• 🟢
• .stringMatching()

---

• 🔴
• .addSnapshotSerializer()

---

• 🟢
• .resolves() (since Bun v0.6.12+)

---

• 🟢
• .rejects() (since Bun v0.6.12+)

---

• 🟢
• .toHaveBeenCalled()

---

• 🟢
• .toHaveBeenCalledTimes()

---

• 🔴
• .toHaveBeenCalledWith()

---

• 🔴
• .toHaveBeenLastCalledWith()

---

• 🔴
• .toHaveBeenNthCalledWith()

---

• 🔴
• .toHaveReturned()

---

• 🔴
• .toHaveReturnedTimes()

---

• 🔴
• .toHaveReturnedWith()

---

• 🔴
• .toHaveLastReturnedWith()

---

• 🔴
• .toHaveNthReturnedWith()

---

• 🟢
• .toBeCloseTo()

---

• 🟢
• .toBeGreaterThan()

---

• 🟢
• .toBeGreaterThanOrEqual()

---

• 🟢
• .toBeLessThan()

---

• 🟢
• .toBeLessThanOrEqual()

---

• 🟢
• .toBeInstanceOf() (Bun v0.5.8+)

---

• 🔴
• .toContainEqual()

---

• 🟢
• .toMatch()

---

• 🟢
• .toMatchObject()

---

• 🟢
• .toMatchSnapshot() (Bun v0.5.8+)

---

• 🔴
• .toMatchInlineSnapshot()

---

• 🔴
• .toThrowErrorMatchingSnapshot()

---

• 🔴
• .toThrowErrorMatchingInlineSnapshot()

{% /table %}