Support explicit resource management

[sukima]

Is your feature request related to a problem? Please describe.
I'm always frustrated when I have to remember to call sinon.restore() in test cleanup or risk memory leaks and test pollution. The current approach requires explicit cleanup in afterEach hooks or manual restoration, which is error-prone and leads to boilerplate code. With modern JavaScript's Explicit Resource Management (using/await using), we could leverage automatic cleanup at block scope end, making sandboxes potentially unnecessary for many use cases.

Describe the solution you'd like
I want all sinon primitives (spies, stubs, fakes, mocks, and sandboxes) to implement the Symbol.dispose method by default, enabling automatic cleanup when used with the using declaration. The disposal behavior should:

• Individual objects: Dispose only the specific spy/stub/fake/mock (equivalent to calling .restore() on that instance)
• Sandbox objects: Dispose all sinon objects within that sandbox (equivalent to calling sandbox.restore())
• Multiple disposal calls: Be no-ops after the first call (idempotent behavior)
• Backward compatibility: No breaking changes - existing code works unchanged, using keyword provides opt-in automatic cleanup

Example usage:

test('my test', function () {
  using myFake = sinon.replace(ob, 'method', sinon.fake());
  using mySpy = sinon.spy(obj, 'method');
  using sandbox = sinon.createSandbox();
  using stubFromSandbox = sandbox.stub(obj, 'otherMethod');
  
  doSomething();
  
  sinon.assert.called(myFake);
  // All objects automatically restored when leaving scope
  // sandbox disposal would also clean up stubFromSandbox
});

Describe alternatives you've considered

• Manual sinon.restore() calls in afterEach hooks (current approach - verbose and error-prone)
• Wrapper functions that return disposable objects (would require maintaining separate wrapper library)
• Using try/finally blocks with manual cleanup (adds nesting and complexity)
• Test framework-specific plugins (not portable across different test runners)
• Custom DisposableStack implementations (more verbose than native using syntax)

Additional context
This feature would leverage the TC39 Explicit Resource Management proposal (Stage 3) which is already supported in TypeScript 5.2+ and modern JavaScript engines. The implementation would require adding [Symbol.dispose]() { this.restore(); } to relevant prototypes, with idempotent behavior to handle multiple disposal calls gracefully.

This approach could make sandboxes less necessary for many use cases, as individual using declarations provide the same automatic cleanup benefits with more granular control. It would make sinon more ergonomic and significantly reduce the likelihood of test pollution due to forgotten cleanup.

[fatso83]

This is a great suggestion! I was unaware of that feature.

Mind you, we already do have a wrapper library that cleans up sandboxes: sinon-test. Nothing fancy, though, but less typing for the most common use case (auto-cleanup per test).

This approach could make sandboxes less necessary for many use cases

More of a technical note: you cannot avoid sandboxes, as the base Sinon object is a Sandbox.

PR's of course welcome :)

[sukima]

Here is a contrived idea on how this could work. Though, it is debatable if this is the best use case. However I can imagine some (like myself) enjoying the guarantees that Disposable resources provide without having to worry about sandboxes or post-test cleanup. This is especially true if you want to control the cleanup in for example testing multiple sinon.replace on the same subjectUnderTest.method.

test('something', function () {
  try {
    using fake = sinon.replace(sut, 'method', sinon.fake());
    doSomething();
    sinon.assert.calledOnce(fake);
    // calls sinon.restore()
  } catch (_ignored) { /* ignored */ }

  try {
    using fake = sinon.replace(sut, 'method', sinon.fake.returns('foo'));
    doSomething();
    sinon.assert.calledOnce(fake);
    // calls sinon.restore()
  } catch (_ignored) { /* ignored */ }
});

I thought about making a wrapper function that would facilitate this. However, since the resource in question is the fake/spy I’d either have to monkey-patch or proxy the fake. I’d rather this come into the core since then TypeScript would complain about monkey-patching. But till then here is the idea in JavaScript:

/**
 * @param {sinon.SinonSpy} fake
 * @returns {sinon.SinonSpy & Disposable}
 */
function patchedFake(fake) {
  fake[Symbol.dispose] = () => fake.restore();
  return fake;
}

But to be honest, I haven’t a clue where or how to implement this in the core source code. Do you have any advise?

[sukima]

I should add that is is also possible to do this inline without monkey-patching using DisposableStack if one wished to add an some extra lines of code:

using stack = new DisposableStack();
const fake = stack.adopt(
  sinon.replace(sut, ‘method’, sinon.fake()),
  (fake) => fake.restore(),
);

[fatso83]

But to be honest, I haven’t a clue where or how to implement this in the core source code. Do you have any advise?

See stuff in lib/sinon: proxy.js (used by spy.js) and fake.js

---

Did you see my note about sinon-test above? That gives you

it(
    "should do something",
    test(function () {
        var spy1 = this.spy(myFunc);
        var spy2 = this.spy(myOtherFunc);
        myFunc(1);
        myFunc(2);
        assert(spy1.calledWith(1));
        assert(spy1.calledWith(2));
    })
); 

It's already less typing than the alternatives proposed, but I think we could add something similar to the base Sinon object if we just exposes a using(testFn) and add Sandbox.prototype[Symbol.dispose].

Then you could probably get this:

test('something', using(() => {
    const fake = sinon.replace(sut, 'method', sinon.fake());
    doSomething();
    sinon.assert.calledOnce(fake);
}));

The using() function would probably look look something like:

function using(testFn) {
    using existingSinon = sinon
    testFn();
    // implicitly calls sinon.restore()
}

I don't mind adding support for this to all the different types of fakes, stubs, etc but not sure if that extra typing will be used by anyone.

[sukima]

I just like using the language itself to manage cleanup. It is why explicit resource management was added to the language. I mean why reinvent the wheel?

I think binding mocking by scope is a much better option then relaying on sandboxes, try/finally restoring, and test frameworks to support cleanup. Least that is when cleanup is not built into the language itself.

Least that is why I think it would be cool if sinon supported that out of the box. No longer having to worry about the test framework calling sinon.restore() on every afterTest hook or yet another wrapper function we have to import form a third party.

I think it would be cool if we could do this without having to rely on a test framework to accomplish. Perhaps using sinon outside of a test framework or in new frameworks that haven’t established any sinon integration.

using myResource = new Resource()

{
  using myFake = sinon.replace(myResource, ‘method’, sinon.fake.resolves(‘success’));
  const result = await myResource.method();
  console.assert(result === ‘success’, ‘resolves a string’);
}

{
  using myFake - sinon.replace(myResource, ‘method’, sinon.fake.rejects(‘failed’));
  try {
    await myResource.method();
  } catch (result) {
    console.assert(result === ‘failed’, ‘rejects a string’);
  }
}

For now there is this:

using stack = new DisposableStack();
const myFake = stack.adopt(
  sinon.replace(thing, ‘method’, sinon.fake()),
  (fake) => fake.restore(),
);