From 18b521d9b875f4514e413dbe9b614309fd1618aa Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Tue, 12 Sep 2023 21:51:49 -0700 Subject: Various docs (#5201) * Updates * Improve jest guide * Improve --- docs/guides/test/migrate-from-jest.md | 112 ++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/guides/test/migrate-from-jest.md (limited to 'docs/guides/test/migrate-from-jest.md') diff --git a/docs/guides/test/migrate-from-jest.md b/docs/guides/test/migrate-from-jest.md new file mode 100644 index 000000000..595ac0fae --- /dev/null +++ b/docs/guides/test/migrate-from-jest.md @@ -0,0 +1,112 @@ +--- +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-diff +- $ 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](/docs/test/writing#matchers). + +Some notable missing features: + +- `expect.extend()` +- `expect().toMatchInlineSnapshot()` +- `expect().toHaveBeenCalledWith()` +- `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. + + + +```sh-diff +$ bun test --bail 3 +``` + +--- + +Replace `collectCoverage` with the `--coverage` CLI flag. + + + +```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` — Buns supports TypeScript & JSX. Other file types can be configured with [Plugins](/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`](/docs/runtime/configuration.md#runtime) + +--- + +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](/docs/test/writing) -- cgit v1.2.3 From 31691e3898ff9fe4d51092a9d1c49388a2ad97ed Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Thu, 14 Sep 2023 21:02:52 -0700 Subject: Fix links --- docs/api/utils.md | 2 +- docs/guides/test/migrate-from-jest.md | 2 +- docs/runtime/jsx.md | 2 +- docs/runtime/plugins.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/guides/test/migrate-from-jest.md') diff --git a/docs/api/utils.md b/docs/api/utils.md index 1e18c67e1..9889d6aa0 100644 --- a/docs/api/utils.md +++ b/docs/api/utils.md @@ -183,7 +183,7 @@ const currentFile = import.meta.url; Bun.openInEditor(currentFile); ``` -You can override this via the `debug.editor` setting in your [`bunfig.toml`](/docs/runtime/configuration) +You can override this via the `debug.editor` setting in your [`bunfig.toml`](/docs/runtime/bunfig) ```toml-diff#bunfig.toml + [debug] diff --git a/docs/guides/test/migrate-from-jest.md b/docs/guides/test/migrate-from-jest.md index 595ac0fae..4adbddc34 100644 --- a/docs/guides/test/migrate-from-jest.md +++ b/docs/guides/test/migrate-from-jest.md @@ -98,7 +98,7 @@ Many other flags become irrelevant or obsolete when using `bun test`. - `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`](/docs/runtime/configuration.md#runtime) +- `verbose` — set `logLevel: "debug"` in [`bunfig.toml`](/docs/runtime/bunfig#loglevel) --- diff --git a/docs/runtime/jsx.md b/docs/runtime/jsx.md index 3d37dbe01..31a61652b 100644 --- a/docs/runtime/jsx.md +++ b/docs/runtime/jsx.md @@ -14,7 +14,7 @@ console.log(); ## Configuration -Bun reads your `tsconfig.json` or `jsconfig.json` configuration files to determines how to perform the JSX transform internally. To avoid using either of these, the following options can also be defined in [`bunfig.toml`](/docs/runtime/configuration). +Bun reads your `tsconfig.json` or `jsconfig.json` configuration files to determines how to perform the JSX transform internally. To avoid using either of these, the following options can also be defined in [`bunfig.toml`](/docs/runtime/bunfig). The following compiler options are respected. diff --git a/docs/runtime/plugins.md b/docs/runtime/plugins.md index a1525790a..8f5bf21e2 100644 --- a/docs/runtime/plugins.md +++ b/docs/runtime/plugins.md @@ -17,7 +17,7 @@ const myPlugin: BunPlugin = { }; ``` -Plugins have to be registered before any other code runs! To achieve this, use the `preload` option in your [`bunfig.toml`](/docs/runtime/configuration). Bun automatically loads the files/modules specified in `preload` before running a file. +Plugins have to be registered before any other code runs! To achieve this, use the `preload` option in your [`bunfig.toml`](/docs/runtime/bunfig). Bun automatically loads the files/modules specified in `preload` before running a file. ```toml preload = ["./myPlugin.ts"] -- cgit v1.2.3