bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/test/configuration.mdx

@@ -0,0 +1,467 @@
+---
+title: "Test configuration"
+description: "Learn how to configure Bun test behavior using bunfig.toml and command-line options"
+---
+
+Configure `bun test` via `bunfig.toml` file and command-line options. This page documents the available configuration options for `bun test`.
+
+## Configuration File
+
+You can configure `bun test` behavior by adding a `[test]` section to your `bunfig.toml` file:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Options go here
+```
+
+## Test Discovery
+
+### root
+
+The `root` option specifies a root directory for test discovery, overriding the default behavior of scanning from the project root.
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+root = "src"  # Only scan for tests in the src directory
+```
+
+This is useful when you want to:
+
+- Limit test discovery to specific directories
+- Exclude certain parts of your project from test scanning
+- Organize tests in a specific subdirectory structure
+
+#### Examples
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Only run tests in the src directory
+root = "src"
+
+# Run tests in a specific test directory
+root = "tests"
+
+# Run tests in multiple specific directories (not currently supported - use patterns instead)
+# root = ["src", "lib"]  # This syntax is not supported
+```
+
+### Preload Scripts
+
+Load scripts before running tests using the `preload` option:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+preload = ["./test-setup.ts", "./global-mocks.ts"]
+```
+
+This is equivalent to using `--preload` on the command line:
+
+```bash terminal icon="terminal"
+bun test --preload ./test-setup.ts --preload ./global-mocks.ts
+```
+
+#### Common Preload Use Cases
+
+```ts title="test-setup.ts" icon="/icons/typescript.svg"
+// Global test setup
+import { beforeAll, afterAll } from "bun:test";
+
+beforeAll(() => {
+  // Set up test database
+  setupTestDatabase();
+});
+
+afterAll(() => {
+  // Clean up
+  cleanupTestDatabase();
+});
+```
+
+```ts title="global-mocks.ts" icon="/icons/typescript.svg"
+// Global mocks
+import { mock } from "bun:test";
+
+// Mock environment variables
+process.env.NODE_ENV = "test";
+process.env.API_URL = "http://localhost:3001";
+
+// Mock external dependencies
+mock.module("./external-api", () => ({
+  fetchData: mock(() => Promise.resolve({ data: "test" })),
+}));
+```
+
+## Timeouts
+
+### Default Timeout
+
+Set the default timeout for all tests:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+timeout = 10000  # 10 seconds (default is 5000ms)
+```
+
+This applies to all tests unless overridden by individual test timeouts:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+// This test will use the default timeout from bunfig.toml
+test("uses default timeout", () => {
+  // test implementation
+});
+
+// This test overrides the default timeout
+test("custom timeout", () => {
+  // test implementation
+}, 30000); // 30 seconds
+```
+
+## Reporters
+
+### JUnit Reporter
+
+Configure the JUnit reporter output file path directly in the config file:
+
+```toml title="bunfig.toml" icon="settings"
+[test.reporter]
+junit = "path/to/junit.xml"  # Output path for JUnit XML report
+```
+
+This complements the `--reporter=junit` and `--reporter-outfile` CLI flags:
+
+```bash terminal icon="terminal"
+# Equivalent command line usage
+bun test --reporter=junit --reporter-outfile=./junit.xml
+```
+
+#### Multiple Reporters
+
+You can use multiple reporters simultaneously:
+
+```bash terminal icon="terminal"
+# CLI approach
+bun test --reporter=junit --reporter-outfile=./junit.xml
+
+# Config file approach
+```
+
+```toml title="bunfig.toml" icon="settings"
+[test.reporter]
+junit = "./reports/junit.xml"
+
+[test]
+# Also enable coverage reporting
+coverage = true
+coverageReporter = ["text", "lcov"]
+```
+
+## Memory Usage
+
+### smol Mode
+
+Enable the `--smol` memory-saving mode specifically for the test runner:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+smol = true  # Reduce memory usage during test runs
+```
+
+This is equivalent to using the `--smol` flag on the command line:
+
+```bash terminal icon="terminal"
+bun test --smol
+```
+
+The `smol` mode reduces memory usage by:
+
+- Using less memory for the JavaScript heap
+- Being more aggressive about garbage collection
+- Reducing buffer sizes where possible
+
+This is useful for:
+
+- CI environments with limited memory
+- Large test suites that consume significant memory
+- Development environments with memory constraints
+
+## Coverage Options
+
+### Basic Coverage Settings
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Enable coverage by default
+coverage = true
+
+# Set coverage reporter
+coverageReporter = ["text", "lcov"]
+
+# Set coverage output directory
+coverageDir = "./coverage"
+```
+
+### Skip Test Files from Coverage
+
+Exclude files matching test patterns (e.g., `*.test.ts`) from the coverage report:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+coverageSkipTestFiles = true  # Exclude test files from coverage reports
+```
+
+### Coverage Thresholds
+
+The coverage threshold can be specified either as a number or as an object with specific thresholds:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Simple threshold - applies to lines, functions, and statements
+coverageThreshold = 0.8
+
+# Detailed thresholds
+coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }
+```
+
+Setting any of these enables `fail_on_low_coverage`, causing the test run to fail if coverage is below the threshold.
+
+#### Threshold Examples
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Require 90% coverage across the board
+coverageThreshold = 0.9
+
+# Different requirements for different metrics
+coverageThreshold = {
+  lines = 0.85,      # 85% line coverage
+  functions = 0.90,  # 90% function coverage
+  statements = 0.80  # 80% statement coverage
+}
+```
+
+### Coverage Path Ignore Patterns
+
+Exclude specific files or file patterns from coverage reports using glob patterns:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Single pattern
+coveragePathIgnorePatterns = "**/*.spec.ts"
+
+# Multiple patterns
+coveragePathIgnorePatterns = [
+  "**/*.spec.ts",
+  "**/*.test.ts",
+  "src/utils/**",
+  "*.config.js",
+  "generated/**",
+  "vendor/**"
+]
+```
+
+Files matching any of these patterns will be excluded from coverage calculation and reporting. See the [coverage documentation](/test/code-coverage) for more details and examples.
+
+#### Common Ignore Patterns
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+coveragePathIgnorePatterns = [
+  # Test files
+  "**/*.test.ts",
+  "**/*.spec.ts",
+  "**/*.e2e.ts",
+
+  # Configuration files
+  "*.config.js",
+  "*.config.ts",
+  "webpack.config.*",
+  "vite.config.*",
+
+  # Build output
+  "dist/**",
+  "build/**",
+  ".next/**",
+
+  # Generated code
+  "generated/**",
+  "**/*.generated.ts",
+
+  # Vendor/third-party
+  "vendor/**",
+  "third-party/**",
+
+  # Utilities that don't need testing
+  "src/utils/constants.ts",
+  "src/types/**"
+]
+```
+
+### Sourcemap Handling
+
+Internally, Bun transpiles every file. That means code coverage must also go through sourcemaps before they can be reported. We expose this as a flag to allow you to opt out of this behavior, but it will be confusing because during the transpilation process, Bun may move code around and change variable names. This option is mostly useful for debugging coverage issues.
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+coverageIgnoreSourcemaps = true  # Don't use sourcemaps for coverage analysis
+```
+
+<Warning>
+  When using this option, you probably want to stick a `// @bun` comment at the top of the source file to opt out of the
+  transpilation process.
+</Warning>
+
+## Install Settings Inheritance
+
+The `bun test` command inherits relevant network and installation configuration (registry, cafile, prefer, exact, etc.) from the `[install]` section of `bunfig.toml`. This is important if tests need to interact with private registries or require specific install behaviors triggered during the test run.
+
+```toml title="bunfig.toml" icon="settings"
+[install]
+# These settings are inherited by bun test
+registry = "https://npm.company.com/"
+exact = true
+prefer = "offline"
+
+[test]
+# Test-specific configuration
+coverage = true
+timeout = 10000
+```
+
+## Environment Variables
+
+You can also set environment variables in your configuration that affect test behavior:
+
+```toml title="bunfig.toml" icon="settings"
+[env]
+NODE_ENV = "test"
+DATABASE_URL = "postgresql://localhost:5432/test_db"
+LOG_LEVEL = "error"
+
+[test]
+coverage = true
+```
+
+## Complete Configuration Example
+
+Here's a comprehensive example showing all available test configuration options:
+
+```toml title="bunfig.toml" icon="settings"
+[install]
+# Install settings inherited by tests
+registry = "https://registry.npmjs.org/"
+exact = true
+
+[env]
+# Environment variables for tests
+NODE_ENV = "test"
+DATABASE_URL = "postgresql://localhost:5432/test_db"
+API_URL = "http://localhost:3001"
+LOG_LEVEL = "error"
+
+[test]
+# Test discovery
+root = "src"
+preload = ["./test-setup.ts", "./global-mocks.ts"]
+
+# Execution settings
+timeout = 10000
+smol = true
+
+# Coverage configuration
+coverage = true
+coverageReporter = ["text", "lcov"]
+coverageDir = "./coverage"
+coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
+coverageSkipTestFiles = true
+coveragePathIgnorePatterns = [
+  "**/*.spec.ts",
+  "src/utils/**",
+  "*.config.js",
+  "generated/**"
+]
+
+# Advanced coverage settings
+coverageIgnoreSourcemaps = false
+
+# Reporter configuration
+[test.reporter]
+junit = "./reports/junit.xml"
+```
+
+## CLI Override Behavior
+
+Command-line options always override configuration file settings:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+timeout = 5000
+coverage = false
+```
+
+```bash terminal icon="terminal"
+# These CLI flags override the config file
+bun test --timeout 10000 --coverage
+# timeout will be 10000ms and coverage will be enabled
+```
+
+## Conditional Configuration
+
+You can use different configurations for different environments:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Default test configuration
+coverage = false
+timeout = 5000
+
+# Override for CI environment
+[test.ci]
+coverage = true
+coverageThreshold = 0.8
+timeout = 30000
+```
+
+Then in CI:
+
+```bash terminal icon="terminal"
+# Use CI-specific settings
+bun test --config=ci
+```
+
+## Validation and Troubleshooting
+
+### Invalid Configuration
+
+Bun will warn about invalid configuration options:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+invalidOption = true  # This will generate a warning
+```
+
+### Common Configuration Issues
+
+1. **Path Resolution**: Relative paths in config are resolved relative to the config file location
+2. **Pattern Matching**: Glob patterns use standard glob syntax
+3. **Type Mismatches**: Ensure numeric values are not quoted unless they should be strings
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+# Correct
+timeout = 10000
+
+# Incorrect - will be treated as string
+timeout = "10000"
+```
+
+### Debugging Configuration
+
+To see what configuration is being used:
+
+```bash terminal icon="terminal"
+# Show effective configuration
+bun test --dry-run
+
+# Verbose output to see configuration loading
+bun test --verbose
+```

