sinon

name	sinon
description	Use when the user asks about Sinon stubbing, spying, mocking, or test double APIs for unit tests. Triggers on questions like "how do I stub this", "Sinon fake timers", "spy vs stub", "sandbox usage", "assert.calledWith", "stub.resolves", "sinon.match", or test double patterns.
allowed-tools	["Read","Bash","WebFetch","WebSearch"]

Sinon.JS Documentation Lookup

This skill helps look up Sinon.JS APIs, patterns, and best practices for creating test doubles in unit tests.

Sources

Sinon.JS Documentation (v18)

The official docs organized by feature at https://sinonjs.org/releases/v18/:

Section	URL	Use For
Overview	https://sinonjs.org/releases/v18/	General concepts, what's new
Spies	https://sinonjs.org/releases/v18/spies/	Observing function calls without changing them
Stubs	https://sinonjs.org/releases/v18/stubs/	Replacing functions with controlled behavior
Mocks	https://sinonjs.org/releases/v18/mocks/	Pre-programmed expectations (use sparingly)
Fakes	https://sinonjs.org/releases/v18/fakes/	Immutable spies with optional behavior
Sandbox	https://sinonjs.org/releases/v18/sandbox/	Automatic cleanup of stubs/spies/mocks
Fake Timers	https://sinonjs.org/releases/v18/fake-timers/	Controlling setTimeout, setInterval, Date
Fake XHR	https://sinonjs.org/releases/v18/fake-xhr-and-server/	Faking HTTP requests
Assertions	https://sinonjs.org/releases/v18/assertions/	Sinon-specific assertion helpers
Matchers	https://sinonjs.org/releases/v18/matchers/	Argument matching for assertions

Process

1. Understand the Question Context

Determine whether the user needs:

• API reference: Exact method signatures, options, return values
• Pattern guidance: How to set up stubs, organize sandboxes, verify calls
• Troubleshooting: Why a stub isn't working, common pitfalls
• Best practices: Project-specific conventions for test doubles

2. Check Project Conventions First

Before fetching external docs, review the project's stubbing conventions from CLAUDE.md:

• Always use a sandbox: create via sinon.createSandbox(), restore in afterEach. The project uses sandboxes in virtually all test files — never use bare sinon.stub() or sinon.spy()
• Design for stubbing: avoid calling same-module functions you need to stub — Sinon can only stub module exports, not internal calls within the same file
• Extract dependencies to separate modules or pass them as parameters
• Common stubs go in the top-level describe block's beforeEach
• The project uses Node.js assert (not Chai) alongside Sinon

3. Fetch Documentation

Sinon docs are organized by feature — fetch the specific section page:

WebFetch: https://sinonjs.org/releases/v18/stubs/
Prompt: "Find the API documentation for [specific method like stub.resolves, stub.callsFake, etc.]"

For general best practices or newer features, supplement with web search:

WebSearch: "sinon.js stub resolves rejects async example"
WebSearch: "sinon sandbox restore best practices"

4. Look at Existing Test Examples

When the user needs pattern guidance, look at how the project uses Sinon:

# Find test files using stubs
grep -r "sinon.stub" --include="*.test.ts" -l src/ | head -5

# Find sandbox usage
grep -r "createSandbox\|sinon.sandbox" --include="*.test.ts" -l src/ | head -5

# Find specific patterns
grep -r "stub\.resolves\|stub\.returns\|stub\.callsFake" --include="*.test.ts" -l src/ | head -5

Read 1-2 relevant test files to show project-specific patterns alongside official docs.

5. Search for Specific APIs

When the user asks about a specific API (e.g., stub.resolves(), sandbox.create()):

1. Fetch the relevant Sinon section page (stubs, sandbox, etc.)
2. Search for the specific method or property
3. Extract the API signature with description and examples
4. Cross-reference with project usage if applicable

Output Format

API Reference

## Sinon: [method/feature]

### API

[Method signature and description from docs]

### Example

[Code example from docs or adapted to project patterns]

### Project Usage

[How this is typically used in the project, with file references if found]

Pattern Guidance

## Pattern: [description]

### From the Docs

[Official recommended approach]

### In This Project

[How the project implements this pattern, with examples from existing tests]

### Key Points

- [Important considerations]
- [Common pitfalls to avoid]

Common Lookup Patterns

Sandbox (project default)

Always create stubs and spies through a sandbox for automatic cleanup:

• Create: const sandbox = sinon.createSandbox()
• Stubs: sandbox.stub(obj, 'method'), sandbox.stub() (anonymous)
• Spies: sandbox.spy(obj, 'method'), sandbox.spy() (anonymous)
• Cleanup: sandbox.restore() in afterEach (restores all fakes created through the sandbox)

Stubs

• Behavior: stub.returns(val), stub.resolves(val), stub.rejects(err), stub.callsFake(fn), stub.throws(err)
• Conditional: stub.withArgs(arg).returns(val), stub.onFirstCall().returns(val)
• Reset: stub.reset(), stub.resetBehavior(), stub.resetHistory()

Spies

• Inspect: spy.calledOnce, spy.calledWith(arg), spy.returnValues, spy.args
• Count: spy.callCount, spy.firstCall, spy.secondCall, spy.lastCall

Assertions

• sinon.assert.calledOnce(spy)
• sinon.assert.calledWith(spy, arg1, arg2)
• sinon.assert.calledOnceWithExactly(spy, arg1)
• sinon.assert.notCalled(spy)
• sinon.assert.callOrder(spy1, spy2)

Fake Timers

• Create: sandbox.useFakeTimers(), sandbox.useFakeTimers({ now: timestamp })
• Control: clock.tick(ms), clock.tickAsync(ms), clock.next(), clock.runAll()
• Cleanup: handled by sandbox.restore()

Matchers

• Type: sinon.match.string, sinon.match.number, sinon.match.func, sinon.match.object
• Partial: sinon.match({ key: value }), sinon.match.has('key', value)
• Custom: sinon.match(predicate), sinon.match.any

Tips

• Always use sandbox — the project convention is sinon.createSandbox() with sandbox.restore() in afterEach. Never suggest bare sinon.stub() or sinon.spy() — always use sandbox.stub() and sandbox.spy() instead
• Sinon docs are organized by feature — fetch the specific section page rather than the overview for API details
• When the user asks "how do I stub X", first check whether the function is an export from another module (stubbable) vs. an internal call within the same file (needs restructuring) — this is a key project convention
• The project uses Node.js assert (not Chai) — adapt any Chai-based examples from docs to use assert.strictEqual, assert.deepStrictEqual, assert.ok, etc.
• stub.resolves() / stub.rejects() are the async-friendly counterparts to stub.returns() / stub.throws() — use these for Promise-based code
• When stubbing VS Code APIs (like vscode.window.showErrorMessage), the stub target must be the vscode module's export, not a local reference