Bun’s Built‑In Test Runner: Write Tests Without Configuration

Problem and Thesis

Developers often need a test runner that requires no extra packages, starts instantly, and watches files for changes. Bun provides exactly that with its built‑in bun test command, letting you write and run JavaScript tests without a package.json or external framework.

Why Bun’s test runner matters

Traditional test setups involve installing Mocha, Jest, or Vitest, configuring scripts, and managing node_modules. Bun’s runner eliminates those steps, delivering sub‑second start times thanks to V8 isolate start‑up and file‑system caching. The result is a frictionless workflow that fits naturally into a Bun project.

Zero‑Config Test Execution

File discovery and glob patterns

The runner automatically discovers any *.js file inside a tests/ directory (or a path you specify with a glob). This means you can place a single test file anywhere in that folder and run bun test to execute it.

If you prefer a custom location, you can pass a glob pattern, e.g. bun test \"src/**/*.test.js\". The command works with both CommonJS (require) and ES modules (import) without additional configuration.

Worked Example

Create a file named example.test.js in a tests/ folder:

// example.test.js
import { expect } from 'bun:test';

test('add', () => {
  expect(1 + 1).toBe(2);
});

Run the command:

bun test example.test.js

Expected terminal output (color‑coded):

PASS example.test.js
  add: ✓

If the test fails, the stack trace includes source‑map information and the failing line is highlighted.

Trade‑offs and Limitations

Folder constraints and Node globals

The runner only auto‑discovers files located in a tests/ directory or a glob you provide. Moving tests outside that structure requires an explicit path, which can be inconvenient for large projects.

Because it runs in a Node‑compatible environment, code that relies on browser‑only APIs (e.g., window or document) will throw errors unless you polyfill or avoid those APIs.

Actionable Closing

To get started, verify your Bun version and explore the help output:

1. Run bun --version to confirm you are on a recent release.
2. Execute bun test --help to see supported flags such as --watch for hot‑reloading.
3. Create a tests/example.test.js file with a simple assertion and run bun test. You should see a passing result printed instantly.

With zero configuration, fast feedback, and clear error reporting, Bun’s built‑in test runner is a practical choice for developers seeking a lightweight testing solution.