# Runtime behavior (/docs/test/runtime-behavior)

<!-- agent-signals: reading_time_min: 5 · est_tokens: 1994 · updated: 2026-07-28 -->
Related: [Writing tests](/docs/test/writing-tests.md), [Test configuration](/docs/test/configuration.md), [Finding tests](/docs/test/discovery.md), [Lifecycle hooks](/docs/test/lifecycle.md), [Mocks](/docs/test/mocks.md), [Snapshots](/docs/test/snapshots.md)

`bun test` is deeply integrated with Bun's runtime. This integration is part of what makes `bun test` fast.

## Environment Variables [#environment-variables]

### NODE\_ENV [#node_env]

`bun test` sets `$NODE_ENV` to `"test"` unless it's already set in the environment or in `.env` files. Most test runners do the same.

```ts title="test.ts" icon="/icons/typescript.svg"
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:

```bash terminal icon="terminal"
NODE_ENV=development bun test
```

### TZ (Timezone) [#tz-timezone]

`bun test` uses UTC (`Etc/UTC`) as the time zone unless the `TZ` environment variable overrides it. This keeps date and time behavior consistent across machines.

```ts title="test.ts" icon="/icons/typescript.svg"
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 time zone:

```bash terminal icon="terminal"
TZ=America/New_York bun test
```

## Test Timeouts [#test-timeouts]

Each test has a default timeout of 5000ms (5 seconds). Tests that exceed it fail.

### Global Timeout [#global-timeout]

Change the timeout globally with the `--timeout` flag:

```bash terminal icon="terminal"
bun test --timeout 10000  # 10 seconds
```

### Per-Test Timeout [#per-test-timeout]

Set a per-test timeout as the third argument to the test function:

```ts title="test.ts" icon="/icons/typescript.svg"
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 [#infinite-timeout]

Use `0` or `Infinity` to disable the timeout:

```ts title="test.ts" icon="/icons/typescript.svg"
test("test without timeout", async () => {
  // This test can run indefinitely
  await someVeryLongOperation();
}, 0);
```

## Error Handling [#error-handling]

### Unhandled Errors [#unhandled-errors]

`bun test` tracks unhandled promise rejections and errors that occur between tests. If any occur, the final exit code is non-zero, even if all tests pass.

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

```ts title="test.ts" icon="/icons/typescript.svg"
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 [#promise-rejections]

Unhandled promise rejections are also caught:

```ts title="test.ts" icon="/icons/typescript.svg"
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 [#custom-error-handling]

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

```ts title="test-setup.ts" icon="/icons/typescript.svg"
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 [#cli-flags-integration]

Several Bun CLI flags also work with `bun test`:

### Memory Usage [#memory-usage]

```bash terminal icon="terminal"
# Reduces memory usage for the test runner VM
bun test --smol
```

### Debugging [#debugging]

```bash terminal icon="terminal"
# Attaches the debugger to the test runner process
bun test --inspect
bun test --inspect-brk
```

### Module Loading [#module-loading]

```bash terminal icon="terminal"
# 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'"

# Maps file extensions to built-in loaders
bun test --loader .svg:text

# 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 [#installation-related-flags]

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

## Watch and Hot Reloading [#watch-and-hot-reloading]

### Watch Mode [#watch-mode]

With the `--watch` flag, the test runner watches for file changes and re-runs tests.

```bash terminal icon="terminal"
bun test --watch
```

### Hot Reloading [#hot-reloading]

The `--hot` flag is similar, but more aggressive about preserving state between runs:

```bash terminal icon="terminal"
bun test --hot
```

For most tests, use `--watch`: it gives better isolation between runs.

## Global Variables [#global-variables]

The following globals are available in test files without importing:

```ts title="test.ts" icon="/icons/typescript.svg"
// 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:

```ts title="test.ts" icon="/icons/typescript.svg"
import { test, it, describe, expect, beforeAll, beforeEach, afterAll, afterEach, jest, vi } from "bun:test";
```

## Process Integration [#process-integration]

### Exit Codes [#exit-codes]

`bun test` uses standard exit codes:

* `0`: All tests passed, no unhandled errors
* `1`: Test failures or unhandled errors occurred

### Signal Handling [#signal-handling]

The test runner handles common signals:

```bash terminal icon="terminal"
# Gracefully stops test execution
kill -SIGTERM <test-process-pid>

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

### Environment Detection [#environment-detection]

Bun automatically detects certain environments and adjusts behavior:

```ts title="test.ts" icon="/icons/typescript.svg"
// 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 [#performance-considerations]

### Single Process [#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 [#memory-management]

```bash terminal icon="terminal"
# 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 [#test-isolation]

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

```ts title="test.ts" icon="/icons/typescript.svg"
import { afterEach } from "bun:test";

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

  // Restore mocked functions if needed
  jest.restoreAllMocks();
});
```