.define method

lib/sinon/sandbox.js

@@ -212,7 +212,10 @@ function Sandbox() {
         const descriptor = getPropertyDescriptor(object, property);
 
         function restorer() {
-            if (descriptor.isOwn) {
+            if (typeof descriptor === 'undefined') {
+                object[property] = undefined;
+            }
+            else if (descriptor.isOwn) {
                 Object.defineProperty(object, property, descriptor);
             } else {
                 delete object[property];
@@ -278,6 +281,33 @@ function Sandbox() {
         return replacement;
     };
 
+    sandbox.define = function define(object, property, value) {
+        const descriptor = getPropertyDescriptor(object, property);
+
+        if (typeof descriptor !== "undefined") {
+            throw new TypeError(
+                `Cannot define the already existing property ${valueToString(
+                    property
+                )}`
+            );
+        }
+
+        if (typeof value === "undefined") {
+            throw new TypeError("Expected value argument to be defined");
+        }
+
+        // check just in case we allow to replace properties by undefined in the future
+        // in the implementation at the moment of writing, this check always succeeds
+        verifyNotReplaced(object, property);
+
+        // store a function for restoring the defined property
+        push(fakeRestorers, getFakeRestorer(object, property));
+
+        object[property] = value;
+
+        return value;
+    };
+
     sandbox.replaceGetter = function replaceGetter(
         object,
         property,

test/sandbox-test.js

@@ -807,11 +807,92 @@ describe("Sandbox", function () {
         });
     });
 
+    describe(".define", function () {
+        beforeEach(function () {
+            this.sandbox = createSandbox();
+        });
+
+        afterEach(function () {
+            this.sandbox.restore();
+        });
+
+        it("should define a function property", function () {
+            function newFunction() {
+                return;
+            }
+
+            const object = {};
+
+            this.sandbox.define(object, "property", newFunction);
+
+            assert.equals(object.property, newFunction);
+
+            this.sandbox.restore();
+
+            assert.isUndefined(object.property);
+        });
+
+        it("should define a non-function property", function () {
+            const newValue = "some-new-value";
+            const object = {};
+
+            this.sandbox.define(object, "property", newValue);
+
+            assert.equals(object.property, newValue);
+
+            this.sandbox.restore();
+
+            assert.isUndefined(object.property);
+        });
+
+        it("should error on existing descriptor", function () {
+            const sandbox = this.sandbox;
+
+            const existingValue = "123";
+            const existingFunction = () => "abcd";
+
+            const object = {
+                existingValue: existingValue,
+                existingFunction: existingFunction
+            };
+
+            assert.exception(
+                function () {
+                    sandbox.define(object, "existingValue", "new value");
+                },
+                {
+                    message:
+                        "Cannot define the already existing property existingValue",
+                    name: "TypeError",
+                }
+            );
+
+            assert.exception(
+                function () {
+                    sandbox.define(object, "existingFunction", () => "new function");
+                },
+                {
+                    message:
+                        "Cannot define the already existing property existingFunction",
+                    name: "TypeError",
+                }
+            );
+
+            // Verify that the methods above, even though they failed, did not replace the values
+            assert.equals(object.existingValue, existingValue);
+            assert.equals(object.existingFunction, existingFunction);
+        });
+    });
+
     describe(".replace", function () {
         beforeEach(function () {
             this.sandbox = createSandbox();
         });
 
+        afterEach(function () {
+            this.sandbox.restore();
+        });
+
         it("should replace a function property", function () {
             const replacement = function replacement() {
                 return;