From d659f361fe002712a82a3dc7500f2ce375966329 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= <arauujogui@gmail.com>
Date: Fri, 9 Oct 2026 14:52:49 -0300
Subject: [PATCH] test_runner: add mockReturnValue and promise helpers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add mockReturnValue(), mockResolvedValue() and mockRejectedValue()
to MockFunctionContext as shorthands for common mockImplementation()
patterns.

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
---
 doc/api/test.md                       | 63 +++++++++++++++++++++++++++
 lib/internal/test_runner/mock/mock.js | 26 +++++++++++
 test/parallel/test-runner-mocking.js  | 36 +++++++++++++++
 3 files changed, 125 insertions(+)

diff --git a/doc/api/test.md b/doc/api/test.md
index a2c98388fa4f..84947e2a3432 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -2464,6 +2464,69 @@ test('changes a mock behavior once', (t) => {
 });
 ```
 
+### `ctx.mockRejectedValue(reason)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `reason` {any} The value the returned promise rejects with.
+
+Changes the mock's implementation to a function that returns a promise rejected
+with `reason`. This is shorthand for
+`ctx.mockImplementation(() => Promise.reject(reason))`.
+
+```js
+test('mocks a rejected value', async (t) => {
+  const fn = t.mock.fn();
+
+  fn.mock.mockRejectedValue(new Error('boom'));
+  await assert.rejects(fn(), { message: 'boom' });
+});
+```
+
+### `ctx.mockResolvedValue(value)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `value` {any} The value the returned promise resolves with.
+
+Changes the mock's implementation to a function that returns a promise resolved
+with `value`. This is shorthand for
+`ctx.mockImplementation(() => Promise.resolve(value))`.
+
+```js
+test('mocks a resolved value', async (t) => {
+  const fn = t.mock.fn();
+
+  fn.mock.mockResolvedValue(42);
+  assert.strictEqual(await fn(), 42);
+});
+```
+
+### `ctx.mockReturnValue(value)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `value` {any} The value returned by the mock.
+
+Changes the mock's implementation to a function that returns `value`. This is
+shorthand for `ctx.mockImplementation(() => value)`.
+
+```js
+test('mocks a return value', (t) => {
+  const fn = t.mock.fn();
+
+  fn.mock.mockReturnValue(42);
+  assert.strictEqual(fn(), 42);
+  assert.strictEqual(fn(), 42);
+});
+```
+
 ### `ctx.resetCalls()`
 
 <!-- YAML
diff --git a/lib/internal/test_runner/mock/mock.js b/lib/internal/test_runner/mock/mock.js
index 996c8a7bcca0..f4f2b9cbade4 100644
--- a/lib/internal/test_runner/mock/mock.js
+++ b/lib/internal/test_runner/mock/mock.js
@@ -15,6 +15,8 @@ const {
   ObjectKeys,
   ObjectSetPrototypeOf,
   ObjectValues,
+  PromiseReject,
+  PromiseResolve,
   Proxy,
   ReflectApply,
   ReflectConstruct,
@@ -143,6 +145,30 @@ class MockFunctionContext {
     this.#mocks.set(call, implementation);
   }
 
+  /**
+   * Sets a new implementation that always returns the given value.
+   * @param {any} value - The value to return.
+   */
+  mockReturnValue(value) {
+    this.#implementation = function() { return value; };
+  }
+
+  /**
+   * Sets a new implementation that returns a promise resolved with the given value.
+   * @param {any} value - The value to resolve with.
+   */
+  mockResolvedValue(value) {
+    this.#implementation = function() { return PromiseResolve(value); };
+  }
+
+  /**
+   * Sets a new implementation that returns a promise rejected with the given reason.
+   * @param {any} reason - The reason to reject with.
+   */
+  mockRejectedValue(reason) {
+    this.#implementation = function() { return PromiseReject(reason); };
+  }
+
   /**
    * Restores the original function that was mocked.
    */
diff --git a/test/parallel/test-runner-mocking.js b/test/parallel/test-runner-mocking.js
index 634eff931651..b9a5ee159ae7 100644
--- a/test/parallel/test-runner-mocking.js
+++ b/test/parallel/test-runner-mocking.js
@@ -892,6 +892,42 @@ test('mock implementation can be changed dynamically', (t) => {
   assert.strictEqual(fn.mock.callCount(), 12);
 });
 
+test('mockReturnValue() sets a fixed return value', (t) => {
+  const fn = t.mock.fn(common.mustNotCall());
+
+  fn.mock.mockReturnValue(42);
+  assert.strictEqual(fn(), 42);
+  assert.strictEqual(fn(1, 2), 42);
+  assert.strictEqual(fn.mock.callCount(), 2);
+  assert.strictEqual(fn.mock.calls[1].result, 42);
+});
+
+test('mockResolvedValue() returns a resolved promise', async (t) => {
+  const fn = t.mock.fn(common.mustNotCall());
+
+  fn.mock.mockResolvedValue(42);
+  const result = fn();
+  assert(result instanceof Promise);
+  assert.strictEqual(await result, 42);
+});
+
+test('mockRejectedValue() returns a rejected promise', async (t) => {
+  const fn = t.mock.fn(common.mustNotCall());
+  const error = new Error('boom');
+
+  fn.mock.mockRejectedValue(error);
+  await assert.rejects(fn(), error);
+});
+
+test('mockImplementationOnce() takes precedence over mockReturnValue()', (t) => {
+  const fn = t.mock.fn();
+
+  fn.mock.mockReturnValue(1);
+  fn.mock.mockImplementationOnce(() => 2);
+  assert.strictEqual(fn(), 2);
+  assert.strictEqual(fn(), 1);
+});
+
 test('local mocks are auto restored after the test finishes', async (t) => {
   const obj = {
     foo() {},