bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/test/dom.mdx

@@ -0,0 +1,226 @@
+---
+title: "DOM testing"
+description: "Learn how to test DOM elements and components using Bun with happy-dom and React Testing Library"
+---
+
+Bun's test runner plays well with existing component and DOM testing libraries, including React Testing Library and happy-dom.
+
+## happy-dom
+
+For writing headless tests for your frontend code and components, we recommend happy-dom. Happy DOM implements a complete set of HTML and DOM APIs in plain JavaScript, making it possible to simulate a browser environment with high fidelity.
+
+To get started install the `@happy-dom/global-registrator` package as a dev dependency.
+
+```bash terminal icon="terminal"
+bun add -d @happy-dom/global-registrator
+```
+
+We'll be using Bun's preload functionality to register the happy-dom globals before running our tests. This step will make browser APIs like `document` available in the global scope. Create a file called `happydom.ts` in the root of your project and add the following code:
+
+```ts title="happydom.ts" icon="/icons/typescript.svg"
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+GlobalRegistrator.register();
+```
+
+To preload this file before `bun test`, open or create a `bunfig.toml` file and add the following lines.
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+preload = ["./happydom.ts"]
+```
+
+This will execute `happydom.ts` when you run `bun test`. Now you can write tests that use browser APIs like `document` and `window`.
+
+```ts title="dom.test.ts" icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+test("dom test", () => {
+  document.body.innerHTML = `<button>My button</button>`;
+  const button = document.querySelector("button");
+  expect(button?.innerText).toEqual("My button");
+});
+```
+
+### TypeScript Support
+
+Depending on your `tsconfig.json` setup, you may see a "Cannot find name 'document'" type error in the code above. To "inject" the types for `document` and other browser APIs, add the following triple-slash directive to the top of any test file.
+
+```ts title="dom.test.ts" icon="/icons/typescript.svg"
+/// <reference lib="dom" />
+
+import { test, expect } from "bun:test";
+
+test("dom test", () => {
+  document.body.innerHTML = `<button>My button</button>`;
+  const button = document.querySelector("button");
+  expect(button?.innerText).toEqual("My button");
+});
+```
+
+Let's run this test with `bun test`:
+
+```bash terminal icon="terminal"
+bun test
+```
+
+```
+bun test v1.2.20
+
+dom.test.ts:
+✓ dom test [0.82ms]
+
+ 1 pass
+ 0 fail
+ 1 expect() calls
+Ran 1 tests across 1 files. 1 total [125.00ms]
+```
+
+## React Testing Library
+
+Bun works seamlessly with React Testing Library for testing React components. After setting up happy-dom as shown above, you can install and use React Testing Library normally.
+
+```bash terminal icon="terminal"
+bun add -d @testing-library/react @testing-library/jest-dom
+```
+
+```ts title="component.test.tsx" icon="/icons/typescript.svg"
+/// <reference lib="dom" />
+
+import { test, expect } from 'bun:test';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+function Button({ children }: { children: React.ReactNode }) {
+  return <button>{children}</button>;
+}
+
+test('renders button', () => {
+  render(<Button>Click me</Button>);
+  expect(screen.getByRole('button')).toHaveTextContent('Click me');
+});
+```
+
+## Advanced DOM Testing
+
+### Custom Elements
+
+You can test custom elements and web components using the same setup:
+
+```ts title="custom-element.test.ts" icon="/icons/typescript.svg"
+/// <reference lib="dom" />
+
+import { test, expect } from "bun:test";
+
+test("custom element", () => {
+  // Define a custom element
+  class MyElement extends HTMLElement {
+    constructor() {
+      super();
+      this.innerHTML = "<p>Custom element content</p>";
+    }
+  }
+
+  customElements.define("my-element", MyElement);
+
+  // Use it in tests
+  document.body.innerHTML = "<my-element></my-element>";
+  const element = document.querySelector("my-element");
+  expect(element?.innerHTML).toBe("<p>Custom element content</p>");
+});
+```
+
+### Event Testing
+
+Test DOM events and user interactions:
+
+```ts title="events.test.ts" icon="/icons/typescript.svg"
+/// <reference lib="dom" />
+
+import { test, expect } from "bun:test";
+
+test("button click event", () => {
+  let clicked = false;
+
+  document.body.innerHTML = '<button id="test-btn">Click me</button>';
+  const button = document.getElementById("test-btn");
+
+  button?.addEventListener("click", () => {
+    clicked = true;
+  });
+
+  button?.click();
+  expect(clicked).toBe(true);
+});
+```
+
+## Configuration Tips
+
+### Global Setup
+
+For more complex DOM testing setups, you can create a more comprehensive preload file:
+
+```ts title="test-setup.ts" icon="/icons/typescript.svg"
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import "@testing-library/jest-dom";
+
+// Register happy-dom globals
+GlobalRegistrator.register();
+
+// Add any global test configuration here
+global.ResizeObserver = class ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+// Mock other APIs as needed
+Object.defineProperty(window, "matchMedia", {
+  writable: true,
+  value: jest.fn().mockImplementation(query => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});
+```
+
+Then update your `bunfig.toml`:
+
+```toml title="bunfig.toml" icon="settings"
+[test]
+preload = ["./test-setup.ts"]
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**TypeScript errors for DOM APIs**: Make sure to include the `/// <reference lib="dom" />` directive at the top of your test files.
+
+**Missing globals**: Ensure that `@happy-dom/global-registrator` is properly imported and registered in your preload file.
+
+**React component rendering issues**: Make sure you've installed both `@testing-library/react` and have happy-dom set up correctly.
+
+### Performance Considerations
+
+Happy-dom is fast, but for very large test suites, you might want to:
+
+- Use `beforeEach` to reset the DOM state between tests
+- Avoid creating too many DOM elements in a single test
+- Consider using `cleanup` functions from testing libraries
+
+```ts title="test-setup.ts" icon="/icons/typescript.svg"
+import { afterEach } from "bun:test";
+import { cleanup } from "@testing-library/react";
+
+afterEach(() => {
+  cleanup();
+  document.body.innerHTML = "";
+});
+```

package/docs/{cli/test.md → test/index.mdx}

@@ -1,3 +1,10 @@
+---
+title: "Test runner"
+description: "Bun's fast, built-in, Jest-compatible test runner with TypeScript support, lifecycle hooks, mocking, and watch mode"
+---
+
+import Test from "/snippets/cli/test.mdx";
+
 Bun ships with a fast, built-in, Jest-compatible test runner. Tests are executed with the Bun runtime, and support the following features.
 
 - TypeScript and JSX
@@ -7,19 +14,20 @@ Bun ships with a fast, built-in, Jest-compatible test runner. Tests are executed
 - Watch mode with `--watch`
 - Script pre-loading with `--preload`
 
-{% callout %}
-Bun aims for compatibility with Jest, but not everything is implemented. To track compatibility, see [this tracking issue](https://github.com/oven-sh/bun/issues/1825).
-{% /callout %}
+<Note>
+  Bun aims for compatibility with Jest, but not everything is implemented. To track compatibility, see [this tracking
+  issue](https://github.com/oven-sh/bun/issues/1825).
+</Note>
 
 ## Run tests
 
-```bash
-$ bun test
+```bash terminal icon="terminal"
+bun test
 ```
 
-Tests are written in JavaScript or TypeScript with a Jest-like API. Refer to [Writing tests](https://bun.com/docs/test/writing) for full documentation.
+Tests are written in JavaScript or TypeScript with a Jest-like API. Refer to [Writing tests](/test/writing-tests) for full documentation.
 
-```ts#math.test.ts
+```ts math.test.ts icon="/icons/typescript.svg"
 import { expect, test } from "bun:test";
 
 test("2 + 2", () => {
@@ -36,26 +44,24 @@ The runner recursively searches the working directory for files that match the f
 
 You can filter the set of _test files_ to run by passing additional positional arguments to `bun test`. Any test file with a path that matches one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
 
-```bash
-$ bun test <filter> <filter> ...
+```bash terminal icon="terminal"
+bun test <filter> <filter> ...
 ```
 
 To filter by _test name_, use the `-t`/`--test-name-pattern` flag.
 
-```sh
+```sh terminal icon="terminal"
 # run all tests or test suites with "addition" in the name
-$ bun test --test-name-pattern addition
+bun test --test-name-pattern addition
 ```
 
-When no tests match the filter, `bun test` exits with code 1.
-
 To run a specific file in the test runner, make sure the path starts with `./` or `/` to distinguish it from a filter name.
 
-```bash
-$ bun test ./test/specific-file.test.ts
+```bash terminal icon="terminal"
+bun test ./test/specific-file.test.ts
 ```
 
-The test runner runs all tests in a single process. It loads all `--preload` scripts (see [Lifecycle](https://bun.com/docs/test/lifecycle) for details), then runs all tests. If a test fails, the test runner will exit with a non-zero exit code.
+The test runner runs all tests in a single process. It loads all `--preload` scripts (see [Lifecycle](/test/lifecycle) for details), then runs all tests. If a test fails, the test runner will exit with a non-zero exit code.
 
 ## CI/CD integration
 
@@ -71,7 +77,7 @@ No configuration is needed, other than installing `bun` in the workflow and runn
 
 To use `bun test` in a GitHub Actions workflow, add the following step:
 
-```yaml
+```yaml title=".github/workflows/test.yml" icon="file-code"
 jobs:
   build:
     name: build-app
@@ -93,8 +99,8 @@ From there, you'll get GitHub Actions annotations.
 
 To use `bun test` with a JUnit XML reporter, you can use the `--reporter=junit` in combination with `--reporter-outfile`.
 
-```sh
-$ bun test --reporter=junit --reporter-outfile=./bun.xml
+```sh terminal icon="terminal"
+bun test --reporter=junit --reporter-outfile=./bun.xml
 ```
 
 This will continue to output to stdout/stderr as usual, and also write a JUnit
@@ -106,9 +112,9 @@ JUnit XML is a popular format for reporting test results in CI/CD pipelines.
 
 Use the `--timeout` flag to specify a _per-test_ timeout in milliseconds. If a test times out, it will be marked as failed. The default value is `5000`.
 
-```bash
+```bash terminal icon="terminal"
 # default value is 5000
-$ bun test --timeout 20
+bun test --timeout 20
 ```
 
 ## Concurrent test execution
@@ -119,8 +125,8 @@ By default, Bun runs all tests sequentially within each test file. You can enabl
 
 Use the `--concurrent` flag to run all tests concurrently within their respective files:
 
-```sh
-$ bun test --concurrent
+```sh terminal icon="terminal"
+bun test --concurrent
 ```
 
 When this flag is enabled, all tests will run in parallel unless explicitly marked with `test.serial`.
@@ -129,12 +135,12 @@ When this flag is enabled, all tests will run in parallel unless explicitly mark
 
 Control the maximum number of tests running simultaneously with the `--max-concurrency` flag:
 
-```sh
+```sh terminal icon="terminal"
 # Limit to 4 concurrent tests
-$ bun test --concurrent --max-concurrency 4
+bun test --concurrent --max-concurrency 4
 
 # Default: 20
-$ bun test --concurrent
+bun test --concurrent
 ```
 
 This helps prevent resource exhaustion when running many concurrent tests. The default value is 20.
@@ -143,7 +149,7 @@ This helps prevent resource exhaustion when running many concurrent tests. The d
 
 Mark individual tests to run concurrently, even when the `--concurrent` flag is not used:
 
-```ts
+```ts title="math.test.ts" icon="/icons/typescript.svg"
 import { test, expect } from "bun:test";
 
 // These tests run in parallel with each other
@@ -167,7 +173,7 @@ test("sequential test", () => {
 
 Force tests to run sequentially, even when the `--concurrent` flag is enabled:
 
-```ts
+```ts title="math.test.ts" icon="/icons/typescript.svg"
 import { test, expect } from "bun:test";
 
 let sharedState = 0;
@@ -199,22 +205,25 @@ test.failing.each([1, 2, 3])("chained qualifiers %d", input => {
 
 Use the `--rerun-each` flag to run each test multiple times. This is useful for detecting flaky or non-deterministic test failures.
 
-```sh
-$ bun test --rerun-each 100
+```sh terminal icon="terminal"
+bun test --rerun-each 100
 ```
 
 ## Randomize test execution order
 
 Use the `--randomize` flag to run tests in a random order. This helps detect tests that depend on shared state or execution order.
 
-```sh
-$ bun test --randomize
+```sh terminal icon="terminal"
+bun test --randomize
 ```
 
 When using `--randomize`, the seed used for randomization will be displayed in the test summary:
 
-```sh
-$ bun test --randomize
+```sh terminal icon="terminal"
+bun test --randomize
+```
+
+```txt
 # ... test output ...
  --seed=12345
  2 pass
@@ -226,9 +235,9 @@ Ran 10 tests across 2 files. [50.00ms]
 
 Use the `--seed` flag to specify a seed for the randomization. This allows you to reproduce the same test order when debugging order-dependent failures.
 
-```sh
+```sh terminal icon="terminal"
 # Reproduce a previous randomized run
-$ bun test --seed 123456
+bun test --seed 123456
 ```
 
 The `--seed` flag implies `--randomize`, so you don't need to specify both. Using the same seed value will always produce the same test execution order, making it easier to debug intermittent failures caused by test interdependencies.
@@ -237,47 +246,46 @@ The `--seed` flag implies `--randomize`, so you don't need to specify both. Usin
 
 Use the `--bail` flag to abort the test run early after a pre-determined number of test failures. By default Bun will run all tests and report all failures, but sometimes in CI environments it's preferable to terminate earlier to reduce CPU usage.
 
-```sh
+```sh terminal icon="terminal"
 # bail after 1 failure
-$ bun test --bail
+bun test --bail
 
 # bail after 10 failure
-$ bun test --bail=10
+bun test --bail=10
 ```
 
 ## Watch mode
 
 Similar to `bun run`, you can pass the `--watch` flag to `bun test` to watch for changes and re-run tests.
 
-```bash
-$ bun test --watch
+```bash terminal icon="terminal"
+bun test --watch
 ```
 
 ## Lifecycle hooks
 
 Bun supports the following lifecycle hooks:
 
-| Hook             | Description                                              |
-| ---------------- | -------------------------------------------------------- |
-| `beforeAll`      | Runs once before all tests.                              |
-| `beforeEach`     | Runs before each test.                                   |
-| `afterEach`      | Runs after each test.                                    |
-| `afterAll`       | Runs once after all tests.                               |
-| `onTestFinished` | Runs after a test finishes, including after `afterEach`. |
+| Hook         | Description                 |
+| ------------ | --------------------------- |
+| `beforeAll`  | Runs once before all tests. |
+| `beforeEach` | Runs before each test.      |
+| `afterEach`  | Runs after each test.       |
+| `afterAll`   | Runs once after all tests.  |
 
 These hooks can be defined inside test files, or in a separate file that is preloaded with the `--preload` flag.
 
-```ts
-$ bun test --preload ./setup.ts
+```ts terminal icon="terminal"
+bun test --preload ./setup.ts
 ```
 
-See [Test > Lifecycle](https://bun.com/docs/test/lifecycle) for complete documentation.
+See [Test > Lifecycle](/test/lifecycle) for complete documentation.
 
 ## Mocks
 
 Create mock functions with the `mock` function.
 
-```ts
+```ts title="math.test.ts" icon="/icons/typescript.svg"
 import { test, expect, mock } from "bun:test";
 const random = mock(() => Math.random());
 
@@ -291,21 +299,21 @@ test("random", () => {
 
 Alternatively, you can use `jest.fn()`, it behaves identically.
 
-```ts-diff
-- import { test, expect, mock } from "bun:test";
-+ import { test, expect, jest } from "bun:test";
+```ts title="math.test.ts" icon="/icons/typescript.svg"
+import { test, expect, mock } from "bun:test"; // [!code --]
+import { test, expect, jest } from "bun:test"; // [!code ++]
 
-- const random = mock(() => Math.random());
-+ const random = jest.fn(() => Math.random());
+const random = mock(() => Math.random()); // [!code --]
+const random = jest.fn(() => Math.random()); // [!code ++]
 ```
 
-See [Test > Mocks](https://bun.com/docs/test/mocks) for complete documentation.
+See [Test > Mocks](/test/mocks) for complete documentation.
 
 ## Snapshot testing
 
 Snapshots are supported by `bun test`.
 
-```ts
+```ts title="math.test.ts" icon="/icons/typescript.svg"
 // example usage of toMatchSnapshot
 import { test, expect } from "bun:test";
 
@@ -316,11 +324,11 @@ test("snapshot", () => {
 
 To update snapshots, use the `--update-snapshots` flag.
 
-```sh
-$ bun test --update-snapshots
+```sh terminal icon="terminal"
+bun test --update-snapshots
 ```
 
-See [Test > Snapshots](https://bun.com/docs/test/snapshots) for complete documentation.
+See [Test > Snapshots](/test/snapshots) for complete documentation.
 
 ## UI & DOM testing
 
@@ -330,40 +338,13 @@ Bun is compatible with popular UI testing libraries:
 - [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro/)
 - [React Testing Library](https://testing-library.com/docs/react-testing-library/intro)
 
-See [Test > DOM Testing](https://bun.com/docs/test/dom) for complete documentation.
+See [Test > DOM Testing](/test/dom) for complete documentation.
 
 ## Performance
 
 Bun's test runner is fast.
 
-{% image src="/images/buntest.jpeg" caption="Running 266 React SSR tests faster than Jest can print its version number." /%}
-
-<!--
-Consider the following directory structure:
-
-```
-.
-├── a.test.ts
-├── b.test.ts
-├── c.test.ts
-└── foo
-    ├── a.test.ts
-    └── b.test.ts
-```
-
-To run both `a.test.ts` files:
-
-```
-$ bun test a
-```
-
-To run all tests in the `foo` directory:
-
-```
-$ bun test foo
-```
-
-Any test file in the directory with an _absolute path_ that contains one of the targets will run. Glob patterns are not yet supported. -->
+<Frame>![Running 266 React SSR tests faster than Jest can print its version number.](/images/buntest.jpeg)</Frame>
 
 ## AI Agent Integration
 
@@ -385,13 +366,15 @@ When an AI agent environment is detected:
 - Passing, skipped, and todo test indicators are hidden
 - Summary statistics remain intact
 
-```bash
+```bash terminal icon="terminal"
 # Example: Enable quiet output for Claude Code
-$ CLAUDECODE=1 bun test
+CLAUDECODE=1 bun test
 
 # Still shows failures and summary, but hides verbose passing test output
 ```
 
 This feature is particularly useful in AI-assisted development workflows where reduced output verbosity improves context efficiency while maintaining visibility into test failures.
 
-{% bunCLIUsage command="test" /%}
+---
+
+<Test />