bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/guides/runtime/vscode-debugger.md

@@ -0,0 +1,47 @@
+---
+name: Debugging Bun with the VS Code extension
+---
+
+{% note %}
+
+VSCode extension support is currently buggy. We recommend the [Web Debugger](https://bun.sh/guides/runtime/web-debugger) for now.
+
+{% /note %}
+
+Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-vscode/types/jsc.d.ts) so you can debug your code with an interactive debugger.
+
+---
+
+To install the extension, visit the [Bun for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode) page on the VS Code marketplace website, then click Install.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/7c8c80e6-d49e-457a-a45e-45ebed946d56" /%}
+
+---
+
+Alternatively, search `bun-vscode` in the Extensions tab of VS Code.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/664b4c40-944c-4076-a4c2-f812aebd3dc9" /%}
+
+---
+
+Make sure you are installing the extension published by the verified Oven organization.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/73e6b09f-9ff1-4d85-b725-c5eb7215b6ae" /%}
+
+---
+
+Once installed, two new Bun-specific commands will appear in the Command Palette. To open the palette, click View > Command Palette, or type `Ctrl+Shift+P` (Windows, Linux) or `Cmd+Shift+P` on (Mac).
+
+---
+
+The `Bun: Run File` command will execute your code and print the output to the Debug Console in VS Code. Breakpoints will be ignored; this is similar to executing the file with `bun <file>` from the command line.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/1b2c7fd9-fbb9-486a-84d0-eb7ec135ded3" /%}
+
+---
+
+The `Bun: Debug File` command will execute your code and print the output to the Debug Console in VS Code. You can set breakpoints in your code by clicking to the left of a line number; a red dot should appear.
+
+When you run the file with `Bun: Debug File`, execution will pause at the breakpoint. You can inspect the variables in scope and step through the code line-by-line using the VS Code controls.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/c579a36c-eb21-4a58-bc9c-74612aad82af" /%}

package/docs/guides/runtime/web-debugger.md

