Improve docs

3 files changed, 79 insertions, 4 deletions

diff --git a/docs/cli/install.md b/docs/cli/install.md
index beaf6ca47..4aa4e7816 100644
--- a/docs/cli/install.md
+++ b/docs/cli/install.md
@@ -43,7 +43,7 @@ Running `bun install` will:
 - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies.
 - **Write** a `bun.lockb` lockfile to the project root.
 
-To install in production mode (i.e. without `devDependencies`):
+To install in production mode (i.e. without `devDependencies` or `optionalDependencies`):
 
 ```bash
 $ bun install --production
diff --git a/docs/cli/test.md b/docs/cli/test.md
index dfe78c45b..d505cd6a8 100644
--- a/docs/cli/test.md
+++ b/docs/cli/test.md
@@ -1,4 +1,4 @@
-Bun ships with a fast built-in test runner. Tests are executed with the Bun runtime, and support the following features.
+Bun ships with a fast, built-in, Jest-compatible test runner. Tests are executed with the Bun runtime, and support the following features.
 
 - TypeScript and JSX
 - Lifecycle hooks
@@ -7,6 +7,10 @@ Bun ships with a fast built-in test runner. Tests are executed with the Bun runt
 - Watch mode with `--watch`
 - Script pre-loading with `--preload`
 
+{% callout %}
+Bun aims for compatibility with Jest, but not everything is implemented. To track compatibility, see [this tracking issue](https://github.com/oven-sh/bun/issues/1825).
+{% /callout %}
+
 ## Run tests
 
 ```bash
@@ -103,7 +107,11 @@ See [Test > Lifecycle](/docs/test/lifecycle) for complete documentation.
 
 ## Mocks
 
-Create mocks with the `mock` function. Mocks are automatically reset between tests.
+{% callout %}
+Module mocking (`jest.mock()`) is not yet supported. Track support for it [here](https://github.com/oven-sh/bun/issues/5394).
+{% /callout %}
+
+Create mock functions with the `mock` function. Mocks are automatically reset between tests.
 
 ```ts
 import { test, expect, mock } from "bun:test";
@@ -117,11 +125,38 @@ test("random", async () => {
 });
 ```
 
+Alternatively, you can use `jest.fn()`, it behaves identically.
+
+```ts-diff
+- import { test, expect, mock } from "bun:test";
++ import { test, expect, jest } from "bun:test";
+
+- const random = mock(() => Math.random());
++ const random = jest.fn(() => Math.random());
+```
+
 See [Test > Mocks](/docs/test/mocks) for complete documentation.
 
 ## Snapshot testing
 
-Snapshots are supported by `bun test`. See [Test > Snapshots](/docs/test/snapshots) for complete documentation.
+Snapshots are supported by `bun test`.
+
+```ts
+// example usage of toMatchSnapshot
+import { test, expect } from "bun:test";
+
+test("snapshot", async () => {
+  expect({ a: 1 }).toMatchSnapshot();
+});
+```
+
+To update snapshots, use the `--update-snapshots` flag.
+
+```sh
+$ bun test --update-snapshots
+```
+
+See [Test > Snapshots](/docs/test/snapshots) for complete documentation.
 
 ## UI & DOM testing
 
diff --git a/docs/test/mocks.md b/docs/test/mocks.md
index 31b5dab41..645e2a394 100644
--- a/docs/test/mocks.md
+++ b/docs/test/mocks.md
@@ -12,6 +12,23 @@ test("random", async () => {
 });
 ```
 
+{% 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
@@ -31,6 +48,29 @@ random.mock.results;
 //  ]
 ```
 
+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()`.