bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/test/reporters.md

@@ -1,117 +0,0 @@
-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
-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
-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]
-```
-
-### Dots Reporter
-
-The dots reporter shows `.` for passing tests and `F` for failures—useful for large test suites.
-
-```sh
-$ bun test --dots
-$ bun test --reporter=dots
-```
-
-### 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
-$ 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
-[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](../cli/test.md#cicd-integration) 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.md

@@ -1,95 +0,0 @@
-`bun test` is deeply integrated with Bun's runtime. This is part of what makes `bun test` fast and simple to use.
-
-#### `$NODE_ENV` environment variable
-
-`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
-import { test, expect } from "bun:test";
-
-test("NODE_ENV is set to test", () => {
-  expect(process.env.NODE_ENV).toBe("test");
-});
-```
-
-When `NODE_ENV` is set to `"test"`, Bun will not load `.env.local` files. This ensures consistent test environments across different executions by preventing local overrides during testing. Instead, use `.env.test` for test-specific environment variables, which should be committed to your repository for consistency across all developers and CI environments.
-
-#### `$TZ` environment variable
-
-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.
-
-#### Test Timeouts
-
-Each test has a default timeout of 5000ms (5 seconds) if not explicitly overridden. Tests that exceed this timeout will fail. This can be changed globally with the `--timeout` flag or per-test as the third parameter to the test function.
-
-## 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
-import { test } from "bun:test";
-
-test("test 1", () => {
-  // This test passes
-});
-
-// This error happens outside any test
-setTimeout(() => {
-  throw new Error("Unhandled error");
-}, 0);
-
-test("test 2", () => {
-  // This test also passes
-});
-
-// The test run will still fail with a non-zero exit code
-// because of the unhandled error
-```
-
-Internally, this occurs with a higher precedence than `process.on("unhandledRejection")` or `process.on("uncaughtException")`, which makes it simpler to integrate with existing code.
-
-## Using General CLI Flags with Tests
-
-Several Bun CLI flags can be used with `bun test` to modify its behavior:
-
-### Memory Usage
-
-- `--smol`: Reduces memory usage for the test runner VM
-
-### Debugging
-
-- `--inspect`, `--inspect-brk`: Attaches the debugger to the test runner process
-
-### Module Loading
-
-- `--preload`: Runs scripts before test files (useful for global setup/mocks)
-- `--define`: Sets compile-time constants
-- `--loader`: Configures custom loaders
-- `--tsconfig-override`: Uses a different tsconfig
-- `--conditions`: Sets package.json conditions for module resolution
-- `--env-file`: Loads environment variables for tests
-
-### Installation-related Flags
-
-- `--prefer-offline`, `--frozen-lockfile`, etc.: Affect any network requests or auto-installs during test execution
-
-## Watch and Hot Reloading
-
-When running `bun test` with the `--watch` flag, the test runner will watch for file changes and re-run affected tests.
-
-The `--hot` flag provides similar functionality but is more aggressive about trying to preserve state between runs. For most test scenarios, `--watch` is the recommended option.
-
-## Global Variables
-
-The following globals are automatically available in test files without importing (though they can be imported from `bun:test` if preferred):
-
-- `test`, `it`: Define tests
-- `describe`: Group tests
-- `expect`: Make assertions
-- `beforeAll`, `beforeEach`, `afterAll`, `afterEach`: Lifecycle hooks
-- `jest`: Jest global object
-- `vi`: Vitest compatibility alias for common jest methods

package/docs/test/snapshots.md

@@ -1,68 +0,0 @@
-Snapshot testing saves the output of a value and compares it against future test runs. This is particularly useful for UI components, complex objects, or any output that needs to remain consistent.
-
-## Basic snapshots
-
-Snapshot tests are written using the `.toMatchSnapshot()` matcher:
-
-```ts
-import { test, expect } from "bun:test";
-
-test("snap", () => {
-  expect("foo").toMatchSnapshot();
-});
-```
-
-The first time this test is run, the argument to `expect` will be serialized and written to a special snapshot file in a `__snapshots__` directory alongside the test file. On future runs, the argument is compared against the snapshot on disk. Snapshots can be re-generated with the following command:
-
-```bash
-$ bun test --update-snapshots
-```
-
-## Inline snapshots
-
-For smaller values, you can use inline snapshots with `.toMatchInlineSnapshot()`. These snapshots are stored directly in your test file:
-
-```ts
-import { test, expect } from "bun:test";
-
-test("inline snapshot", () => {
-  // First run: snapshot will be inserted automatically
-  expect({ hello: "world" }).toMatchInlineSnapshot();
-
-  // After first run, the test file will be updated to:
-  // expect({ hello: "world" }).toMatchInlineSnapshot(`
-  //   {
-  //     "hello": "world",
-  //   }
-  // `);
-});
-```
-
-When you run the test, Bun automatically updates the test file itself with the generated snapshot string. This makes the tests more portable and easier to understand, since the expected output is right next to the test.
-
-### Using inline snapshots
-
-1. Write your test with `.toMatchInlineSnapshot()`
-2. Run the test once
-3. Bun automatically updates your test file with the snapshot
-4. On subsequent runs, the value will be compared against the inline snapshot
-
-Inline snapshots are particularly useful for small, simple values where it's helpful to see the expected output right in the test file.
-
-## Error snapshots
-
-You can also snapshot error messages using `.toThrowErrorMatchingSnapshot()` and `.toThrowErrorMatchingInlineSnapshot()`:
-
-```ts
-import { test, expect } from "bun:test";
-
-test("error snapshot", () => {
-  expect(() => {
-    throw new Error("Something went wrong");
-  }).toThrowErrorMatchingSnapshot();
-
-  expect(() => {
-    throw new Error("Another error");
-  }).toThrowErrorMatchingInlineSnapshot();
-});
-```

package/docs/test/time.md

@@ -1,126 +0,0 @@
-`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()`
-
-Timers are not impacted yet, but may be in a future release of Bun.
-
-## `setSystemTime`
-
-To change the system time, use `setSystemTime`:
-
-```ts
-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
-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);
-  }
-});
-```
-
-{% callout %}
-**Timers** — Note that we have not implemented builtin support for mocking timers yet, but this is on the roadmap.
-{% /callout %}
-
-### Reset the system time
-
-To reset the system time, pass no arguments to `setSystemTime`:
-
-```ts
-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
-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`.
-
-```sh
-TZ=America/Los_Angeles bun test
-```
-
-Or set `process.env.TZ` at runtime:
-
-```ts
-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",
-  );
-});
-```