@@ -0,0 +1,82 @@
+---
+name: Debugging Bun with the web debugger
+---
+
+Bun speaks the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-vscode/types/jsc.d.ts). To enable debugging when running code with Bun, use the `--inspect` flag. For demonstration purposes, consider the following simple web server.
+
+```ts#server.ts
+Bun.serve({
+  fetch(req){
+    console.log(req.url);
+    return new Response("Hello, world!");
+  }
+})
+```
+
+---
+
+Let's run this file with the `--inspect` flag.
+
+This automatically starts a WebSocket server on an available port that can be used to introspect the running Bun process. Various debugging tools can connect to this server to provide an interactive debugging experience.
+
+Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a modified version of WebKit's [Web Inspector Interface](https://webkit.org/web-inspector/web-inspector-interface/), which will look familiar to Safari users.
+
+```sh
+$ bun --inspect server.ts
+------------------ Bun Inspector ------------------
+Listening at:
+  ws://localhost:6499/0tqxs9exrgrm
+
+Inspect in browser:
+  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
+------------------ Bun Inspector ------------------
+```
+
+---
+
+Open the provided `debug.bun.sh` URL in your browser to start a debugging session. From this interface, you'll be able to view the source code of the running file, view and set breakpoints, and execute code with the built-in console.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/e6a976a8-80cc-4394-8925-539025cc025d" alt="Screenshot of Bun debugger, Console tab" /%}
+
+---
+
+Let's set a breakpoint. Navigate to the Sources tab; you should see the code from earlier. Click on the line number `3` to set a breakpoint on our `console.log(req.url)` statement.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/3b69c7e9-25ff-4f9d-acc4-caa736862935" alt="screenshot of Bun debugger" /%}
+
+---
+
+Then visit [`http://localhost:3000`](http://localhost:3000) in your web browser. This will send an HTTP request to our `localhost` web server. It will seem like the page isn't loading. Why? Because the program has paused execution at the breakpoint we set earlier.
+
+Note how the UI has changed.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/8b565e58-5445-4061-9bc4-f41090dfe769" alt="screenshot of Bun debugger" /%}
+
+---
+
+At this point there's a lot we can do to introspect the current execution environment. We can use the console at the bottom to run arbitrary code in the context of the program, with full access to the variables in scope at our breakpoint.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/f4312b76-48ba-4a7d-b3b6-6205968ac681" /%}
+
+---
+
+On the right side of the Sources pane, we can see all local variables currently in scope, and drill down to see their properties and methods. Here, we're inspecting the `req` variable.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/63d7f843-5180-489c-aa94-87c486e68646" /%}
+
+---
+
+In the upper left of the Sources pane, we can control the execution of the program.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/41b76deb-7371-4461-9d5d-81b5a6d2f7a4" /%}
+
+---
+
+Here's a cheat sheet explaining the functions of the control flow buttons.
+
+- _Continue script execution_ — continue running the program until the next breakpoint or exception.
+- _Step over_ — The program will continue to the next line.
+- _Step into_ — If the current statement contains a function call, the debugger will "step into" the called function.
+- _Step out_ — If the current statement is a function call, the debugger will finish executing the call, then "step out" of the function to the location where it was called.
+
+{% image src="https://github-production-user-asset-6210df.s3.amazonaws.com/3084745/261510346-6a94441c-75d3-413a-99a7-efa62365f83d.png" /%}

package/docs/guides/streams/node-readable-to-arraybuffer.md

@@ -0,0 +1,11 @@
+---
+name: Convert a Node.js Readable to an ArrayBuffer
+---
+
+To convert a Node.js `Readable` stream to an `ArrayBuffer` in Bun, you can create a new `Response` object with the stream as the body, then use `arrayBuffer()` to read the stream into an `ArrayBuffer`.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from(["Hello, ", "world!"]);
+const buf = await new Response(stream).arrayBuffer();
+```

package/docs/guides/streams/node-readable-to-blob.md

@@ -0,0 +1,11 @@
+---
+name: Convert a Node.js Readable to a Blob
+---
+
+To convert a Node.js `Readable` stream to a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) in Bun, you can create a new [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the stream as the body, then use [`response.blob()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/blob) to read the stream into a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from(["Hello, ", "world!"]);
+const blob = await new Response(stream).blob();
+```

package/docs/guides/streams/node-readable-to-json.md

@@ -0,0 +1,12 @@
+---
+name: Convert a Node.js Readable to JSON
+---
+
+To convert a Node.js `Readable` stream to a JSON object in Bun, you can create a new [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the stream as the body, then use [`response.json()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/json) to read the stream into a JSON object.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from([JSON.stringify({ hello: "world" })]);
+const json = await new Response(stream).json();
+console.log(json); // { hello: "world" }
+```

package/docs/guides/streams/node-readable-to-string.md

@@ -0,0 +1,12 @@
+---
+name: Convert a Node.js Readable to a string
+---
+
+To convert a Node.js `Readable` stream to a string in Bun, you can create a new [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with the stream as the body, then use [`response.text()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/text) to read the stream into a string.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from([Buffer.from("Hello, world!")]);
+const text = await new Response(stream).text();
+console.log(text); // "Hello, world!"
+```

package/docs/guides/streams/node-readable-to-uint8array.md

@@ -0,0 +1,11 @@
+---
+name: Convert a Node.js Readable to an Uint8Array
+---
+
+To convert a Node.js `Readable` stream to an `Uint8Array` in Bun, you can create a new `Response` object with the stream as the body, then use `bytes()` to read the stream into an `Uint8Array`.
+
+```ts
+import { Readable } from "stream";
+const stream = Readable.from(["Hello, ", "world!"]);
+const buf = await new Response(stream).bytes();
+```

package/docs/guides/streams/to-array.md

@@ -0,0 +1,14 @@
+---
+name: Convert a ReadableStream to an array of chunks
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats. The `Bun.readableStreamToArray` function reads the contents of a `ReadableStream` to an array of chunks.
+
+```ts
+const stream = new ReadableStream();
+const str = await Bun.readableStreamToArray(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-arraybuffer.md

@@ -0,0 +1,14 @@
+---
+name: Convert a ReadableStream to an ArrayBuffer
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const buf = await Bun.readableStreamToArrayBuffer(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-blob.md

@@ -0,0 +1,14 @@
+---
+name: Convert a ReadableStream to a Blob
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const blob = await Bun.readableStreamToBlob(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-buffer.md

@@ -0,0 +1,15 @@
+---
+name: Convert a ReadableStream to a Buffer
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats. This snippet reads the contents of a `ReadableStream` to an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), then creates a [`Buffer`](https://nodejs.org/api/buffer.html) that points to it.
+
+```ts
+const stream = new ReadableStream();
+const arrBuf = await Bun.readableStreamToArrayBuffer(stream);
+const nodeBuf = Buffer.from(arrBuf);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-json.md

@@ -0,0 +1,14 @@
+---
+name: Convert a ReadableStream to JSON
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const json = await Bun.readableStreamToJSON(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-string.md

@@ -0,0 +1,14 @@
+---
+name: Convert a ReadableStream to a string
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const str = await Bun.readableStreamToText(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-typedarray.md

@@ -0,0 +1,22 @@
+---
+name: Convert a ReadableStream to a Uint8Array
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats. This snippet reads the contents of a `ReadableStream` to an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), then creates a [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) that points to the buffer.
+
+```ts
+const stream = new ReadableStream();
+const buf = await Bun.readableStreamToArrayBuffer(stream);
+const uint8 = new Uint8Array(buf);
+```
+
+Additionally, there is a convenience method to convert to `Uint8Array` directly.
+
+```ts
+const stream = new ReadableStream();
+const uint8 = await Bun.readableStreamToBytes(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/test/bail.md

@@ -0,0 +1,22 @@
+---
+name: Bail early with the Bun test runner
+---
+
+Use the `--bail` flag to bail on a test run after a single failure. This is useful for aborting as soon as possible in a continuous integration environment.
+
+```sh
+$ bun test --bail
+```
+
+---
+
+To bail after a certain threshold of failures, optionally specify a number after the flag.
+
+```sh
+# bail after 10 failures
+$ bun test --bail=10
+```
+
+---
+
+See [Docs > Test runner](https://bun.sh/docs/cli/test) for complete documentation of `bun test`.

package/docs/guides/test/coverage-threshold.md

@@ -0,0 +1,60 @@
+---
+name: Set a code coverage threshold with the Bun test runner
+---
+
+Bun's test runner supports built-in code coverage reporting via the `--coverage` flag.
+
+```sh
+$ bun test --coverage
+
+test.test.ts:
+✓ math > add [0.71ms]
+✓ math > multiply [0.03ms]
+✓ random [0.13ms]
+-------------|---------|---------|-------------------
+File         | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|---------|-------------------
+All files    |   66.67 |   77.78 |
+ math.ts     |   50.00 |   66.67 |
+ random.ts   |   50.00 |   66.67 |
+-------------|---------|---------|-------------------
+
+ 3 pass
+ 0 fail
+ 3 expect() calls
+```
+
+---
+
+To set a minimum coverage threshold, add the following line to your `bunfig.toml`. This requires that 90% of your codebase is covered by tests.
+
+```toml
+[test]
+# to require 90% line-level and function-level coverage
+coverageThreshold = 0.9
+```
+
+---
+
+If your test suite does not meet this threshold, `bun test` will exit with a non-zero exit code to signal a failure.
+
+```sh
+$ bun test --coverage
+<test output>
+$ echo $?
+1 # this is the exit code of the previous command
+```
+
+---
+
+Different thresholds can be set for line-level and function-level coverage.
+
+```toml
+[test]
+# to set different thresholds for lines and functions
+coverageThreshold = { lines = 0.5, functions = 0.7 }
+```
+
+---
+
+See [Docs > Test runner > Coverage](https://bun.sh/docs/test/coverage) for complete documentation on code coverage reporting in Bun.

package/docs/guides/test/coverage.md

@@ -0,0 +1,44 @@
+---
+name: Generate code coverage reports with the Bun test runner
+---
+
+Bun's test runner 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.
+
+---
+
+Pass the `--coverage` flag to `bun test` to enable this feature. This will print a coverage report after the test run.
+
+The coverage report lists the source files that were executed during the test run, the percentage of functions and lines that were executed, and the line ranges that were not executed during the run.
+
+```sh
+$ bun test --coverage
+
+test.test.ts:
+✓ math > add [0.71ms]
+✓ math > multiply [0.03ms]
+✓ random [0.13ms]
+-------------|---------|---------|-------------------
+File         | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|---------|-------------------
+All files    |   66.67 |   77.78 |
+ math.ts     |   50.00 |   66.67 |
+ random.ts   |   50.00 |   66.67 |
+-------------|---------|---------|-------------------
+
+ 3 pass
+ 0 fail
+ 3 expect() calls
+```
+
+---
+
+To always enable coverage reporting by default, add the following line to your `bunfig.toml`:
+
+```toml
+[test]
+coverage = true # always enable coverage
+```
+
+---
+
+Refer to [Docs > Test runner > Coverage](https://bun.sh/docs/test/coverage) for complete documentation on code coverage reporting in Bun.

package/docs/guides/test/happy-dom.md

@@ -0,0 +1,68 @@
+---
+name: Write browser DOM tests with Bun and happy-dom
+---
+
+You can write and run browser tests with Bun's test runner in conjunction with [Happy DOM](https://github.com/capricorn86/happy-dom). Happy DOM implements mocked versions of browser APIs like `document` and `location`.
+
+---
+
+To get started, install `happy-dom`.
+
+```sh
+$ bun add -d @happy-dom/global-registrator
+```
+
+---
+
+This module exports a "registrator" that injects the mocked browser APIs to the global scope.
+
+```ts#happydom.ts
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+GlobalRegistrator.register();
+```
+
+---
+
+We need to make sure this file is executed before any of our test files. That's a job for Bun's built-in [_preload_]() functionality. Create a `bunfig.toml` file in the root of your project (if it doesn't already exist) and add the following lines.
+
+The `./happydom.ts` file should contain the registration code above.
+
+```toml#bunfig.toml
+[test]
+preload = "./happydom.ts"
+```
+
+---
+
+Now running `bun test` inside our project will automatically execute `happydom.ts` first. We can start writing tests that use browser APIs.
+
+```ts
+import { test, expect } from "bun:test";
+
+test("set button text", () => {
+  document.body.innerHTML = `<button>My button</button>`;
+  const button = document.querySelector("button");
+  expect(button?.innerText).toEqual("My button");
+});
+```
+
+---
+
+With Happy DOM properly configured, this test runs as expected.
+
+```sh
+$ bun test
+
+dom.test.ts:
+✓ set button text [0.82ms]
+
+ 1 pass
+ 0 fail
+ 1 expect() calls
+Ran 1 tests across 1 files. 1 total [125.00ms]
+```
+
+---
+
+Refer to the [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/migrate-from-jest.md

@@ -0,0 +1,110 @@
+---
+name: Migrate from Jest to Bun's test runner
+---
+
+In many cases, Bun's test runner can run Jest test suites with no code changes. Just run `bun test` instead of `npx jest`, `yarn test`, etc.
+
+```sh
+- $ npx jest
+- $ yarn test
++ $ bun test
+```
+
+---
+
+There's often no need for code changes.
+
+- Bun internally re-writes imports from `@jest/globals` to use the `bun:test` equivalents.
+- If you're relying on Jest to inject `test`, `expect`, etc. as globals, Bun does that too.
+
+But if you'd rather switch to the `bun:test` imports, you can do that too.
+
+```ts-diff
+- import {test, expect} from "@jest/globals";
++ import {test, expect} from "bun:test";
+```
+
+---
+
+Bun implements the vast majority of Jest's matchers, but compatibility isn't 100% yet. Refer to the full compatibility table at [Docs > Test runner > Writing tests](https://bun.sh/docs/test/writing#matchers).
+
+Some notable missing features:
+
+- `expect().toMatchInlineSnapshot()`
+- `expect().toHaveReturned()`
+
+---
+
+If you're using `testEnvironment: "jsdom"` to run your tests in a browser-like environment, you should follow the [DOM testing with Bun and happy-dom](/guides/test/happy-dom) guide to inject browser APIs into the global scope. This guide relies on [`happy-dom`](https://github.com/capricorn86/happy-dom), which is a leaner and faster alternative to [`jsdom`](https://github.com/jsdom/jsdom).
+
+At the moment jsdom does not work in Bun due to its internal use of V8 APIs. Track support for it [here](https://github.com/oven-sh/bun/issues/3554).
+
+```toml#bunfig.toml
+[test]
+preload = ["./happy-dom.ts"]
+```
+
+---
+
+Replace `bail` in your Jest config with the `--bail` CLI flag.
+
+<!-- ```ts-diff
+- import type {Config} from 'jest';
+-
+- const config: Config = {
+-   bail: 3
+- };
+``` -->
+
+```sh
+$ bun test --bail=3
+```
+
+---
+
+Replace `collectCoverage` with the `--coverage` CLI flag.
+
+<!-- ```ts-diff
+- import type {Config} from 'jest';
+-
+- const config: Config = {
+-   collectCoverageFrom: [
+-     '**/*.{js,jsx}',
+-     '!**/node_modules/**',
+-     '!**/vendor/**',
+-   ],
+- };
+``` -->
+
+```sh
+$ bun test --coverage
+```
+
+---
+
+Replace `testTimeout` with the `--test-timeout` CLI flag.
+
+```sh
+$ bun test --timeout 10000
+```
+
+---
+
+Many other flags become irrelevant or obsolete when using `bun test`.
+
+- `transform` — Bun supports TypeScript & JSX. Other file types can be configured with [Plugins](https://bun.sh/docs/runtime/plugins).
+- `extensionsToTreatAsEsm`
+- `haste` — Bun uses it's own internal source maps
+- `watchman`, `watchPlugins`, `watchPathIgnorePatterns` — use `--watch` to run tests in watch mode
+- `verbose` — set `logLevel: "debug"` in [`bunfig.toml`](https://bun.sh/docs/runtime/bunfig#loglevel)
+
+---
+
+Settings that aren't mentioned here are not supported or have no equivalent. Please [file a feature request](https://github.com/oven-sh/bun) if something important is missing.
+
+---
+
+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/mock-clock.md

@@ -0,0 +1,48 @@
+---
+name: Set the system time in Bun's test runner
+---
+
+Bun's test runner supports setting the system time programmatically with the `setSystemTime` function.
+
+```ts
+import { test, expect, setSystemTime } from "bun:test";
+
+test("party like it's 1999", () => {
+  const date = new Date("1999-01-01T00:00:00.000Z");
+  setSystemTime(date); // it's now January 1, 1999
+
+  const now = new Date();
+  expect(now.getFullYear()).toBe(1999);
+  expect(now.getMonth()).toBe(0);
+  expect(now.getDate()).toBe(1);
+});
+```
+
+---
+
+The `setSystemTime` function is commonly used on conjunction with [Lifecycle Hooks](https://bun.sh/docs/test/lifecycle) to configure a testing environment with a deterministic "fake clock".
+
+```ts
+import { test, expect, beforeAll, setSystemTime } from "bun:test";
+
+beforeAll(() => {
+  const date = new Date("1999-01-01T00:00:00.000Z");
+  setSystemTime(date); // it's now January 1, 1999
+});
+
+// tests...
+```
+
+---
+
+To reset the system clock to the actual time, call `setSystemTime` with no arguments.
+
+```ts
+import { test, expect, beforeAll, setSystemTime } from "bun:test";
+
+setSystemTime(); // reset to actual time
+```
+
+---
+
+See [Docs > Test Runner > Date and time](https://bun.sh/docs/test/time) for complete documentation on mocking with the Bun test runner.