Merge branch 'main' into postinstall_3

3 files changed, 94 insertions, 60 deletions

diff --git a/docs/test/lifecycle.md b/docs/test/lifecycle.md
index fd804c9bb..3fa69b1e3 100644
--- a/docs/test/lifecycle.md
+++ b/docs/test/lifecycle.md
@@ -44,11 +44,11 @@ To scope the hooks to a test file:
 ```ts
 import { describe, beforeAll } from "bun:test";
 
-describe("test group", () => {
-  beforeAll(() => {
-    // setup
-  });
+beforeAll(() => {
+  // setup
+});
 
+describe("test group", () => {
   // tests...
 });
 ```
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()`.
diff --git a/docs/test/writing.md b/docs/test/writing.md
index ef26a802a..b8b0118f7 100644
--- a/docs/test/writing.md
+++ b/docs/test/writing.md
@@ -143,12 +143,6 @@ To run a test conditionally, use `test.if()`. The test will run if the condition
 test.if(Math.random() > 0.5)("runs half the time", () => {
   // ...
 });
-```
-
-```ts
-test.if(Math.random() > 0.5)("runs half the time", () => {
-  // ...
-});
 
 const macOS = process.arch === "darwin";
 test.if(macOS)("runs on macOS", () => {
@@ -174,252 +168,252 @@ Bun implements the following matchers. Full Jest compatibility is on the roadmap
 
 ---
 
-- 🟢
+- ✅
 - [`.not`](https://jestjs.io/docs/expect#not)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBe()`](https://jestjs.io/docs/expect#tobevalue)
 
 ---
 
-- 🟢
+- ✅
 - [`.toEqual()`](https://jestjs.io/docs/expect#toequalvalue)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeNull()`](https://jestjs.io/docs/expect#tobenull)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeUndefined()`](https://jestjs.io/docs/expect#tobeundefined)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeNaN()`](https://jestjs.io/docs/expect#tobenan)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeDefined()`](https://jestjs.io/docs/expect#tobedefined)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeFalsy()`](https://jestjs.io/docs/expect#tobefalsy)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeTruthy()`](https://jestjs.io/docs/expect#tobetruthy)
 
 ---
 
-- 🟢
+- ✅
 - [`.toContain()`](https://jestjs.io/docs/expect#tocontainitem)
 
 ---
 
-- 🟢
+- ✅
 - [`.toStrictEqual()`](https://jestjs.io/docs/expect#tostrictequalvalue)
 
 ---
 
-- 🟢
+- ✅
 - [`.toThrow()`](https://jestjs.io/docs/expect#tothrowerror)
 
 ---
 
-- 🟢
+- ✅
 - [`.toHaveLength()`](https://jestjs.io/docs/expect#tohavelengthnumber)
 
 ---
 
-- 🟢
+- ✅
 - [`.toHaveProperty()`](https://jestjs.io/docs/expect#tohavepropertykeypath-value)
 
 ---
 
-- 🔴
+- ❌
 - [`.extend`](https://jestjs.io/docs/expect#expectextendmatchers)
 
 ---
 
-- 🟢
+- ✅
 - [`.anything()`](https://jestjs.io/docs/expect#expectanything)
 
 ---
 
-- 🟢
+- ✅
 - [`.any()`](https://jestjs.io/docs/expect#expectanyconstructor)
 
 ---
 
-- 🔴
+- ❌
 - [`.arrayContaining()`](https://jestjs.io/docs/expect#expectarraycontainingarray)
 
 ---
 
-- 🔴
+- ❌
 - [`.assertions()`](https://jestjs.io/docs/expect#expectassertionsnumber)
 
 ---
 
-- 🔴
+- ❌
 - [`.closeTo()`](https://jestjs.io/docs/expect#expectclosetonumber-numdigits)
 
 ---
 
-- 🔴
+- ❌
 - [`.hasAssertions()`](https://jestjs.io/docs/expect#expecthasassertions)
 
 ---
 
-- 🔴
+- ❌
 - [`.objectContaining()`](https://jestjs.io/docs/expect#expectobjectcontainingobject)
 
 ---
 
-- 🟢
+- ✅
 - [`.stringContaining()`](https://jestjs.io/docs/expect#expectstringcontainingstring)
 
 ---
 
-- 🟢
+- ✅
 - [`.stringMatching()`](https://jestjs.io/docs/expect#expectstringmatchingstring--regexp)
 
 ---
 
-- 🔴
+- ❌
 - [`.addSnapshotSerializer()`](https://jestjs.io/docs/expect#expectaddsnapshotserializerserializer)
 
 ---
 
-- 🟢
+- ✅
 - [`.resolves()`](https://jestjs.io/docs/expect#resolves)
 
 ---
 
-- 🟢
+- ✅
 - [`.rejects()`](https://jestjs.io/docs/expect#rejects)
 
 ---
 
-- 🟢
+- ✅
 - [`.toHaveBeenCalled()`](https://jestjs.io/docs/expect#tohavebeencalled)
 
 ---
 
-- 🟢
+- ✅
 - [`.toHaveBeenCalledTimes()`](https://jestjs.io/docs/expect#tohavebeencalledtimesnumber)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveBeenCalledWith()`](https://jestjs.io/docs/expect#tohavebeencalledwitharg1-arg2-)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveBeenLastCalledWith()`](https://jestjs.io/docs/expect#tohavebeenlastcalledwitharg1-arg2-)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveBeenNthCalledWith()`](https://jestjs.io/docs/expect#tohavebeennthcalledwithnthcall-arg1-arg2-)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveReturned()`](https://jestjs.io/docs/expect#tohavereturned)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveReturnedTimes()`](https://jestjs.io/docs/expect#tohavereturnedtimesnumber)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveReturnedWith()`](https://jestjs.io/docs/expect#tohavereturnedwithvalue)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveLastReturnedWith()`](https://jestjs.io/docs/expect#tohavelastreturnedwithvalue)
 
 ---
 
-- 🔴
+- ❌
 - [`.toHaveNthReturnedWith()`](https://jestjs.io/docs/expect#tohaventhreturnedwithnthcall-value)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeCloseTo()`](https://jestjs.io/docs/expect#tobeclosetonumber-numdigits)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeGreaterThan()`](https://jestjs.io/docs/expect#tobegreaterthannumber--bigint)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeGreaterThanOrEqual()`](https://jestjs.io/docs/expect#tobegreaterthanorequalnumber--bigint)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeLessThan()`](https://jestjs.io/docs/expect#tobelessthannumber--bigint)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeLessThanOrEqual()`](https://jestjs.io/docs/expect#tobelessthanorequalnumber--bigint)
 
 ---
 
-- 🟢
+- ✅
 - [`.toBeInstanceOf()`](https://jestjs.io/docs/expect#tobeinstanceofclass)
 
 ---
 
-- 🔴
+- ❌
 - [`.toContainEqual()`](https://jestjs.io/docs/expect#tocontainequalitem)
 
 ---
 
-- 🟢
+- ✅
 - [`.toMatch()`](https://jestjs.io/docs/expect#tomatchregexp--string)
 
 ---
 
-- 🟢
+- ✅
 - [`.toMatchObject()`](https://jestjs.io/docs/expect#tomatchobjectobject)
 
 ---
 
-- 🟢
+- ✅
 - [`.toMatchSnapshot()`](https://jestjs.io/docs/expect#tomatchsnapshotpropertymatchers-hint)
 
 ---
 
-- 🔴
+- ❌
 - [`.toMatchInlineSnapshot()`](https://jestjs.io/docs/expect#tomatchinlinesnapshotpropertymatchers-inlinesnapshot)
 
 ---
 
-- 🔴
+- ❌
 - [`.toThrowErrorMatchingSnapshot()`](https://jestjs.io/docs/expect#tothrowerrormatchingsnapshothint)
 
 ---
 
-- 🔴
+- ❌
 - [`.toThrowErrorMatchingInlineSnapshot()`](https://jestjs.io/docs/expect#tothrowerrormatchinginlinesnapshotinlinesnapshot)
 
 {% /table %}