Various docs (#5201)

* Updates

* Improve jest guide

* Improve

4 files changed, 147 insertions, 4 deletions

diff --git a/docs/guides/install/trusted.md b/docs/guides/install/trusted.md
new file mode 100644
index 000000000..3dc14aa94
--- /dev/null
+++ b/docs/guides/install/trusted.md
@@ -0,0 +1,29 @@
+---
+name: Add a trusted dependency
+---
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall` and `node-gyp` builds. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
+
+---
+
+To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["my-trusted-package"]
+  }
+```
+
+<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+
+---
+
+Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
+
+Soon, Bun will include a built-in allow-list that automatically allows lifecycle scripts to be run by popular packages that are known to be safe. This is still under development.
+
+---
+
+See [Docs > Package manager > Trusted dependencies](/docs/cli/install#trusted-dependencies) for complete documentation of trusted dependencies.
diff --git a/docs/guides/test/happy-dom.md b/docs/guides/test/happy-dom.md
index 9c6728f88..072790929 100644
--- a/docs/guides/test/happy-dom.md
+++ b/docs/guides/test/happy-dom.md
@@ -49,7 +49,7 @@ test("set button text", () => {
 
 ---
 
-With Happy DOM propertly configured, this test runs as expected.
+With Happy DOM properly configured, this test runs as expected.
 
 ```sh
 $ bun test
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.
+
+<!-- ```ts-diff
+- import type {Config} from 'jest';
+-
+- const config: Config = {
+-   bail: 3
+- };
+``` -->
+
+```sh-diff
+$ 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` — 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)
diff --git a/docs/runtime/configuration.md b/docs/runtime/configuration.md
index ac71de582..df2fc5199 100644
--- a/docs/runtime/configuration.md
+++ b/docs/runtime/configuration.md
@@ -12,7 +12,9 @@ You can also create a global configuration file at the following paths:
 
 If both a global and local `bunfig` are detected, the results are shallow-merged, with local overriding global. CLI flags will override `bunfig` setting where applicable.
 
-## Runtime
+## `bunfig.toml`
+
+### Runtime
 
 ```toml
 # scripts to run before `bun run`ning a file or script
@@ -42,7 +44,7 @@ logLevel = "debug" # "debug", "warn", "error"
 ".bagel" = "js"
 ```
 
-## Test runner
+### Test runner
 
 ```toml
 [test]
@@ -53,7 +55,7 @@ preload = ["./setup.ts"]
 smol = true
 ```
 
-## Package manager
+### Package manager
 
 Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured in [`bunfig.toml`](/docs/runtime/configuration).