bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/guides/test/mock-functions.md

@@ -0,0 +1,68 @@
+---
+name: Mock functions in `bun test`
+---
+
+Create mocks with the `mock` function from `bun:test`.
+
+```ts
+import { test, expect, mock } from "bun:test";
+
+const random = mock(() => Math.random());
+```
+
+---
+
+The mock function can accept arguments.
+
+```ts
+import { test, expect, mock } from "bun:test";
+
+const random = mock((multiplier: number) => multiplier * Math.random());
+```
+
+---
+
+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 }
+//  ]
+```
+
+---
+
+These extra properties make it possible to write `expect` assertions about usage of the mock function, including how many times it was called, the arguments, and the return values.
+
+```ts
+import { test, expect, mock } from "bun:test";
+
+const random = mock((multiplier: number) => multiplier * Math.random());
+
+test("random", async () => {
+  const a = random(1);
+  const b = random(2);
+  const c = random(3);
+
+  expect(random).toHaveBeenCalled();
+  expect(random).toHaveBeenCalledTimes(3);
+  expect(random.mock.args).toEqual([[1], [2], [3]]);
+  expect(random.mock.results[0]).toEqual({ type: "return", value: a });
+});
+```
+
+---
+
+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/rerun-each.md

@@ -0,0 +1,14 @@
+---
+name: Re-run tests multiple times with the Bun test runner
+---
+
+Use the `--rerun-each` flag to re-run every test multiple times with the Bun test runner. This is useful for finding flaky or non-deterministic tests.
+
+```sh
+# re-run each test 10 times
+$ bun test --rerun-each 10
+```
+
+---
+
+See [Docs > Test runner](https://bun.sh/docs/cli/test) for complete documentation of `bun test`.

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

@@ -0,0 +1,111 @@
+---
+name: Run your tests with the Bun test runner
+---
+
+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
+*.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
+$ bun test
+bun test v1.x (9c68abdb)
+
+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
+$ bun test test3
+bun test v1.x (9c68abdb)
+
+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
+$ bun test -t add
+bun test v1.x (9c68abdb)
+
+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.md

@@ -0,0 +1,39 @@
+---
+name: Skip tests with the Bun test runner
+---
+
+To skip a test with the Bun test runner, use the `test.skip` function.
+
+```ts
+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
+$ bun test
+
+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.md

@@ -0,0 +1,99 @@
+---
+name: Use snapshot testing in `bun test`
+---
+
+Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
+
+{% callout %}
+The `.toMatchInlineSnapshot()` method is not yet supported.
+{% /callout %}
+
+```ts#snap.test.ts
+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
+$ bun test test/snap
+bun test v1.x (9c68abdb)
+
+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
+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
+// Bun Snapshot v1, https://goo.gl/fbAQLP
+
+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
+$ bun test
+bun test v1.x (9c68abdb)
+
+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
+$ bun test --update-snapshots
+bun test v1.x (9c68abdb)
+
+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/mocks) for complete documentation on mocking with the Bun test runner.

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

@@ -0,0 +1,46 @@
+---
+name: Spy on methods in `bun test`
+---
+
+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-diff
+  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", ()=>{
++   expect(spy).toHaveBeenCalledTimes(0);
++   leo.sayHi("pizza");
++   expect(spy).toHaveBeenCalledTimes(1);
++   expect(spy.mock.calls).toEqual([[ "pizza" ]]);
++ })
+```
+
+---
+
+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/testing-library.md

@@ -0,0 +1,87 @@
+---
+name: Using Testing Library with Bun
+---
+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
+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
+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
+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
+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
+[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
+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
+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.md

@@ -0,0 +1,15 @@
+---
+name: Set a per-test timeout with the Bun test runner
+---
+
+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
+$ 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.md

@@ -0,0 +1,67 @@
+---
+name: Mark a test as a "todo" with the Bun test runner
+---
+
+To remind yourself to write a test later, use the `test.todo` function. There's no need to provide a test implementation.
+
+```ts
+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
+$ bun test
+
+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
+$ bun test --todo
+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.md

@@ -0,0 +1,50 @@
+---
+name: Update snapshots in `bun test`
+---
+
+Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
+
+{% callout %}
+The `.toMatchInlineSnapshot()` method is not yet supported.
+{% /callout %}
+
+```ts#snap.test.ts
+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
+test
+├── __snapshots__
+│   └── snap.test.ts.snap
+└── snap.test.ts
+```
+
+---
+
+To regenerate snapshots, use the `--update-snapshots` flag.
+
+```sh
+$ bun test --update-snapshots
+bun test v1.x (9c68abdb)
+
+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/mocks) for complete documentation on mocking with the Bun test runner.

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

@@ -0,0 +1,19 @@
+---
+name: Run tests in watch mode with Bun
+---
+
+Use the `--watch` flag to run your tests in watch mode.
+
+```sh
+$ 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.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/dc49a36e-ba82-416f-b960-1c883a924248" caption="Running tests in watch mode in Bun" /%}
+
+---
+
+See [Docs > Test Runner](https://bun.sh/docs/cli/test) for complete documentation on the test runner.

package/docs/guides/util/base64.md

@@ -0,0 +1,15 @@
+---
+name: Encode and decode base64 strings
+---
+
+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.sh/docs/runtime/web-apis) for a complete breakdown of the Web APIs implemented in Bun.

package/docs/guides/util/deep-equals.md

@@ -0,0 +1,39 @@
+---
+name: Check if two objects are deeply equal
+---
+
+Check if two objects are deeply equal. This is used internally by `expect().toEqual()` in Bun's [test runner](https://bun.sh/docs/test/writing).
+
+```ts#index.ts
+const a = { a: 1, b: 2, c: { d: 3 } };
+const b = { a: 1, b: 2, c: { d: 3 } };
+
+Bun.deepEquals(a, b); // true
+```
+
+---
+
+Pass `true` as a third argument to enable strict mode. This is used internally by `expect().toStrictEqual()` in Bun's [test runner](https://bun.sh/docs/test/writing).
+
+The following examples would return `true` in non-strict mode but `false` in strict mode.
+
+```ts
+// undefined values
+Bun.deepEquals({}, { a: undefined }, true); // false
+
+// undefined in arrays
+Bun.deepEquals(["asdf"], ["asdf", undefined], true); // false
+
+// sparse arrays
+Bun.deepEquals([, 1], [undefined, 1], true); // false
+
+// object literals vs instances w/ same properties
+class Foo {
+  a = 1;
+}
+Bun.deepEquals(new Foo(), { a: 1 }, true); // false
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/util/deflate.md

@@ -0,0 +1,18 @@
+---
+name: Compress and decompress data with DEFLATE
+---
+
+Use `Bun.deflateSync()` to compress a `Uint8Array` with DEFLATE.
+
+```ts
+const data = Buffer.from("Hello, world!");
+const compressed = Bun.deflateSync("Hello, world!");
+// => Uint8Array
+
+const decompressed = Bun.inflateSync(compressed);
+// => Uint8Array
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.