jarle/Bun Runtime behavior

Runtime behavior

Learn about Bun test's runtime integration, environment variables, timeouts, and error handling

bun test is deeply integrated with Bun's runtime. This is part of what makes bun test fast and simple to use.

Environment Variables

NODE_ENV

bun test automatically sets $NODE_ENV to "test" unless it's already set in the environment or via .env files. This is standard behavior for most test runners and helps ensure consistent test behavior.

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

test("NODE_ENV is set to test", () => {
  expect(process.env.NODE_ENV).toBe("test");
});

You can override this by setting NODE_ENV explicitly:

NODE_ENV=development bun test

TZ (Timezone)

By default, all bun test runs use UTC (Etc/UTC) as the time zone unless overridden by the TZ environment variable. This ensures consistent date and time behavior across different development environments.

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

test("timezone is UTC by default", () => {
  const date = new Date();
  expect(date.getTimezoneOffset()).toBe(0);
});

To test with a specific timezone:

TZ=America/New_York bun test

Test Timeouts

Each test has a default timeout of 5000ms (5 seconds) if not explicitly overridden. Tests that exceed this timeout will fail.

Global Timeout

Change the timeout globally with the --timeout flag:

bun test --timeout 10000  # 10 seconds

Per-Test Timeout

Set timeout per test as the third parameter to the test function:

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

test("fast test", () => {
  expect(1 + 1).toBe(2);
}, 1000); // 1 second timeout

test("slow test", async () => {
  await new Promise(resolve => setTimeout(resolve, 8000));
}, 10000); // 10 second timeout

Infinite Timeout

Use 0 or Infinity to disable timeout:

test("test without timeout", async () => {
  // This test can run indefinitely
  await someVeryLongOperation();
}, 0);

Error Handling

Unhandled Errors

bun test tracks unhandled promise rejections and errors that occur between tests. If such errors occur, the final exit code will be non-zero (specifically, the count of such errors), even if all tests pass.

This helps catch errors in asynchronous code that might otherwise go unnoticed:

import { test } from "bun:test";

test("test 1", () => {
  // This test passes
  expect(true).toBe(true);
});

// This error happens outside any test
setTimeout(() => {
  throw new Error("Unhandled error");
}, 0);

test("test 2", () => {
  // This test also passes
  expect(true).toBe(true);
});

// The test run will still fail with a non-zero exit code
// because of the unhandled error

Promise Rejections

Unhandled promise rejections are also caught:

import { test } from "bun:test";

test("passing test", () => {
  expect(1).toBe(1);
});

// This will cause the test run to fail
Promise.reject(new Error("Unhandled rejection"));

Custom Error Handling

You can set up custom error handlers in your test setup:

process.on("uncaughtException", error => {
  console.error("Uncaught Exception:", error);
  process.exit(1);
});

process.on("unhandledRejection", (reason, promise) => {
  console.error("Unhandled Rejection at:", promise, "reason:", reason);
  process.exit(1);
});

CLI Flags Integration

Several Bun CLI flags can be used with bun test to modify its behavior:

Memory Usage

# Reduces memory usage for the test runner VM
bun test --smol

Debugging

# Attaches the debugger to the test runner process
bun test --inspect
bun test --inspect-brk

Module Loading

# Runs scripts before test files (useful for global setup/mocks)
bun test --preload ./setup.ts

# Sets compile-time constants
bun test --define "process.env.API_URL='http://localhost:3000'"

# Configures custom loaders
bun test --loader .special:special-loader

# Uses a different tsconfig
bun test --tsconfig-override ./test-tsconfig.json

# Sets package.json conditions for module resolution
bun test --conditions development

# Loads environment variables for tests
bun test --env-file .env.test

Installation-related Flags

# Affect any network requests or auto-installs during test execution
bun test --prefer-offline
bun test --frozen-lockfile

Watch and Hot Reloading

Watch Mode

When running bun test with the --watch flag, the test runner will watch for file changes and re-run affected tests.

bun test --watch

The test runner is smart about which tests to re-run:

import { add } from "./math.js";
import { test, expect } from "bun:test";

test("addition", () => {
  expect(add(2, 3)).toBe(5);
});

If you modify math.js, only math.test.ts will re-run, not all tests.

Hot Reloading

The --hot flag provides similar functionality but is more aggressive about trying to preserve state between runs:

bun test --hot

For most test scenarios, --watch is the recommended option as it provides better isolation between test runs.

Global Variables

The following globals are automatically available in test files without importing (though they can be imported from bun:test if preferred):

// All of these are available globally
test("global test function", () => {
  expect(true).toBe(true);
});

describe("global describe", () => {
  beforeAll(() => {
    // global beforeAll
  });

  it("global it function", () => {
    // it is an alias for test
  });
});

// Jest compatibility
jest.fn();

// Vitest compatibility
vi.fn();

You can also import them explicitly if you prefer:

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

Process Integration

Exit Codes

bun test uses standard exit codes:

• 0: All tests passed, no unhandled errors
• 1: Test failures occurred
• >1: Number of unhandled errors (even if tests passed)

Signal Handling

The test runner properly handles common signals:

# Gracefully stops test execution
kill -SIGTERM <test-process-pid>

# Immediately stops test execution
kill -SIGKILL <test-process-pid>

Environment Detection

Bun automatically detects certain environments and adjusts behavior:

// GitHub Actions detection
if (process.env.GITHUB_ACTIONS) {
  // Bun automatically emits GitHub Actions annotations
}

// CI detection
if (process.env.CI) {
  // Certain behaviors may be adjusted for CI environments
}

Performance Considerations

Single Process

The test runner runs all tests in a single process by default. This provides:

• Faster startup - No need to spawn multiple processes
• Shared memory - Efficient resource usage
• Simple debugging - All tests in one process

However, this means:

• Tests share global state (use lifecycle hooks to clean up)
• One test crash can affect others
• No true parallelization of individual tests

Memory Management

# Monitor memory usage
bun test --smol  # Reduces memory footprint

# For large test suites, consider splitting files
bun test src/unit/
bun test src/integration/

Test Isolation

Since tests run in the same process, ensure proper cleanup:

import { afterEach } from "bun:test";

afterEach(() => {
  // Clean up global state
  global.myGlobalVar = undefined;
  delete process.env.TEST_VAR;

  // Reset modules if needed
  jest.resetModules();
});