test: add common.mustNotMutate()

Author: LiviaMedeiros

test/common/README.md

@@ -299,6 +299,40 @@ If `fn` is not provided, an empty function will be used.
 Returns a function that triggers an `AssertionError` if it is invoked. `msg` is
 used as the error message for the `AssertionError`.
 
+### `mustNotMutate([target])`
+
+* `target` [\<any>][<any>] default = `undefined`
+* return [\<any>][<any>]
+
+If `target` is an Object, returns a proxy object that triggers
+an `AssertionError` on mutation attempt, including mutation of deeply nested
+objects. Otherwise, it returns `target` directly.
+
+Use of this function is encouraged for relevant regression tests and for new
+APIs that work with user-provided objects.
+
+```mjs
+import { open } from 'node:fs/promises';
+import { mustNotMutate } from '../common/index.mjs';
+
+const _mutableOptions = { length: 4, position: 8 };
+const options = mustNotMutate(_mutableOptions);
+
+// In filehandle.read or filehandle.write, attempt to mutate options will throw
+// In the test code, options can still be mutated via _mutableOptions
+const fh = await open('/path/to/file', 'r+');
+const { buffer } = await fh.read(options);
+_mutableOptions.position = 4;
+await fh.write(buffer, options);
+
+// Inline usage
+const stats = await fh.stat(mustNotMutate({ bigint: true }));
+console.log(stats.size);
+```
+
+Caveat: built-in objects that make use of their internal slots (for example,
+`Map`s and `Set`s) might not work with this function.
+
 ### `mustSucceed([fn])`
 
 * `fn` [\<Function>][<Function>] default = () => {}
