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

package/docs/guides/test/run-tests.mdx

@@ -0,0 +1,116 @@
+---
+title: Run your tests with the Bun test runner
+sidebarTitle: Run tests
+mode: center
+---
+
+Bun has a built-in [test runner](https://bun.sh/docs/cli/test) with a Jest-like `expect` API.
+
+---
+
+To use it, run the `bun test` command from your project directory. The test runner will recursively search for all files in the directory that match the following patterns and execute the tests they contain.
+
+```txt File Tree icon="folder-tree"
+*.test.{js|jsx|ts|tsx}
+*_test.{js|jsx|ts|tsx}
+*.spec.{js|jsx|ts|tsx}
+*_spec.{js|jsx|ts|tsx}
+```
+
+---
+
+Here's what the output of a typical test run looks like. In this case, there are three tests files (`test.test.js`, `test2.test.js`, and `test3.test.js`) containing two tests each (`add` and `multiply`).
+
+```sh terminal icon="terminal"
+bun test
+```
+
+```txt
+test.test.js:
+✓ add [0.87ms]
+✓ multiply [0.02ms]
+
+test2.test.js:
+✓ add [0.72ms]
+✓ multiply [0.01ms]
+
+test3.test.js:
+✓ add [0.54ms]
+✓ multiply [0.01ms]
+
+ 6 pass
+ 0 fail
+ 6 expect() calls
+Ran 6 tests across 3 files. [9.00ms]
+```
+
+---
+
+To only run certain test files, pass a positional argument to `bun test`. The runner will only execute files that contain that argument in their path.
+
+```sh terminal icon="terminal"
+bun test test3
+```
+
+```txt
+test3.test.js:
+✓ add [1.40ms]
+✓ multiply [0.03ms]
+
+ 2 pass
+ 0 fail
+ 2 expect() calls
+Ran 2 tests across 1 files. [15.00ms]
+```
+
+---
+
+All tests have a name, defined using the first parameter to the `test` function. Tests can also be grouped into suites with `describe`.
+
+```ts
+import { test, expect, describe } from "bun:test";
+
+describe("math", () => {
+  test("add", () => {
+    expect(2 + 2).toEqual(4);
+  });
+
+  test("multiply", () => {
+    expect(2 * 2).toEqual(4);
+  });
+});
+```
+
+---
+
+To filter which tests are executed by name, use the `-t`/`--test-name-pattern` flag.
+
+Adding `-t add` will only run tests with "add" in the name. This works with test names defined with `test` or test suite names defined with `describe`.
+
+```sh terminal icon="terminal"
+bun test -t add
+```
+
+```txt
+test.test.js:
+✓ add [1.79ms]
+» multiply
+
+test2.test.js:
+✓ add [2.30ms]
+» multiply
+
+test3.test.js:
+✓ add [0.32ms]
+» multiply
+
+ 3 pass
+ 3 skip
+ 0 fail
+ 3 expect() calls
+Ran 6 tests across 3 files. [59.00ms]
+```
+
+---
+
+See [Docs > Test Runner](https://bun.sh/docs/cli/test) for complete documentation on the test runner.

package/docs/guides/test/skip-tests.mdx

@@ -0,0 +1,43 @@
+---
+title: Skip tests with the Bun test runner
+sidebarTitle: Skip tests
+mode: center
+---
+
+To skip a test with the Bun test runner, use the `test.skip` function.
+
+```ts test.ts icon="/icons/typescript.svg"
+import { test } from "bun:test";
+
+test.skip("unimplemented feature", () => {
+  expect(Bun.isAwesome()).toBe(true);
+});
+```
+
+---
+
+Running `bun test` will not execute this test. It will be marked as skipped in the terminal output.
+
+```sh terminal icon="terminal"
+bun test
+```
+
+```txt
+test.test.ts:
+✓ add [0.03ms]
+✓ multiply [0.02ms]
+» unimplemented feature
+
+ 2 pass
+ 1 skip
+ 0 fail
+ 2 expect() calls
+Ran 3 tests across 1 files. [74.00ms]
+```
+
+---
+
+See also:
+
+- [Mark a test as a todo](/guides/test/todo-tests)
+- [Docs > Test runner > Writing tests](https://bun.sh/docs/test/writing)

package/docs/guides/test/snapshot.mdx

@@ -0,0 +1,102 @@
+---
+title: Use snapshot testing in `bun test`
+sidebarTitle: Snapshot testing
+mode: center
+---
+
+Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
+
+```ts snap.test.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+test("snapshot", () => {
+  expect({ foo: "bar" }).toMatchSnapshot();
+});
+```
+
+---
+
+The first time this test is executed, Bun will evaluate the value passed into `expect()` and write it to disk in a directory called `__snapshots__` that lives alongside the test file. (Note the `snapshots: +1 added` line in the output.)
+
+```sh terminal icon="terminal"
+bun test test/snap
+```
+
+```txt
+test/snap.test.ts:
+✓ snapshot [1.48ms]
+
+ 1 pass
+ 0 fail
+ snapshots: +1 added
+ 1 expect() calls
+Ran 1 tests across 1 files. [82.00ms]
+```
+
+---
+
+The `__snapshots__` directory contains a `.snap` file for each test file in the directory.
+
+```txt File Tree icon="folder-tree"
+test
+├── __snapshots__
+│   └── snap.test.ts.snap
+└── snap.test.ts
+```
+
+---
+
+The `snap.test.ts.snap` file is a JavaScript file that exports a serialized version of the value passed into `expect()`. The `{foo: "bar"}` object has been serialized to JSON.
+
+```js snap.test.ts.snap icon="file-code"
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`snapshot 1`] = `
+{
+  "foo": "bar",
+}
+`;
+```
+
+---
+
+Later, when this test file is executed again, Bun will read the snapshot file and compare it to the value passed into `expect()`. If the values are different, the test will fail.
+
+```sh terminal icon="terminal"
+bun test
+bun test v1.3.1 (9c68abdb)
+```
+
+```txt
+test/snap.test.ts:
+✓ snapshot [1.05ms]
+
+ 1 pass
+ 0 fail
+ 1 snapshots, 1 expect() calls
+Ran 1 tests across 1 files. [101.00ms]
+```
+
+---
+
+To update snapshots, use the `--update-snapshots` flag.
+
+```sh terminal icon="terminal"
+bun test --update-snapshots
+bun test v1.3.1 (9c68abdb)
+```
+
+```txt
+test/snap.test.ts:
+✓ snapshot [0.86ms]
+
+ 1 pass
+ 0 fail
+ snapshots: +1 added  # the snapshot was regenerated
+ 1 expect() calls
+Ran 1 tests across 1 files. [102.00ms]
+```
+
+---
+
+See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

package/docs/guides/test/spy-on.mdx

@@ -0,0 +1,49 @@
+---
+title: Spy on methods in `bun test`
+sidebarTitle: Spy on methods
+mode: center
+---
+
+Use the `spyOn` utility to track method calls with Bun's test runner.
+
+```ts
+import { test, expect, spyOn } from "bun:test";
+
+const leo = {
+  name: "Leonardo",
+  sayHi(thing: string) {
+    console.log(`Sup I'm ${this.name} and I like ${thing}`);
+  },
+};
+
+const spy = spyOn(leo, "sayHi");
+```
+
+---
+
+Once the spy is created, it can be used to write `expect` assertions relating to method calls.
+
+```ts
+import { test, expect, spyOn } from "bun:test";
+
+const leo = {
+  name: "Leonardo",
+  sayHi(thing: string) {
+    console.log(`Sup I'm ${this.name} and I like ${thing}`);
+  },
+};
+
+const spy = spyOn(leo, "sayHi");
+
+test("turtles", () => {
+  // [!code ++]
+  expect(spy).toHaveBeenCalledTimes(0); // [!code ++]
+  leo.sayHi("pizza"); // [!code ++]
+  expect(spy).toHaveBeenCalledTimes(1); // [!code ++]
+  expect(spy.mock.calls).toEqual([["pizza"]]); // [!code ++]
+}); // [!code ++]
+```
+
+---
+
+See [Docs > Test Runner > Mocks](https://bun.sh/docs/test/mocks) for complete documentation on mocking with the Bun test runner.

package/docs/guides/test/svelte-test.mdx

@@ -0,0 +1,113 @@
+---
+title: "import, require, and test Svelte components with bun test"
+sidebarTitle: Test Svelte
+mode: center
+---
+
+Bun's [Plugin API](/runtime/plugins) lets you add custom loaders to your project. The `test.preload` option in `bunfig.toml` lets you configure your loader to start before your tests run.
+
+Firstly, install `@testing-library/svelte`, `svelte`, and `@happy-dom/global-registrator`.
+
+```bash terminal icon="terminal"
+bun add @testing-library/svelte svelte@4 @happy-dom/global-registrator
+```
+
+Then, save this plugin in your project.
+
+```ts svelte-loader.js icon="/icons/typescript.svg"
+import { plugin } from "bun";
+import { compile } from "svelte/compiler";
+import { readFileSync } from "fs";
+import { beforeEach, afterEach } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+beforeEach(async () => {
+  await GlobalRegistrator.register();
+});
+
+afterEach(async () => {
+  await GlobalRegistrator.unregister();
+});
+
+plugin({
+  title: "svelte loader",
+  setup(builder) {
+    builder.onLoad({ filter: /\.svelte(\?[^.]+)?$/ }, ({ path }) => {
+      try {
+        const source = readFileSync(path.substring(0, path.includes("?") ? path.indexOf("?") : path.length), "utf-8");
+
+        const result = compile(source, {
+          filetitle: path,
+          generate: "client",
+          dev: false,
+        });
+
+        return {
+          contents: result.js.code,
+          loader: "js",
+        };
+      } catch (err) {
+        throw new Error(`Failed to compile Svelte component: ${err.message}`);
+      }
+    });
+  },
+});
+```
+
+---
+
+Add this to `bunfig.toml` to tell Bun to preload the plugin, so it loads before your tests run.
+
+```toml bunfig.toml icon="settings"
+[test]
+# Tell Bun to load this plugin before your tests run
+preload = ["./svelte-loader.js"]
+
+# This also works:
+# test.preload = ["./svelte-loader.js"]
+```
+
+---
+
+Add an example `.svelte` file in your project.
+
+```html Counter.svelte icon="file-code"
+<script>
+  export let initialCount = 0;
+  let count = initialCount;
+</script>
+
+<button on:click="{()" ="">(count += 1)}>+1</button>
+```
+
+---
+
+Now you can `import` or `require` `*.svelte` files in your tests, and it will load the Svelte component as a JavaScript module.
+
+```ts hello-svelte.test.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+import { render, fireEvent } from "@testing-library/svelte";
+import Counter from "./Counter.svelte";
+
+test("Counter increments when clicked", async () => {
+  const { getByText, component } = render(Counter);
+  const button = getByText("+1");
+
+  // Initial state
+  expect(component.$$.ctx[0]).toBe(0); // initialCount is the first prop
+
+  // Click the increment button
+  await fireEvent.click(button);
+
+  // Check the new state
+  expect(component.$$.ctx[0]).toBe(1);
+});
+```
+
+---
+
+Use `bun test` to run your tests.
+
+```bash terminal icon="terminal"
+bun test
+```

package/docs/guides/test/testing-library.mdx

@@ -0,0 +1,93 @@
+---
+title: Using Testing Library with Bun
+sidebarTitle: Testing Library
+mode: center
+---
+
+You can use [Testing Library](https://testing-library.com/) with Bun's test runner.
+
+---
+
+As a prerequisite to using Testing Library you will need to install [Happy Dom](https://github.com/capricorn86/happy-dom). ([see Bun's Happy DOM guide for more information](https://bun.sh/guides/test/happy-dom)).
+
+```sh terminal icon="terminal"
+bun add -D @happy-dom/global-registrator
+```
+
+---
+
+Next you should install the Testing Library packages you are planning on using. For example, if you are setting up testing for React your installs may look like this. You will also need to install `@testing-library/jest-dom` to get matchers working later.
+
+```sh terminal icon="terminal"
+bun add -D @testing-library/react @testing-library/dom @testing-library/jest-dom
+```
+
+---
+
+Next you will need to create a preload script for Happy DOM and for Testing Library. For more details about the Happy DOM setup script see [Bun's Happy DOM guide](https://bun.sh/guides/test/happy-dom).
+
+```ts happydom.ts icon="/icons/typescript.svg"
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+GlobalRegistrator.register();
+```
+
+---
+
+For Testing Library, you will want to extend Bun's `expect` function with Testing Library's matchers. Optionally, to better match the behavior of test-runners like Jest, you may want to run cleanup after each test.
+
+```ts testing-library.ts icon="/icons/typescript.svg"
+import { afterEach, expect } from "bun:test";
+import { cleanup } from "@testing-library/react";
+import * as matchers from "@testing-library/jest-dom/matchers";
+
+expect.extend(matchers);
+
+// Optional: cleans up `render` after each test
+afterEach(() => {
+  cleanup();
+});
+```
+
+---
+
+Next, add these preload scripts to your `bunfig.toml` (you can also have everything in a single `preload.ts` script if you prefer).
+
+```toml bunfig.toml icon="settings"
+[test]
+preload = ["./happydom.ts", "./testing-library.ts"]
+```
+
+---
+
+If you are using TypeScript you will also need to make use of declaration merging in order to get the new matcher types to show up in your editor. To do this, create a type declaration file that extends `Matchers` like this.
+
+```ts matchers.d.ts icon="/icons/typescript.svg"
+import { TestingLibraryMatchers } from "@testing-library/jest-dom/matchers";
+import { Matchers, AsymmetricMatchers } from "bun:test";
+
+declare module "bun:test" {
+  interface Matchers<T> extends TestingLibraryMatchers<typeof expect.stringContaining, T> {}
+  interface AsymmetricMatchers extends TestingLibraryMatchers {}
+}
+```
+
+---
+
+You should now be able to use Testing Library in your tests
+
+```ts matchers.d.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+import { screen, render } from "@testing-library/react";
+import { MyComponent } from "./myComponent";
+
+test("Can use Testing Library", () => {
+  render(MyComponent);
+  const myComponent = screen.getByTestId("my-component");
+  expect(myComponent).toBeInTheDocument();
+});
+```
+
+---
+
+Refer to the [Testing Library docs](https://testing-library.com/), [Happy DOM repo](https://github.com/capricorn86/happy-dom) and [Docs > Test runner > DOM](https://bun.sh/docs/test/dom) for complete documentation on writing browser tests with Bun.

package/docs/guides/test/timeout.mdx

@@ -0,0 +1,17 @@
+---
+title: Set a per-test timeout with the Bun test runner
+sidebarTitle: Test timeout
+mode: center
+---
+
+Use the `--timeout` flag to set a timeout for each test in milliseconds. If any test exceeds this timeout, it will be marked as failed.
+
+The default timeout is `5000` (5 seconds).
+
+```sh terminal icon="terminal"
+bun test --timeout 3000 # 3 seconds
+```
+
+---
+
+See [Docs > Test runner](https://bun.sh/docs/cli/test) for complete documentation of `bun test`.

package/docs/guides/test/todo-tests.mdx

@@ -0,0 +1,74 @@
+---
+title: Mark a test as a "todo" with the Bun test runner
+sidebarTitle: Todo tests
+mode: center
+---
+
+To remind yourself to write a test later, use the `test.todo` function. There's no need to provide a test implementation.
+
+```ts test.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+// write this later
+test.todo("unimplemented feature");
+```
+
+---
+
+The output of `bun test` indicates how many `todo` tests were encountered.
+
+```sh terminal icon="terminal"
+bun test
+```
+
+```txt
+test.test.ts:
+✓ add [0.03ms]
+✓ multiply [0.02ms]
+✎ unimplemented feature
+
+ 2 pass
+ 1 todo
+ 0 fail
+ 2 expect() calls
+Ran 3 tests across 1 files. [74.00ms]
+```
+
+---
+
+Optionally, you can provide a test implementation.
+
+```ts
+import { test, expect } from "bun:test";
+
+test.todo("unimplemented feature", () => {
+  expect(Bun.isAwesome()).toBe(true);
+});
+```
+
+---
+
+If an implementation is provided, it will not be run unless the `--todo` flag is passed. If the `--todo` flag is passed, the test will be executed and _expected to fail_ by test runner! If a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
+
+```sh terminal icon="terminal"
+bun test --todo
+```
+
+```txt
+my.test.ts:
+✗ unimplemented feature
+  ^ this test is marked as todo but passes. Remove `.todo` or check that test is correct.
+
+ 0 pass
+ 1 fail
+ 1 expect() calls
+$ echo $?
+1 # this is the exit code of the previous command
+```
+
+---
+
+See also:
+
+- [Skip a test](/guides/test/skip-tests)
+- [Docs > Test runner > Writing tests](https://bun.sh/docs/test/writing)

package/docs/guides/test/update-snapshots.mdx

@@ -0,0 +1,49 @@
+---
+title: Update snapshots in `bun test`
+sidebarTitle: Update snapshots
+mode: center
+---
+
+Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
+
+```ts snap.test.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+test("snapshot", () => {
+  expect({ foo: "bar" }).toMatchSnapshot();
+});
+```
+
+---
+
+The first time this test is executed, Bun will write a snapshot file to disk in a directory called `__snapshots__` that lives alongside the test file.
+
+```txt File Tree icon="folder-tree"
+test
+├── __snapshots__
+│   └── snap.test.ts.snap
+└── snap.test.ts
+```
+
+---
+
+To regenerate snapshots, use the `--update-snapshots` flag.
+
+```sh terminal icon="terminal"
+bun test --update-snapshots
+```
+
+```txt
+test/snap.test.ts:
+✓ snapshot [0.86ms]
+
+ 1 pass
+ 0 fail
+ snapshots: +1 added # the snapshot was regenerated
+ 1 expect() calls
+Ran 1 tests across 1 files. [102.00ms]
+```
+
+---
+
+See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

package/docs/guides/test/watch-mode.mdx

@@ -0,0 +1,24 @@
+---
+title: Run tests in watch mode with Bun
+sidebarTitle: Watch mode
+mode: center
+---
+
+Use the `--watch` flag to run your tests in watch mode.
+
+```sh terminal icon="terminal"
+bun test --watch
+```
+
+---
+
+This will restart the running Bun process whenever a file change is detected. It's fast. In this example, the editor is configured to save the file on every keystroke.
+
+<Frame>
+  ![Running tests in watch mode in
+  Bun](https://github.com/oven-sh/bun/assets/3084745/dc49a36e-ba82-416f-b960-1c883a924248)
+</Frame>
+
+---
+
+See [Docs > Test Runner](https://bun.sh/docs/cli/test) for complete documentation on the test runner.

package/docs/guides/util/base64.mdx

@@ -0,0 +1,17 @@
+---
+title: Encode and decode base64 strings
+sidebarTitle: Base64 encoding
+mode: center
+---
+
+Bun implements the Web-standard [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/atob) and [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa) functions for encoding and decoding base64 strings.
+
+```ts
+const data = "hello world";
+const encoded = btoa(data); // => "aGVsbG8gd29ybGQ="
+const decoded = atob(encoded); // => "hello world"
+```
+
+---
+
+See [Docs > Web APIs](https://bun.com/docs/runtime/web-apis) for a complete breakdown of the Web APIs implemented in Bun.