test_runner: add mockReturnValue and promise helpers

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

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.
    */

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() {},