@@ -1024,6 +1058,7 @@ See [the WPT tests README][] for details.
 [<Function>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
 [<Object>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
 [<RegExp>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp
+[<any>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_types
 [<bigint>]: https://github.com/tc39/proposal-bigint
 [<boolean>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type
 [<number>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type

test/common/index.js

@@ -519,6 +519,48 @@ function mustNotCall(msg) {
   };
 }
 
+const _mustNotMutateProxies = new WeakMap();
+
+function mustNotMutate(original) {
+  if (original === null || typeof original !== 'object') {
+    return original;
+  }
+
+  const cachedProxy = _mustNotMutateProxies.get(original);
+  if (cachedProxy) {
+    return cachedProxy;
+  }
+
+  const _mustNotMutateHandler = {
+    defineProperty(target, property, descriptor) {
+      assert.fail(`Expected no side effects, got ${util.inspect(property)} ` +
+                  'defined');
+    },
+    deleteProperty(target, property) {
+      assert.fail(`Expected no side effects, got ${util.inspect(property)} ` +
+                  'deleted');
+    },
+    get(target, prop, receiver) {
+      return mustNotMutate(Reflect.get(target, prop, receiver));
+    },
+    preventExtensions(target) {
+      assert.fail('Expected no side effects, got extensions prevented on ' +
+                  util.inspect(target));
+    },
+    set(target, property, value, receiver) {
+      assert.fail(`Expected no side effects, got ${util.inspect(value)} ` +
+                  `assigned to ${util.inspect(property)}`);
+    },
+    setPrototypeOf(target, prototype) {
+      assert.fail(`Expected no side effects, got set prototype to ${prototype}`);
+    }
+  };
+
+  const proxy = new Proxy(original, _mustNotMutateHandler);
+  _mustNotMutateProxies.set(original, proxy);
+  return proxy;
+}
+
 function printSkipMessage(msg) {
   console.log(`1..0 # Skipped: ${msg}`);
 }
@@ -827,6 +869,7 @@ const common = {
   mustCall,
   mustCallAtLeast,
   mustNotCall,
+  mustNotMutate,
   mustSucceed,
   nodeProcessAborted,
   PIPE,

test/common/index.mjs

@@ -35,6 +35,7 @@ const {
   canCreateSymLink,
   getCallSite,
   mustNotCall,
+  mustNotMutate,
   printSkipMessage,
   skip,
   nodeProcessAborted,
@@ -81,6 +82,7 @@ export {
   canCreateSymLink,
   getCallSite,
   mustNotCall,
+  mustNotMutate,
   printSkipMessage,
   skip,
   nodeProcessAborted,

test/parallel/test-common-must-not-mutate.mjs

@@ -0,0 +1,186 @@
+import { mustNotMutate } from '../common/index.mjs';
+import assert from 'node:assert';
+
+// Test common.mustNotMutate()
+
+const original = {
+  foo: { bar: 'baz' },
+  qux: null,
+  quux: [
+    'quuz',
+    { corge: 'grault' },
+  ],
+};
+
+// Wrapper for convenience
+const obj = () => mustNotMutate(original);
+
+function testOriginal(root) {
+  assert.deepStrictEqual(root, original);
+  return root.foo.bar === 'baz' && root.quux[1].corge.length === 6;
+}
+
+function definePropertyOnRoot(root) {
+  Object.defineProperty(root, 'xyzzy', {});
+}
+
+function definePropertyOnFoo(root) {
+  Object.defineProperty(root.foo, 'xyzzy', {});
+}
+
+function deletePropertyOnRoot(root) {
+  delete root.foo;
+}
+
+function deletePropertyOnFoo(root) {
+  delete root.foo.bar;
+}
+
+function preventExtensionsOnRoot(root) {
+  Object.preventExtensions(root);
+}
+
+function preventExtensionsOnFoo(root) {
+  Object.preventExtensions(root.foo);
+}
+
+function preventExtensionsOnRootViaSeal(root) {
+  Object.seal(root);
+}
+
+function preventExtensionsOnFooViaSeal(root) {
+  Object.seal(root.foo);
+}
+
+function preventExtensionsOnRootViaFreeze(root) {
+  Object.freeze(root);
+}
+
+function preventExtensionsOnFooViaFreeze(root) {
+  Object.freeze(root.foo);
+}
+
+function setOnRoot(root) {
+  root.xyzzy = 'gwak';
+}
+
+function setOnFoo(root) {
+  root.foo.xyzzy = 'gwak';
+}
+
+function setQux(root) {
+  root.qux = 'gwak';
+}
+
+function setQuux(root) {
+  root.quux.push('gwak');
+}
+
+function setQuuxItem(root) {
+  root.quux[0] = 'gwak';
+}
+
+function setQuuxProperty(root) {
+  root.quux[1].corge = 'gwak';
+}
+
+function setPrototypeOfRoot(root) {
+  Object.setPrototypeOf(root, Array);
+}
+
+function setPrototypeOfFoo(root) {
+  Object.setPrototypeOf(root.foo, Array);
+}
+
+function setPrototypeOfQuux(root) {
+  Object.setPrototypeOf(root.quux, Array);
+}
+
+
+{
+  assert.ok(testOriginal(obj()));
+
+  assert.throws(
+    () => definePropertyOnRoot(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => definePropertyOnFoo(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => deletePropertyOnRoot(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => deletePropertyOnFoo(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => preventExtensionsOnRoot(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => preventExtensionsOnFoo(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => preventExtensionsOnRootViaSeal(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => preventExtensionsOnFooViaSeal(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => preventExtensionsOnRootViaFreeze(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => preventExtensionsOnFooViaFreeze(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setOnRoot(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setOnFoo(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setQux(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setQuux(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setQuux(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setQuuxItem(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setQuuxProperty(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setPrototypeOfRoot(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setPrototypeOfFoo(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+  assert.throws(
+    () => setPrototypeOfQuux(obj()),
+    { code: 'ERR_ASSERTION' }
+  );
+
+  // Test that no mutation happened
+  assert.ok(testOriginal(obj()));
+}