feat: Allow mocking property value in tests

packages/jest-environment/src/index.ts

@@ -319,6 +319,16 @@ export interface Jest {
    * behavior from most other test libraries.
    */
   spyOn: ModuleMocker['spyOn'];
+  /**
+   * Replaces property on object with mock value.
+   *
+   * This method does not work on 'get' or 'set' accessors, and cannot be called
+   * on already replaced value.
+   *
+   * @remarks
+   * For mocking functions, use `jest.spyOn()` instead.
+   */
+  mockProperty: ModuleMocker['mockProperty'];
   /**
    * Indicates that the module system should never return a mocked version of
    * the specified module from `require()` (e.g. that it should always return the

packages/jest-mock/src/__tests__/index.test.ts

@@ -1586,6 +1586,158 @@ describe('moduleMocker', () => {
       expect(spy2.mock.calls).toHaveLength(1);
     });
   });
+
+  describe('mockProperty', () => {
+    it('should work', () => {
+      const obj = {
+        property: 1,
+      };
+
+      const replaced = moduleMocker.mockProperty(obj, 'property', 2);
+
+      expect(obj.property).toBe(2);
+
+      replaced.mockRestore();
+
+      expect(obj.property).toBe(1);
+    });
+
+    describe('should throw', () => {
+      it('when object is not provided', () => {
+        expect(() => {
+          moduleMocker.mockProperty(null, 'property', 1);
+        }).toThrow(
+          'mockProperty could not find an object on which to replace property',
+        );
+      });
+
+      it('when primitive value is provided instead of object', () => {
+        expect(() => {
+          moduleMocker.mockProperty(1, 'property', 1);
+        }).toThrow('Cannot mock property on a primitive value; number given');
+      });
+
+      it('when function is provided instead of object', () => {
+        expect(() => {
+          moduleMocker.mockProperty(() => {}, 'property', 1);
+        }).toThrow('Cannot mock property on a primitive value; function given');
+      });
+
+      it('when property name is not provided', () => {
+        expect(() => {
+          moduleMocker.mockProperty({}, null, 1);
+        }).toThrow('No property name supplied');
+      });
+
+      it('when property is not defined', () => {
+        expect(() => {
+          moduleMocker.mockProperty({}, 'doesNotExist', 1);
+        }).toThrow('doesNotExist property does not exist');
+      });
+
+      it('when property is not configurable', () => {
+        expect(() => {
+          const obj = {};
+
+          Object.defineProperty(obj, 'property', {
+            configurable: false,
+            value: 1,
+            writable: false,
+          });
+
+          moduleMocker.mockProperty(obj, 'property', 2);
+        }).toThrow('property is not declared configurable');
+      });
+
+      it('when mocking with value of different type', () => {
+        expect(() => {
+          moduleMocker.mockProperty({property: 1}, 'property', 'string');
+        }).toThrow(
+          'Cannot mock the property property because it is not a number; string given instead',
+        );
+      });
+
+      it('when trying to mock a method', () => {
+        expect(() => {
+          moduleMocker.mockProperty({method: () => {}}, 'method', () => {});
+        }).toThrow(
+          'Cannot mock the method property because it is a function; use spyOn instead',
+        );
+      });
+
+      it('when mocking a getter', () => {
+        const obj = {
+          get getter() {
+            return 1;
+          },
+        };
+
+        expect(() => {
+          moduleMocker.mockProperty(obj, 'getter', 1);
+        }).toThrow('Cannot mock the getter property because it has a getter');
+      });
+
+      it('when mocking a setter', () => {
+        const obj = {
+          // eslint-disable-next-line accessor-pairs
+          set setter(_value: number) {},
+        };
+
+        expect(() => {
+          moduleMocker.mockProperty(obj, 'setter', 1);
+        }).toThrow('Cannot mock the setter property because it has a setter');
+      });
+    });
+
+    it('should not replace property that has been already replaced', () => {
+      const obj = {
+        property: 1,
+      };
+
+      moduleMocker.mockProperty(obj, 'property', 2);
+
+      expect(() => {
+        moduleMocker.mockProperty(obj, 'property', 3);
+      }).toThrow(
+        'Cannot mock the property property because it is already mocked',
+      );
+    });
+
+    it('should work for property from prototype chain', () => {
+      const parent = {property: 'abcd'};
+      const child = Object.create(parent);
+
+      const replaced = moduleMocker.mockProperty(child, 'property', 'defg');
+
+      expect(child.property).toBe('defg');
+
+      replaced.mockRestore();
+
+      expect(child.property).toBe('abcd');
+      expect(
+        Object.getOwnPropertyDescriptor(child, 'property'),
+      ).toBeUndefined();
+    });
+
+    it('should restore property as part of calling restoreAllMocks', () => {
+      const obj = {
+        property: 1,
+      };
+
+      const replaced = moduleMocker.mockProperty(obj, 'property', 2);
+
+      expect(obj.property).toBe(2);
+
+      moduleMocker.restoreAllMocks();
+
+      expect(obj.property).toBe(1);
+
+      // Just make sure that this call won't break anything while calling after the property has been already restored
+      replaced.mockRestore();
+
+      expect(obj.property).toBe(1);
+    });
+  });
 });
 
 describe('mocked', () => {

packages/jest-mock/src/index.ts

@@ -172,6 +172,19 @@ export interface MockInstance<T extends FunctionLike = UnknownFunction> {
   mockRejectedValueOnce(value: RejectType<T>): this;
 }
 
+export interface MockedProperty {
+  /**
+   * Restore property to its original value known at the time of mocking.
+   */
+  mockRestore(): void;
+}
+
+type MockedPropertyRestorer<T = object> = {
+  (): void;
+  object: T;
+  property: keyof T;
+};
+
 type MockFunctionResultIncomplete = {
   type: 'incomplete';
   /**
@@ -987,6 +1000,27 @@ export class ModuleMocker {
     return mock as Mocked<T>;
   }
 
+  /**
+   * Check whether given property of an object has been already mocked.
+   */
+  private _isAlreadyMocked<T extends object>(
+    object: T,
+    propertyKey: keyof T,
+  ): boolean {
+    for (const spyState of this._spyState) {
+      if (
+        'object' in spyState &&
+        'property' in spyState &&
+        (spyState as MockedPropertyRestorer).object === object &&
+        (spyState as MockedPropertyRestorer).property === propertyKey
+      ) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   /**
    * @see README.md
    * @param metadata Metadata for the mock in the schema returned by the
@@ -1277,6 +1311,116 @@ export class ModuleMocker {
     return mock;
   }
 
+  mockProperty<
+    T extends object,
+    P extends PropertyLikeKeys<T>,
+    V extends Required<T>[P],
+  >(object: T, propertyKey: P, value: V): MockedProperty {
+    if (!object) {
+      throw new Error(
+        `mockProperty could not find an object on which to replace ${String(
+          propertyKey,
+        )}`,
+      );
+    }
+
+    if (!propertyKey) {
+      throw new Error('No property name supplied');
+    }
+
+    if (typeof object !== 'object') {
+      throw new Error(
+        `Cannot mock property on a primitive value; ${this._typeOf(
+          object,
+        )} given`,
+      );
+    }
+
+    let descriptor = Object.getOwnPropertyDescriptor(object, propertyKey);
+    let proto = Object.getPrototypeOf(object);
+    while (!descriptor && proto !== null) {
+      descriptor = Object.getOwnPropertyDescriptor(proto, propertyKey);
+      proto = Object.getPrototypeOf(proto);
+    }
+    if (!descriptor) {
+      throw new Error(`${String(propertyKey)} property does not exist`);
+    }
+    if (!descriptor.configurable) {
+      throw new Error(`${String(propertyKey)} is not declared configurable`);
+    }
+
+    if (this._isAlreadyMocked(object, propertyKey)) {
+      throw new Error(
+        `Cannot mock the ${String(
+          propertyKey,
+        )} property because it is already mocked`,
+      );
+    }
+
+    if (descriptor.get !== undefined) {
+      throw new Error(
+        `Cannot mock the ${String(
+          propertyKey,
+        )} property because it has a getter`,
+      );
+    }
+
+    if (descriptor.set !== undefined) {
+      throw new Error(
+        `Cannot mock the ${String(
+          propertyKey,
+        )} property because it has a setter`,
+      );
+    }
+
+    if (typeof descriptor.value !== typeof value) {
+      throw new Error(
+        `Cannot mock the ${String(
+          propertyKey,
+        )} property because it is not a ${this._typeOf(
+          descriptor.value,
+        )}; ${this._typeOf(value)} given instead`,
+      );
+    }
+
+    if (typeof descriptor.value === 'function') {
+      throw new Error(
+        `Cannot mock the ${String(
+          propertyKey,
+        )} property because it is a function; use spyOn instead`,
+      );
+    }
+
+    const isPropertyOwner = Object.prototype.hasOwnProperty.call(
+      object,
+      propertyKey,
+    );
+    const originalValue = descriptor.value;
+
+    object[propertyKey] = value;
+
+    const restore: MockedPropertyRestorer<typeof object> = () => {
+      if (isPropertyOwner) {
+        object[propertyKey] = originalValue;
+      } else {
+        delete object[propertyKey];
+      }
+    };
+
+    restore.object = object;
+    restore.property = propertyKey;
+
+    this._spyState.add(restore);
+
+    return {
+      mockRestore: (): void => {
+        restore();
+
+        this._spyState.delete(restore);
+      },
+    };
+  }
+
   clearAllMocks(): void {
     this._mockState = new WeakMap();
   }