doc: clarify behavior of destructured assertion methods in Assert instance

Author: miguelmarcondesf

doc/api/assert.md

@@ -242,20 +242,25 @@ assertInstance.deepStrictEqual({ a: 1 }, { a: 2 });
 // Shows a full diff in the error message.
 ```
 
-**Important**: When destructuring assertion methods from an `Assert` instance, the methods lose their connection to the instance's configuration options (such as `diff` and `strict` settings). The destructured methods will behave with default options instead.
+**Important**: When destructuring assertion methods from an `Assert` instance,
+the methods lose their connection to the instance's configuration options (such as `diff` and `strict` settings).
+The destructured methods will fall back to default behavior instead.
 
 ```js
 const myAssert = new Assert({ diff: 'full' });
 
 // This works as expected - uses 'full' diff
 myAssert.strictEqual({ a: 1 }, { b: { c: 1 } });
 
-// This loses the 'full' diff setting - uses default 'simple' diff
+// This loses the 'full' diff setting - falls back to default 'simple' diff
 const { strictEqual } = myAssert;
 strictEqual({ a: 1 }, { b: { c: 1 } });
 ```
 
-To maintain custom options when using destructured methods, pass the options to individual assertion calls or avoid destructuring.
+When destructured, methods lose access to the instance's `this` context and revert to default assertion behavior
+(diff: 'simple', non-strict mode).
+To maintain custom options when using destructured methods, avoid
+destructuring and call methods directly on the instance.
 
 ## `assert(value[, message])`
 

lib/assert.js

@@ -135,6 +135,12 @@ function Assert(options) {
 // both the actual and expected values to the assertion error for
 // display purposes.
 
+// DESTRUCTURING WARNING: All Assert.prototype methods use optional chaining
+// (this?.[kOptions]) to safely access instance configuration. When methods are
+// destructured from an Assert instance (e.g., const {strictEqual} = myAssert),
+// they lose their `this` context and will use default behavior instead of the
+// instance's custom options.
+
 function innerFail(obj) {
   if (obj.message instanceof Error) throw obj.message;
 
@@ -154,6 +160,10 @@ Assert.prototype.fail = function fail(message) {
     internalMessage = true;
   }
 
+  // IMPORTANT: When adding new references to `this`, ensure they use optional chaining
+  // (this?.[kOptions]?.diff) to handle cases where the method is destructured from an
+  // Assert instance and loses its context. Destructured methods will fall back
+  // to default behavior when `this` is undefined.
   const errArgs = {
     operator: 'fail',
     stackStartFn: fail,

test/parallel/test-assert-class-destructuring.js

@@ -0,0 +1,133 @@
+'use strict';
+
+require('../common');
+const assert = require('assert');
+const { Assert } = require('assert');
+const { test } = require('node:test');
+
+// Disable colored output to prevent color codes from breaking assertion
+// message comparisons. This should only be an issue when process.stdout
+// is a TTY.
+if (process.stdout.isTTY) {
+  process.env.NODE_DISABLE_COLORS = '1';
+}
+
+test('Assert class destructuring behavior - diff option', () => {
+  const assertInstanceFull = new Assert({ diff: 'full' });
+  const assertInstanceSimple = new Assert({ diff: 'simple' });
+
+  assertInstanceFull.throws(
+    () => assertInstanceFull.strictEqual({ a: 1 }, { a: 2 }),
+    (err) => {
+      assert.strictEqual(err.diff, 'full');
+      return true;
+    }
+  );
+
+  assertInstanceSimple.throws(
+    () => assertInstanceSimple.strictEqual({ a: 1 }, { a: 2 }),
+    (err) => {
+      assert.strictEqual(err.diff, 'simple');
+      return true;
+    }
+  );
+
+  const { strictEqual: strictEqualSimple } = assertInstanceSimple;
+  const { strictEqual: strictEqualFull } = assertInstanceFull;
+  const { deepStrictEqual: deepStrictEqualFull } = assertInstanceFull;
+  const { equal: equalFull } = assertInstanceFull;
+
+  assert.throws(
+    () => strictEqualSimple({ a: 1 }, { a: 2 }),
+    (err) => {
+      assert.strictEqual(err.diff, 'simple');
+      return true;
+    }
+  );
+
+  assert.throws(
+    () => strictEqualFull({ a: 1 }, { a: 2 }),
+    (err) => {
+      assert.strictEqual(err.diff, 'simple');
+      return true;
+    }
+  );
+
+  assert.throws(
+    () => deepStrictEqualFull({ a: 1 }, { a: 2 }),
+    (err) => {
+      assert.strictEqual(err.diff, 'simple');
+      return true;
+    }
+  );
+
+  assert.throws(
+    () => equalFull({ a: 1 }, { a: 2 }),
+    (err) => {
+      assert.strictEqual(err.diff, 'simple');
+      return true;
+    }
+  );
+});
+
+test('Assert class destructuring behavior - strict option', () => {
+  const assertInstanceNonStrict = new Assert({ strict: false });
+  const assertInstanceStrict = new Assert({ strict: true });
+
+  assertInstanceNonStrict.equal(2, '2');
+
+  assert.throws(
+    () => assertInstanceStrict.equal(2, '2'),
+    assert.AssertionError
+  );
+
+  const { equal: equalNonStrict } = assertInstanceNonStrict;
+  const { equal: equalStrict } = assertInstanceStrict;
+
+  equalNonStrict(2, '2');
+  assert.throws(
+    () => equalStrict(2, '2'),
+    assert.AssertionError
+  );
+});
+
+test('Assert class destructuring behavior - comprehensive methods', () => {
+  const myAssert = new Assert({ diff: 'full', strict: false });
+
+  const {
+    fail,
+    equal,
+    strictEqual,
+    deepStrictEqual,
+    throws,
+    match,
+    doesNotMatch
+  } = myAssert;
+
+  assert.throws(() => fail('test message'), (err) => {
+    assert.strictEqual(err.diff, 'simple');
+    assert.strictEqual(err.message, 'test message');
+    return true;
+  });
+
+  assert.throws(() => equal({ a: 1 }, { a: 2 }), (err) => {
+    assert.strictEqual(err.diff, 'simple');
+    return true;
+  });
+
+  assert.throws(() => strictEqual({ a: 1 }, { a: 2 }), (err) => {
+    assert.strictEqual(err.diff, 'simple');
+    return true;
+  });
+
+  assert.throws(() => deepStrictEqual({ a: 1 }, { a: 2 }), (err) => {
+    assert.strictEqual(err.diff, 'simple');
+    return true;
+  });
+
+  throws(() => { throw new Error('test'); }, Error);
+
+  match('hello world', /world/);
+
+  doesNotMatch('hello world', /xyz/);
+});