package/docs/test/dates-times.mdx

@@ -0,0 +1,129 @@
+---
+title: "Dates and times"
+description: "Learn how to manipulate time and dates in your Bun tests using setSystemTime and Jest compatibility functions"
+---
+
+`bun:test` lets you change what time it is in your tests.
+
+This works with any of the following:
+
+- `Date.now`
+- `new Date()`
+- `new Intl.DateTimeFormat().format()`
+
+<Note>Timers are not impacted yet, but may be in a future release of Bun.</Note>
+
+## setSystemTime
+
+To change the system time, use `setSystemTime`:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { setSystemTime, beforeAll, test, expect } from "bun:test";
+
+beforeAll(() => {
+  setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+});
+
+test("it is 2020", () => {
+  expect(new Date().getFullYear()).toBe(2020);
+});
+```
+
+To support existing tests that use Jest's `useFakeTimers` and `useRealTimers`, you can use `useFakeTimers` and `useRealTimers`:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+test("just like in jest", () => {
+  jest.useFakeTimers();
+  jest.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+  expect(new Date().getFullYear()).toBe(2020);
+  jest.useRealTimers();
+  expect(new Date().getFullYear()).toBeGreaterThan(2020);
+});
+
+test("unlike in jest", () => {
+  const OriginalDate = Date;
+  jest.useFakeTimers();
+  if (typeof Bun === "undefined") {
+    // In Jest, the Date constructor changes
+    // That can cause all sorts of bugs because suddenly Date !== Date before the test.
+    expect(Date).not.toBe(OriginalDate);
+    expect(Date.now).not.toBe(OriginalDate.now);
+  } else {
+    // In bun:test, Date constructor does not change when you useFakeTimers
+    expect(Date).toBe(OriginalDate);
+    expect(Date.now).toBe(OriginalDate.now);
+  }
+});
+```
+
+<Warning>
+  **Timers** — Note that we have not implemented builtin support for mocking timers yet, but this is on the roadmap.
+</Warning>
+
+## Reset the system time
+
+To reset the system time, pass no arguments to `setSystemTime`:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { setSystemTime, expect, test } from "bun:test";
+
+test("it was 2020, for a moment.", () => {
+  // Set it to something!
+  setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+  expect(new Date().getFullYear()).toBe(2020);
+
+  // reset it!
+  setSystemTime();
+
+  expect(new Date().getFullYear()).toBeGreaterThan(2020);
+});
+```
+
+## Get mocked time with jest.now()
+
+When you're using mocked time (with `setSystemTime` or `useFakeTimers`), you can use `jest.now()` to get the current mocked timestamp:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { test, expect, jest } from "bun:test";
+
+test("get the current mocked time", () => {
+  jest.useFakeTimers();
+  jest.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+  expect(Date.now()).toBe(1577836800000); // Jan 1, 2020 timestamp
+  expect(jest.now()).toBe(1577836800000); // Same value
+
+  jest.useRealTimers();
+});
+```
+
+This is useful when you need to access the mocked time directly without creating a new Date object.
+
+## Set the time zone
+
+By default, the time zone for all `bun test` runs is set to UTC (`Etc/UTC`) unless overridden. To change the time zone, either pass the `$TZ` environment variable to `bun test`:
+
+```bash terminal icon="terminal"
+TZ=America/Los_Angeles bun test
+```
+
+Or set `process.env.TZ` at runtime:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+test("Welcome to California!", () => {
+  process.env.TZ = "America/Los_Angeles";
+  expect(new Date().getTimezoneOffset()).toBe(420);
+  expect(new Intl.DateTimeFormat().resolvedOptions().timeZone).toBe("America/Los_Angeles");
+});
+
+test("Welcome to New York!", () => {
+  // Unlike in Jest, you can set the timezone multiple times at runtime and it will work.
+  process.env.TZ = "America/New_York";
+  expect(new Date().getTimezoneOffset()).toBe(240);
+  expect(new Intl.DateTimeFormat().resolvedOptions().timeZone).toBe("America/New_York");
+});
+```
+
+<Info>Unlike in Jest, you can set the timezone multiple times at runtime and it will work.</Info>

package/docs/test/discovery.mdx

@@ -0,0 +1,90 @@
+---
+title: "Finding tests"
+description: "Learn how Bun's test runner discovers and filters test files in your project"
+---
+
+bun test's file discovery mechanism determines which files to run as tests. Understanding how it works helps you structure your test files effectively.
+
+## Default Discovery Logic
+
+By default, `bun test` recursively searches the project directory for files that match specific patterns:
+
+- `*.test.{js|jsx|ts|tsx}` - Files ending with `.test.js`, `.test.jsx`, `.test.ts`, or `.test.tsx`
+- `*_test.{js|jsx|ts|tsx}` - Files ending with `_test.js`, `_test.jsx`, `_test.ts`, or `_test.tsx`
+- `*.spec.{js|jsx|ts|tsx}` - Files ending with `.spec.js`, `.spec.jsx`, `.spec.ts`, or `.spec.tsx`
+- `*_spec.{js|jsx|ts|tsx}` - Files ending with `_spec.js`, `_spec.jsx`, `_spec.ts`, or `_spec.tsx`
+
+## Exclusions
+
+By default, Bun test ignores:
+
+- `node_modules` directories
+- Hidden directories (those starting with a period `.`)
+- Files that don't have JavaScript-like extensions (based on available loaders)
+
+## Customizing Test Discovery
+
+### Position Arguments as Filters
+
+You can filter which test files run by passing additional positional arguments to `bun test`:
+
+```bash terminal icon="terminal"
+bun test <filter> <filter> ...
+```
+
+Any test file with a path that contains one of the filters will run. These filters are simple substring matches, not glob patterns.
+
+For example, to run all tests in a `utils` directory:
+
+```bash terminal icon="terminal"
+bun test utils
+```
+
+This would match files like `src/utils/string.test.ts` and `lib/utils/array_test.js`.
+
+### Specifying Exact File Paths
+
+To run a specific file in the test runner, make sure the path starts with `./` or `/` to distinguish it from a filter name:
+
+```bash terminal icon="terminal"
+bun test ./test/specific-file.test.ts
+```
+
+### Filter by Test Name
+
+To filter tests by name rather than file path, use the `-t`/`--test-name-pattern` flag with a regex pattern:
+
+```sh terminal icon="terminal"
+# run all tests with "addition" in the name
+bun test --test-name-pattern addition
+```
+
+The pattern is matched against a concatenated string of the test name prepended with the labels of all its parent describe blocks, separated by spaces. For example, a test defined as:
+
+```ts title="math.test.ts" icon="/icons/typescript.svg"
+describe("Math", () => {
+  describe("operations", () => {
+    test("should add correctly", () => {
+      // ...
+    });
+  });
+});
+```
+
+Would be matched against the string "Math operations should add correctly".
+
+### Changing the Root Directory
+
+By default, Bun looks for test files starting from the current working directory. You can change this with the `root` option in your `bunfig.toml`:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+root = "src"  # Only scan for tests in the src directory
+```
+
+## Execution Order
+
+Tests are run in the following order:
+
+1. Test files are executed sequentially (not in parallel)
+2. Within each file, tests run sequentially based on their definition order