bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/test/reporters.mdx

@@ -0,0 +1,117 @@
+---
+title: Test Reporters
+description:
+---
+
+bun test supports different output formats through reporters. This document covers both built-in reporters and how to implement your own custom reporters.
+
+---
+
+## Built-in Reporters
+
+### Default Console Reporter
+
+By default, bun test outputs results to the console in a human-readable format:
+
+```sh terminal icon="terminal"
+test/package-json-lint.test.ts:
+✓ test/package.json [0.88ms]
+✓ test/js/third_party/grpc-js/package.json [0.18ms]
+✓ test/js/third_party/svelte/package.json [0.21ms]
+✓ test/js/third_party/express/package.json [1.05ms]
+
+ 4 pass
+ 0 fail
+ 4 expect() calls
+Ran 4 tests in 1.44ms
+```
+
+When a terminal doesn't support colors, the output avoids non-ascii characters:
+
+```sh terminal icon="terminal"
+test/package-json-lint.test.ts:
+(pass) test/package.json [0.48ms]
+(pass) test/js/third_party/grpc-js/package.json [0.10ms]
+(pass) test/js/third_party/svelte/package.json [0.04ms]
+(pass) test/js/third_party/express/package.json [0.04ms]
+
+ 4 pass
+ 0 fail
+ 4 expect() calls
+Ran 4 tests across 1 files. [0.66ms]
+```
+
+### JUnit XML Reporter
+
+For CI/CD environments, Bun supports generating JUnit XML reports. JUnit XML is a widely-adopted format for test results that can be parsed by many CI/CD systems, including GitLab, Jenkins, and others.
+
+#### Using the JUnit Reporter
+
+To generate a JUnit XML report, use the `--reporter=junit` flag along with `--reporter-outfile` to specify the output file:
+
+```sh terminal icon="terminal"
+bun test --reporter=junit --reporter-outfile=./junit.xml
+```
+
+This continues to output to the console as usual while also writing the JUnit XML report to the specified path at the end of the test run.
+
+#### Configuring via bunfig.toml
+
+You can also configure the JUnit reporter in your `bunfig.toml` file:
+
+```toml title="bunfig.toml" icon="settings"
+[test.reporter]
+junit = "path/to/junit.xml"  # Output path for JUnit XML report
+```
+
+#### Environment Variables in JUnit Reports
+
+The JUnit reporter automatically includes environment information as `<properties>` in the XML output. This can be helpful for tracking test runs in CI environments.
+
+Specifically, it includes the following environment variables when available:
+
+| Environment Variable                                                    | Property Name | Description            |
+| ----------------------------------------------------------------------- | ------------- | ---------------------- |
+| `GITHUB_RUN_ID`, `GITHUB_SERVER_URL`, `GITHUB_REPOSITORY`, `CI_JOB_URL` | `ci`          | CI build information   |
+| `GITHUB_SHA`, `CI_COMMIT_SHA`, `GIT_SHA`                                | `commit`      | Git commit identifiers |
+| System hostname                                                         | `hostname`    | Machine hostname       |
+
+This makes it easier to track which environment and commit a particular test run was for.
+
+#### Current Limitations
+
+The JUnit reporter currently has a few limitations that will be addressed in future updates:
+
+- `stdout` and `stderr` output from individual tests are not included in the report
+- Precise timestamp fields per test case are not included
+
+### GitHub Actions reporter
+
+Bun test automatically detects when it's running inside GitHub Actions and emits GitHub Actions annotations to the console directly. No special configuration is needed beyond installing Bun and running `bun test`.
+
+For a GitHub Actions workflow configuration example, see the [CI/CD integration](/pm/cli/install#ci%2Fcd) section of the CLI documentation.
+
+---
+
+## Custom Reporters
+
+Bun allows developers to implement custom test reporters by extending the WebKit Inspector Protocol with additional testing-specific domains.
+
+### Inspector Protocol for Testing
+
+To support test reporting, Bun extends the standard WebKit Inspector Protocol with two custom domains:
+
+1. **TestReporter**: Reports test discovery, execution start, and completion events
+2. **LifecycleReporter**: Reports errors and exceptions during test execution
+
+These extensions allow you to build custom reporting tools that can receive detailed information about test execution in real-time.
+
+### Key Events
+
+Custom reporters can listen for these key events:
+
+- `TestReporter.found`: Emitted when a test is discovered
+- `TestReporter.start`: Emitted when a test starts running
+- `TestReporter.end`: Emitted when a test completes
+- `Console.messageAdded`: Emitted when console output occurs during a test
+- `LifecycleReporter.error`: Emitted when an error or exception occurs

package/docs/test/runtime-behavior.mdx

@@ -0,0 +1,342 @@
+---
+title: "Runtime behavior"
+description: "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.
+
+```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)
+
+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.
+
+```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 timezone:
+
+```bash terminal icon="terminal"
+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:
+
+```bash terminal icon="terminal"
+bun test --timeout 10000  # 10 seconds
+```
+
+### Per-Test Timeout
+
+Set timeout per test as the third parameter 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
+
+Use `0` or `Infinity` to disable timeout:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+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:
+
+```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
+
+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
+
+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
+
+Several Bun CLI flags can be used with `bun test` to modify its behavior:
+
+### Memory Usage
+
+```bash terminal icon="terminal"
+# Reduces memory usage for the test runner VM
+bun test --smol
+```
+
+### Debugging
+
+```bash terminal icon="terminal"
+# Attaches the debugger to the test runner process
+bun test --inspect
+bun test --inspect-brk
+```
+
+### 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'"
+
+# 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
+
+```bash
+# 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.
+
+```bash terminal icon="terminal"
+bun test --watch
+```
+
+The test runner is smart about which tests to re-run:
+
+```ts title="math.test.ts" icon="/icons/typescript.svg"
+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:
+
+```bash terminal icon="terminal"
+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):
+
+```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 if you prefer:
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+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:
+
+```bash terminal icon="terminal"
+# 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:
+
+```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
+
+### 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
+
+```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
+
+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;
+
+  // Reset modules if needed
+  jest.resetModules();
+});
+```