🐛 Bug: Diff reporter fails on cyclic object with custom [Symbol.toStringTag]

[balagge]

Bug Report Checklist

• I have read and agree to Mocha's Code of Conduct and Contributing Guidelines
• I have searched for related issues and issues with the faq label, but none matched my issue.
• I have 'smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, my usage of Mocha, or Mocha itself.
• I want to provide a PR to resolve this

Expected

Reporting object diff successfully.

Actual

TypeError: Converting circular structure to JSON being printed

Minimal, Complete and Verifiable Example

'use strict';

const chai = require('chai');
const assert = chai.assert;

describe('Test circular', function() {

    it ('Reporting diff successfully on circular object with no custom [Symbol.toStringTag]', function() {

        const obj1 = {x:1};
        obj1.self = obj1;
        const obj2 = {x:2};
        obj2.self = obj2;
        assert.deepEqual(obj1, obj2);
    });

    it ('Report fail on circular object with custom [Symbol.toStringTag]', function() {

        const obj1 = {x:1, [Symbol.toStringTag]:"CustomTag"};
        obj1.self = obj1;
        const obj2 = {x:2, [Symbol.toStringTag]:"CustomTag"};
        obj2.self = obj2;
        assert.deepEqual(obj1, obj2);
    });

});

Output:

1) Test circular
       Reporting diff successfully on circular object with no custom [Symbol.toStringTag]:

      AssertionError: expected { x: 1, self: [Circular] } to deeply equal { x: 2, self: [Circular] }
      + expected - actual

       {
         "self": [Circular]
      -  "x": 1
      +  "x": 2
       }
      
      at Context.<anonymous> (test/unitTests/runtime/set/circular.js:14:16)
      at process.processImmediate (node:internal/timers:505:21)

  2) Test circular
       Report fail on circular object with custom [Symbol.toStringTag]:
     TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'CustomTag'
    --- property 'self' closes the circle
      at JSON.stringify (<anonymous>)
      at Runner.emit (node:events:520:35)
      at process.processImmediate (node:internal/timers:505:21)

Fun fact: V8 JSON.stringify also mistakes the custom tag for a constructor name in the TypeError text.

Versions

npx mocha --version
11.7.5

node_modules/.bin/mocha --version
11.7.5

node --version
v24.10.0

Additional Info

Did some testing and debugging. Seems to be caused by

• function canonicalType(value) in lib/utils treating custom [Symbol.toStringTag] as a type,
• which is not handled by function jsonStringify(object, spaces, depth) , so it calls JSON.stringify() directly on the object.

[balagge]

Ecma specs contain a warning against such use of Object.prototype.toString().

[balagge]

In addition to a custom [Symbol.toStringTag] directly attached to an object, the similar TypeError is thrown for recursive

• built-in objects that have predefined [Symbol.toStringTag] (e.g. Set, Map, etc. instances - a lot of such cases exist, although probably most of them are not usually recursive objects)
• objects with prototype if the prototype chain includes a [Symbol.toStringTag] definition - this may include user-defined and library-defined classes

Finally, the 'typechecking' by Object.prototype.toString can be unintentinally broken by attaching a [Symbol.toStringTag] that converts to one of the predefined 'types' in function _stringify(), even without being recursive!.

The last case can be considered an abuse of the string tag, although not entirely. You can easily imagine e.g. using 'DATE' as a string tag, not expecting to be converted to lowercase and being taken as an indicator of a Date object.

[JoshuaKGoldberg]

🙃 The whole area of stringification area is a gift that keeps on giving. A few other issues & PRs around it:

• 🐛 Bug: Calling done with circular reference object results in type error converting JSON instead of correct failure message #2598
• Mocha.utils.stringify() hangs on recursive data structures #2751
• fix circular objects in json reporter; closes #2433 #3318
• 🐛 Bug: infinite loop in parallel tests with uncaught error containing circular dependency #5209
• 🐛 Bug: Setting readOnly properties in breakCircularDeps breaks the reporter in parallel mode with allow-uncaught #5188
• fix: support errors with circular dependencies in object values with --parallel #5212
• 🐛 Bug: thrown error .expected with null prototype throws TypeError: value.toString is not a function #5505
• fix: handle empty null-prototyped objects #5506

@mark-wiemer - as much as I dislike doing things the ECMAScript spec recommends against, my hunch is we shouldn't significantly refactor this code. It's been around for a while. Maybe we can get away with a targeted fix for now? WDYT?

Btw, great investigation @balagge! 👏

[mark-wiemer]

I haven't dug in to the general stringification code, but I imagine it has a lot of stuff that "the ECMAScript spec recommends against" ? I'm fine with "yet another patch" here, as long as we have comprehensive tests for other scenarios so that our patch now doesn't break fixes from last time. One day we'll have capacity to refactor this area... one day :D