bun-types 1.1.37-canary.20241124T140524 → 1.1.37-canary.20241125T140601

package/docs/runtime/web-apis.md

@@ -0,0 +1,128 @@
+Some Web APIs aren't relevant in the context of a server-first runtime like Bun, such as the [DOM API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API#html_dom_api_interfaces) or [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). Many others, though, are broadly useful outside of the browser context; when possible, Bun implements these Web-standard APIs instead of introducing new APIs.
+
+The following Web APIs are partially or completely supported.
+
+{% table %}
+
+---
+
+- HTTP
+- [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch)
+  [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+  [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+  [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+  [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)
+  [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+
+---
+
+- URLs
+- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
+  [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+
+---
+
+- Web Workers
+- [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
+  [`self.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage)
+  [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
+  [`MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)
+  [`MessageChannel`](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel)
+  [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel).
+
+---
+
+- Streams
+- [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
+  [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)
+  [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream)
+  [`ByteLengthQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/ByteLengthQueuingStrategy)
+  [`CountQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) and associated classes
+
+---
+
+- Blob
+- [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
+
+---
+
+- WebSockets
+- [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+
+---
+
+- Encoding and decoding
+- [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/atob)
+  [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/btoa)
+  [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
+  [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
+
+---
+
+- JSON
+- [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
+
+---
+
+- Timeouts
+- [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)
+  [`clearTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout)
+
+---
+
+- Intervals
+- [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)
+  [`clearInterval`](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)
+
+---
+
+- Crypto
+- [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto)
+  [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
+  [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
+
+---
+
+- Debugging
+
+- [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console)
+  [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/Performance)
+
+---
+
+- Microtasks
+- [`queueMicrotask`](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
+
+---
+
+- Errors
+- [`reportError`](https://developer.mozilla.org/en-US/docs/Web/API/reportError)
+
+---
+
+- User interaction
+- [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert)
+  [`confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm)
+  [`prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) (intended for interactive CLIs)
+
+<!-- - Blocking. Prints the alert message to terminal and awaits `[ENTER]` before proceeding. -->
+<!-- - Blocking. Prints confirmation message and awaits `[y/N]` input from user. Returns `true` if user entered `y` or `Y`, `false` otherwise.
+- Blocking. Prints prompt message and awaits user input. Returns the user input as a string. -->
+
+---
+
+- Realms
+- [`ShadowRealm`](https://github.com/tc39/proposal-shadowrealm)
+
+---
+
+- Events
+- [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+  [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event)
+  [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent)
+  [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent)
+  [`MessageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent)
+
+---
+
+{% /table %}

package/docs/test/coverage.md

@@ -0,0 +1,91 @@
+Bun's test runner now supports built-in _code coverage reporting_. This makes it easy to see how much of the codebase is covered by tests, and find areas that are not currently well-tested.
+
+## Enabling coverage
+
+`bun:test` supports seeing which lines of code are covered by tests. To use this feature, pass `--coverage` to the CLI. It will print out a coverage report to the console:
+
+```js
+$ bun test --coverage
+-------------|---------|---------|-------------------
+File         | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|---------|-------------------
+All files    |   38.89 |   42.11 |
+ index-0.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-1.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-10.ts |   33.33 |   36.84 | 10-15,19-24
+ index-2.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-3.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-4.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-5.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-6.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-7.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-8.ts  |   33.33 |   36.84 | 10-15,19-24
+ index-9.ts  |   33.33 |   36.84 | 10-15,19-24
+ index.ts    |  100.00 |  100.00 |
+-------------|---------|---------|-------------------
+```
+
+To always enable coverage reporting by default, add the following line to your `bunfig.toml`:
+
+```toml
+[test]
+
+# always enable coverage
+coverage = true
+```
+
+By default coverage reports will _include_ test files and _exclude_ sourcemaps. This is usually what you want, but it can be configured otherwise in `bunfig.toml`.
+
+```toml
+[test]
+coverageSkipTestFiles = true       # default false
+```
+
+### Coverage thresholds
+
+It is possible to specify a coverage threshold in `bunfig.toml`. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure.
+
+```toml
+[test]
+
+# to require 90% line-level and function-level coverage
+coverageThreshold = 0.9
+
+# to set different thresholds for lines and functions
+coverageThreshold = { lines = 0.9, functions = 0.9 }
+```
+
+### Sourcemaps
+
+Internally, Bun transpiles all files by default, so Bun automatically generates an internal [source map](https://web.dev/source-maps/) that maps lines of your original source code onto Bun's internal representation. If for any reason you want to disable this, set `test.coverageIgnoreSourcemaps` to `true`; this will rarely be desirable outside of advanced use cases.
+
+```toml
+[test]
+coverageIgnoreSourcemaps = true   # default false
+```
+
+### Coverage reporters
+
+By default, coverage reports will be printed to the console.
+
+For persistent code coverage reports in CI environments and for other tools, you can pass a `--coverage-reporter=lcov` CLI option or `coverageReporter` option in `bunfig.toml`.
+
+```toml
+[test]
+coverageReporter  = ["text", "lcov"]  # default ["text"]
+coverageDir = "path/to/somewhere"  # default "coverage"
+```
+
+| Reporter | Description                                                                 |
+| -------- | --------------------------------------------------------------------------- |
+| `text`   | Prints a text summary of the coverage to the console.                       |
+| `lcov`   | Save coverage in [lcov](https://github.com/linux-test-project/lcov) format. |
+
+#### lcov coverage reporter
+
+To generate an lcov report, you can use the `lcov` reporter. This will generate an `lcov.info` file in the `coverage` directory.
+
+```toml
+[test]
+coverageReporter = "lcov"
+```

package/docs/test/dom.md

@@ -0,0 +1,75 @@
+Bun's test runner plays well with existing component and DOM testing libraries, including React Testing Library and [`happy-dom`](https://github.com/capricorn86/happy-dom).
+
+## `happy-dom`
+
+For writing headless tests for your frontend code and components, we recommend [`happy-dom`](https://github.com/capricorn86/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
+$ 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
+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
+[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#dom.test.ts
+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');
+});
+```
+
+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](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) to the top of any test file.
+
+```ts-diff#dom.test.ts
++ /// <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
+$ bun test
+bun test v1.x
+
+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
+
+Once you've set up `happy-dom` as described above, you can use it with React Testing Library. To get started, install the `@testing-library/react` package as a dev dependency.
+
+```bash
+$ bun add -d @testing-library/react
+``` -->

package/docs/test/hot.md

@@ -0,0 +1,15 @@
+To automatically re-run tests when files change, use the `--watch` flag:
+
+```sh
+$ bun test --watch
+```
+
+Bun will watch for changes to any files imported in a test file, and re-run tests when a change is detected.
+
+It's fast.
+
+{% raw %}
+
+<blockquote class="twitter-tweet"><p lang="en" dir="ltr">&quot;bun test --watch url&quot; in a large folder with multiple files that start with &quot;url&quot; <a href="https://t.co/aZV9BP4eFu">pic.twitter.com/aZV9BP4eFu</a></p>&mdash; Jarred Sumner (@jarredsumner) <a href="https://twitter.com/jarredsumner/status/1640890850535436288?ref_src=twsrc%5Etfw">March 29, 2023</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+
+{% /raw %}

package/docs/test/lifecycle.md

@@ -0,0 +1,81 @@
+The test runner supports the following lifecycle hooks. This is useful for loading test fixtures, mocking data, and configuring the test environment.
+
+| Hook         | Description                 |
+| ------------ | --------------------------- |
+| `beforeAll`  | Runs once before all tests. |
+| `beforeEach` | Runs before each test.      |
+| `afterEach`  | Runs after each test.       |
+| `afterAll`   | Runs once after all tests.  |
+
+Perform per-test setup and teardown logic with `beforeEach` and `afterEach`.
+
+```ts
+import { beforeEach, afterEach } from "bun:test";
+
+beforeEach(() => {
+  console.log("running test.");
+});
+
+afterEach(() => {
+  console.log("done with test.");
+});
+
+// tests...
+```
+
+Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. The _scope_ is determined by where the hook is defined.
+
+To scope the hooks to a particular `describe` block:
+
+```ts
+import { describe, beforeAll } from "bun:test";
+
+describe("test group", () => {
+  beforeAll(() => {
+    // setup
+  });
+
+  // tests...
+});
+```
+
+To scope the hooks to a test file:
+
+```ts
+import { describe, beforeAll } from "bun:test";
+
+beforeAll(() => {
+  // setup
+});
+
+describe("test group", () => {
+  // tests...
+});
+```
+
+To scope the hooks to an entire multi-file test run, define the hooks in a separate file.
+
+```ts#setup.ts
+import { beforeAll, afterAll } from "bun:test";
+
+beforeAll(() => {
+  // global setup
+});
+
+afterAll(() => {
+  // global teardown
+});
+```
+
+Then use `--preload` to run the setup script before any test files.
+
+```ts
+$ bun test --preload ./setup.ts
+```
+
+To avoid typing `--preload` every time you run tests, it can be added to your `bunfig.toml`:
+
+```toml
+[test]
+preload = ["./setup.ts"]
+```

package/docs/test/mocks.md

@@ -0,0 +1,236 @@
+Create mocks with the `mock` function.
+
+```ts
+import { test, expect, mock } from "bun:test";
+const random = mock(() => Math.random());
+
+test("random", async () => {
+  const val = random();
+  expect(val).toBeGreaterThan(0);
+  expect(random).toHaveBeenCalled();
+  expect(random).toHaveBeenCalledTimes(1);
+});
+```
+
+{% callout %}
+Alternatively, you can use the `jest.fn()` function, as in Jest. It behaves identically.
+
+```ts
+import { test, expect, jest } from "bun:test";
+const random = jest.fn(() => Math.random());
+
+test("random", async () => {
+  const val = random();
+  expect(val).toBeGreaterThan(0);
+  expect(random).toHaveBeenCalled();
+  expect(random).toHaveBeenCalledTimes(1);
+});
+```
+
+{% /callout %}
+
+The result of `mock()` is a new function that's been decorated with some additional properties.
+
+```ts
+import { mock } from "bun:test";
+const random = mock((multiplier: number) => multiplier * Math.random());
+
+random(2);
+random(10);
+
+random.mock.calls;
+// [[ 2 ], [ 10 ]]
+
+random.mock.results;
+//  [
+//    { type: "return", value: 0.6533907460954099 },
+//    { type: "return", value: 0.6452713933037312 }
+//  ]
+```
+
+The following properties and methods are implemented on mock functions.
+
+- [x] [mockFn.getMockName()](https://jestjs.io/docs/mock-function-api#mockfngetmockname)
+- [x] [mockFn.mock.calls](https://jestjs.io/docs/mock-function-api#mockfnmockcalls)
+- [x] [mockFn.mock.results](https://jestjs.io/docs/mock-function-api#mockfnmockresults)
+- [x] [mockFn.mock.instances](https://jestjs.io/docs/mock-function-api#mockfnmockinstances)
+- [x] [mockFn.mock.contexts](https://jestjs.io/docs/mock-function-api#mockfnmockcontexts)
+- [x] [mockFn.mock.lastCall](https://jestjs.io/docs/mock-function-api#mockfnmocklastcall)
+- [x] [mockFn.mockClear()](https://jestjs.io/docs/mock-function-api#mockfnmockclear)
+- [x] [mockFn.mockReset()](https://jestjs.io/docs/mock-function-api#mockfnmockreset)
+- [x] [mockFn.mockRestore()](https://jestjs.io/docs/mock-function-api#mockfnmockrestore)
+- [x] [mockFn.mockImplementation(fn)](https://jestjs.io/docs/mock-function-api#mockfnmockimplementationfn)
+- [x] [mockFn.mockImplementationOnce(fn)](https://jestjs.io/docs/mock-function-api#mockfnmockimplementationoncefn)
+- [x] [mockFn.mockName(name)](https://jestjs.io/docs/mock-function-api#mockfnmocknamename)
+- [x] [mockFn.mockReturnThis()](https://jestjs.io/docs/mock-function-api#mockfnmockreturnthis)
+- [x] [mockFn.mockReturnValue(value)](https://jestjs.io/docs/mock-function-api#mockfnmockreturnvaluevalue)
+- [x] [mockFn.mockReturnValueOnce(value)](https://jestjs.io/docs/mock-function-api#mockfnmockreturnvalueoncevalue)
+- [x] [mockFn.mockResolvedValue(value)](https://jestjs.io/docs/mock-function-api#mockfnmockresolvedvaluevalue)
+- [x] [mockFn.mockResolvedValueOnce(value)](https://jestjs.io/docs/mock-function-api#mockfnmockresolvedvalueoncevalue)
+- [x] [mockFn.mockRejectedValue(value)](https://jestjs.io/docs/mock-function-api#mockfnmockrejectedvaluevalue)
+- [x] [mockFn.mockRejectedValueOnce(value)](https://jestjs.io/docs/mock-function-api#mockfnmockrejectedvalueoncevalue)
+- [x] [mockFn.withImplementation(fn, callback)](https://jestjs.io/docs/mock-function-api#mockfnwithimplementationfn-callback)
+
+## `.spyOn()`
+
+It's possible to track calls to a function without replacing it with a mock. Use `spyOn()` to create a spy; these spies can be passed to `.toHaveBeenCalled()` and `.toHaveBeenCalledTimes()`.
+
+```ts
+import { test, expect, spyOn } from "bun:test";
+
+const ringo = {
+  name: "Ringo",
+  sayHi() {
+    console.log(`Hello I'm ${this.name}`);
+  },
+};
+
+const spy = spyOn(ringo, "sayHi");
+
+test("spyon", () => {
+  expect(spy).toHaveBeenCalledTimes(0);
+  ringo.sayHi();
+  expect(spy).toHaveBeenCalledTimes(1);
+});
+```
+
+## Module mocks with `mock.module()`
+
+Module mocking lets you override the behavior of a module. Use `mock.module(path: string, callback: () => Object)` to mock a module.
+
+```ts
+import { test, expect, mock } from "bun:test";
+
+mock.module("./module", () => {
+  return {
+    foo: "bar",
+  };
+});
+
+test("mock.module", async () => {
+  const esm = await import("./module");
+  expect(esm.foo).toBe("bar");
+
+  const cjs = require("./module");
+  expect(cjs.foo).toBe("bar");
+});
+```
+
+Like the rest of Bun, module mocks support both `import` and `require`.
+
+### Overriding already imported modules
+
+If you need to override a module that's already been imported, there's nothing special you need to do. Just call `mock.module()` and the module will be overridden.
+
+```ts
+import { test, expect, mock } from "bun:test";
+
+// The module we're going to mock is here:
+import { foo } from "./module";
+
+test("mock.module", async () => {
+  const cjs = require("./module");
+  expect(foo).toBe("bar");
+  expect(cjs.foo).toBe("bar");
+
+  // We update it here:
+  mock.module("./module", () => {
+    return {
+      foo: "baz",
+    };
+  });
+
+  // And the live bindings are updated.
+  expect(foo).toBe("baz");
+
+  // The module is also updated for CJS.
+  expect(cjs.foo).toBe("baz");
+});
+```
+
+### Hoisting & preloading
+
+If you need to ensure a module is mocked before it's imported, you should use `--preload` to load your mocks before your tests run.
+
+```ts
+// my-preload.ts
+import { mock } from "bun:test";
+
+mock.module("./module", () => {
+  return {
+    foo: "bar",
+  };
+});
+```
+
+```sh
+bun test --preload ./my-preload
+```
+
+To make your life easier, you can put `preload` in your `bunfig.toml`:
+
+```toml
+
+[test]
+# Load these modules before running tests.
+preload = ["./my-preload"]
+
+```
+
+#### What happens if I mock a module that's already been imported?
+
+If you mock a module that's already been imported, the module will be updated in the module cache. This means that any modules that import the module will get the mocked version, BUT the original module will still have been evaluated. That means that any side effects from the original module will still have happened.
+
+If you want to prevent the original module from being evaluated, you should use `--preload` to load your mocks before your tests run.
+
+### `__mocks__` directory and auto-mocking
+
+Auto-mocking is not supported yet. If this is blocking you from switching to Bun, please file an issue.
+
+### Implementation details
+
+Module mocks have different implementations for ESM and CommonJS modules. For ES Modules, we've added patches to JavaScriptCore that allow Bun to override export values at runtime and update live bindings recursively.
+
+As of Bun v1.0.19, Bun automatically resolves the `specifier` argument to `mock.module()` as though you did an `import`. If it successfully resolves, then the resolved specifier string is used as the key in the module cache. This means that you can use relative paths, absolute paths, and even module names. If the `specifier` doesn't resolve, then the original `specifier` is used as the key in the module cache.
+
+After resolution, the mocked module is stored in the ES Module registry **and** the CommonJS require cache. This means that you can use `import` and `require` interchangeably for mocked modules.
+
+The callback function is called lazily, only if the module is imported or required. This means that you can use `mock.module()` to mock modules that don't exist yet, and it means that you can use `mock.module()` to mock modules that are imported by other modules.
+
+## Restore all function mocks to their original values with `mock.restore()`
+
+Instead of manually restoring each mock individually with `mockFn.mockRestore()`, restore all mocks with one command by calling `mock.restore()`. Doing so does not reset the value of modules overridden with `mock.module()`.
+
+Using `mock.restore()` can reduce the amount of code in your tests by adding it to `afterEach` blocks in each test file or even in your [test preload code](https://bun.sh/docs/runtime/bunfig#test-preload).
+
+```ts
+import { expect, mock, spyOn, test } from "bun:test";
+
+import * as fooModule from './foo.ts';
+import * as barModule from './bar.ts';
+import * as bazModule from './baz.ts';
+
+test('foo, bar, baz', () => {
+  const fooSpy = spyOn(fooModule, 'foo');
+  const barSpy = spyOn(barModule, 'bar');
+  const bazSpy = spyOn(bazModule, 'baz');
+
+  expect(fooSpy).toBe('foo');
+  expect(barSpy).toBe('bar');
+  expect(bazSpy).toBe('baz');
+
+  fooSpy.mockImplementation(() => 42);
+  barSpy.mockImplementation(() => 43);
+  bazSpy.mockImplementation(() => 44);
+
+  expect(fooSpy).toBe(42);
+  expect(barSpy).toBe(43);
+  expect(bazSpy).toBe(44);
+
+  mock.restore();
+
+  expect(fooSpy).toBe('foo');
+  expect(barSpy).toBe('bar');
+  expect(bazSpy).toBe('baz');
+});
+```

package/docs/test/snapshots.md

@@ -0,0 +1,15 @@
+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
+```