sinon.node.txt

                                  ┏━━━━━━━━━━━┓
                                  ┃   SINON   ┃
                                  ┗━━━━━━━━━━━┛

ALTERNATIVES ==>                  #  - sinon (prefer): lots of features
                                  #  - testdouble.js: a little fewer features
                                  #  - jest mocks: Jest-specific
                                  #  - tape mocks: Tape-specific
                                  #  - jasmine-spies: Jasmine-specific
                                  #  - chai-spies: Chai-specific, less features
                                  #  - CallTracker|MockTracker: Node.js core, fewer features
                                  #  - deno mock: Deno-specific
                                  #     - prefered with Deno, unless need more features

VERSION ==>                       #19.0.4
                                  #Node.js or browser
                                  #Provides spies, function stubs and related assertions.
                                  #Also links to @sinonjs/fake-timers and Nise for: mocks timers, mocks client-side responses (XHR)

                                  ┌───────────┐
                                  │   SPIES   │
                                  └───────────┘

SINON.spy([FUNC])->SPYFUNC        #Creates a SPYFUNC
                                  #FUNC is original function (def: empty).
                                  #FUNC can be a CLASS
SINON.spy(OBJ[, 'FUNC'][,STR_ARR])#Same but with OBJ.FUNC (def: all methods), and SPYFUNC is assigned to OBJ.FUNC
                                  #STR_ARR can be 'get|set', which will set SPYFUNC.get|set SPYFUNC2

SPYFUNC.resetHistory()            #Erase previous calls. Does not transform back.
SINON.restoreObject(SPYFUNC)      #Removes spying

SPYFUNC.withArgs(SVAL...)->SPYFUNC#Only for calls made with arguments SVAL...

SPYFUNC.callCount                 #Number of times it has been fired
SPYFUNC.[not]called               #callCount !== 0
SPYFUNC.calledOnce|Twice|Thrice   #callCount === 1|2|3

SPYFUNC.calledWith(SVAL...)->BOOL #Fired with at least those arguments.
SPYFUNC.called[Once]WithMatch
 (VAL...)->BOOL                   #Fired with at least those arguments, automatically wrapped as SINON.match(VAL)
SPYFUNC.calledWithExactly(SVAL...)
 ->BOOL                           #Fired with exactly those arguments
SPYFUNC.returned(SVAL)->BOOL      #Returned VAL (deep comparison).
SPYFUNC.calledOn(OBJ|SVAL)->BOOL  #Fired with OBJ as `this`
SPYFUNC.calledWithNew()->BOOL     #Fired as new SPYFUNC
SPYFUNC.threw([VAL|STR])->BOOL    #Threw error. STR is ERROR.type.
SPYFUNC.
 called[Immediately]Before|After  #First call of SPYFUNC before|after SPYFUNC2
 (SPYFUNC2)->BOOL                 #If "Immediately", no other SPYFUNC3 in-between.

AT LEAST ONCE ==>                 #All the above are "at least once"
SPYFUNC.alwaysCalledWith*|
 Returned|CalledOn|CalledWithNew|
 Threw(...)                       #Same but "always"
SPYFUNC.neverCalledWith*(...)     #Same but "never"
SPYFUNC.calledOnceWith*(...)      #Same but "exactly once"

SPYFUNC.getCalls()->SPYCALL_ARR   #
SPYFUNC.getCall(NUM|-NUM)->SPYCALL#
SPYFNC.first|second|third|lastCall#Same as SPYFUNC.getCall(1|2|3|-1)
SPYCALL.*called|returned|threw*   #Same as SPYFUNC.*(...)
 (...)                            #Cannot use always|never|Once

SPYCALL.args                      #VAL_ARR
SPYCALL.firstArg|lastArg          #VAL
SPYCALL.callback                  #lastArg if FUNC, undefined otherwise
SPYCALL.returnValue               #Return VAL
SPYCALL.thisValue                 #this OBJ
SPYCALL.exception                 #Exception thrown VAL (or undefined)
SPYFUNC.thisValues|args|
exceptions|returnValues           #Same but as ARR

SPYFUNC.printf(STR[, VAL...])     #Printf using formatting STR with:
                                  #  - "%n": 'FUNC'
                                  #  - "%c": SPYFUNC.callCount in word
                                  #  - "%C": 'FUNC(ARGS) at FILE:LINE'
                                  #  - "%D": 'ARGS'
                                  #  - "%t": `this`
                                  #  - "%NUM": VAL
                                  #  - "%*": all VAL...

                                  ┌───────────┐
                                  │   STUBS   │
                                  └───────────┘

STUB                              #SPYFUNC (inherit all its members) which behavior can be manipulated.

SINON.stub([FUNC2])->STUB
SINON.stub(OBJ[, 'FUNC'][, FUNC2])
 ->STUB                           #Like SINON.spy() except function is replaced by FUNC2 (if present)
SINON.stub(OBJ[, 'FUNC'])
 .get|set([FUNC2])->STUB          #Same for get|set access descriptors
SINON.stub(OBJ[, 'PROP'])
 .value(VAL)->STUB                #Same for a non-function
SINON.createStubInstance          #Same for a function TYPE
 (TYPE[, OBJ])->STUB              #OBJ are merged in. Properties values can be:
                                  #  - STUB2
                                  #  - VAL: shortcut for SINON.stub().returns(VAL)

STUB.restore()                    #Transform OBJ.PROP back to original property
STUB.resetBehavior()              #Removes mocks. Does not transform back.
STUB.resetHistory()               #Erase previous calls. Does not transform back.
STUB.reset()                      #Both

STUB.onCall(NUM)...               #Only for call number NUM
STUB.onFirst|Second|ThirdCall()...#

STUB.*()->STUB                    #Everything below modifies STUB then returns it

STUB.returns(VAL)                 #Mocks: return VAL
STUB.returnsThis()                #Mocks: return `this`
STUB.returnsArg(NUM)              #Mocks: return arguments[NUM]
STUB.resolves(VAL)                #Mocks: return Promise.resolve(VAL)
STUB.resolvesArg(NUM)             #Mocks: return Promise.resolve(arguments[NUM])
STUB.throws([ERROR[()]|STR])      #Mocks: throw (STR is ERROR.type)
STUB.rejects([ERROR|STR])         #Mocks: returns Promise.reject(ERROR)

STUB.callThrough()                #Mocks: fire original function
STUB.callThroughWithNew()         #Mocks: fire original function with new ...
STUB.callsFake(FUNC)              #Mocks: fire FUNC(...)

STUB.callsArg(NUM)                #Mocks: fire arguments[NUM]()
STUB.callsArgWith(NUM, ...)       #Mocks: fire arguments[NUM](...)
STUB.yields(...)                  #Mocks: fire arguments[0](...)
STUB.yieldsRight(...)             #Mocks: fire arguments[last](...)
STUB.yieldsTo('FUNC', ...)        #Mocks: fire arguments[0].FUNC(...)
STUB.yieldsToRight('FUNC', ...)   #Mocks: fire arguments[last].FUNC(...)
STUB.callsArgOn(NUM, OBJ, ...)
STUB.yields*On(OBJ, ...)          #Same but with OBJ as `this`
STUB.callsArg|yields*Async(...)   #Same but uses process.nextTick() (in Node) or setTimeout() (in browsers)
STUB|SPYFUNC|SPYCALL.             #Same as .calls|yields*(...) except:
 callArg|yield*(...)->VAL         #  - performed on previous calls (not future calls), in order
                                  #  - return value of first one

SINON.addBehavior
 ('FUNC', FUNC(STUB, ...))        #Adds custom mock STUB.FUNC(...)

STUB.usingPromise(Promise)        #Mock Promise, as used in STUB.resolves|rejects*()

                                  ┌──────────┐
                                  │   FAKE   │
                                  └──────────┘

FAKE                              #Same as SPY but:
                                  #  - no withArgs()
                                  #  - shortcut firstArg|lastArg|callback -> lastCall.firstArg|lastArg|callback
SINON.fake([FUNC])                #Same as SINON.spy([FUNC]) but with FAKE
SINON.fake.returns|resolves|throws
 |rejects|yields[Async](...)      #Same as SINON.stub().*(...) but with FAKE

                                  ┌─────────────┐
                                  │   REPLACE   │
                                  └─────────────┘

SINON.replace[.usingAccessor]     #Does OBJ.PROP = VAL
 (OBJ, 'PROP', VAL)               #I.e. like stubs but without spying
                                  #As opposed to directly doing OBJ.PROP = VAL, can use SANDBOX to restore later
                                  #Unless `usingAccessor`, bypasses any setter FUNC
SINON.replaceGetter|Setter(...)   #Same but for getter|setter accessors

                                  ┌─────────────┐
                                  │   MATCHER   │
                                  └─────────────┘

SVAL                              #VAL|SINONMATCH
SINONMATCH                        #Everything below
SINONMATCH.test(VAL)->BOOL        #

SINON.match
 (FUNC(VAL)->BOOL[, 'ERROR'])     #
SINONMATCH.and|or(SINONMATCH2)    #

SINON.match.any                   #Always true
SINON.match.same(VAL)             #=== VAL
SINON.match.defined               #!== null|undefined

SINON.match.typeOf(STR)           #'undefined|null|boolean|number|string|object|function|array|regexp|date|synbol'
SINON.match.instanceOf(TYPE)      #instanceof TYPE
SINON.match.bool|number|string|
 object|func|array|regexp|date|
 map|set|symbol                   #Checks type

SINON.match.truthy|falsy          #!= true|false

SINON.match(STR|REGEXP)           #typeof "string" and partially matches STR|REGEXP

SINON.match(NUM)                  #== NUM

SINON.match(ARR)                  #ARR.includes()

SINON.match(OBJ)                  #Contains OBJ
                                  #Can contain nested SINONMATCH
SINON.match.has[Own]('VAR'[, VAL])#Same for one specific property
                                  #Can only check own members (non-inherited)
                                  #VAL is deeply compared.
SINON.match.hasNested
 ('VARR'[, VAL])                  #Same with VARR

SINON.match.array.
 deepEquals(ARR|MAP|SET)          #
SINON.match.array.
 contains(ARR|MAP|SET)            #
SINON.match.array.
 startsWith|endsWith(ARR)         #
SINON.match.every|some(SINONMTCH2)#

                                  ┌────────────────┐
                                  │   ASSERTIONS   │
                                  └────────────────┘

SINON.assert.*(SPY[CALL]|STUB,...)#If SPY[CALL]|STUB.*(...) === true, throw error
                                  #SPY[CALL]|STUB.returned() is not available
                                  #SPY[CALL]|STUB.calledBefore|After is SINON.assert.callOrder(SPY[FUNC]|STUB...)
SINON.assert.match(SVAL, SVAL2)   #Asserts using SINON.match()

SINON.assert.fail('ERROR')        #Throw an ERROR. Can be customized
SINON.assert.failException        #AssertError. Can be customized
SINON.assert.pass('NAME')         #When assertion succeeds. Noop. Can be customized
SINON.assert.expose(OBJ[, OPTS])  #Copies SINON.assert.* to OBJ
                                  #OPTS:
                                  #  - prefix STR: prefixed to each 'FUNC' name
                                  #  - includeFail BOOL (def: true): also copies fail[Exception]

SHOULD.[always|never.]have.been.*##Same but with Chai
 (...)                           ##Does not have same limitations as SINON.assert.*() for returned|calledBefore|After()
                                 ##threw() -> thrown()
                                 ##Module sinon-chai (4.0.0)

JASMINE-SINON ==>                ##Similar for Jasmine, but not maintained

                                  ┌───────────┐
                                  │   MOCKS   │
                                  └───────────┘

SINON.mock(['FUNC'])->EXPECTATION
SINON.expectation.create(['FUNC'])
 ->EXPECTATION
SINN.mock(OBJ)->MOCK
MOCK.expects('FUNC')->EXPECTATION #Like SINON.stub()
                                  #Provides way to define assertions before verying them
MOCK|EXPECTATION.verify()         #Check assertions
MOCK.restore()                    #

EXPECTATION.*                     #Same as STUB
EXPECTATION.*()->EXPECTATION      #For all of the above

EXPECTATION.
 never|once|twice|thrice()
EXPECTATION.exactly|atLeast|atMost
 (NUM)                            #Checks calledCount
EXPECTATION.with[Exact]Args(...)  #Checks arguments
EXPECTATION.on(OBJ)               #Checks `this`

                                  ┌─────────────┐
                                  │   PROMISE   │
                                  └─────────────┘

SINON.promise
 ([FUNC(RESOLVE, REJECT)])
 ->FAKE_PROMISE                   #FAKE_PROMISE is like PROMISE but with additional methods
FAKE_PROMISE.status               #'pending|resolved|rejected'
FAKE_PROMISE.resolve|reject(VAL)  #
FAKE_PROMISE.
 resolvedValue|rejectedValue      #VAL

                                  ┌─────────────┐
                                  │   SANDBOX   │
                                  └─────────────┘

SINON.restore()                   #Fire all *.restore|uninstall() (removing all mocks, stubs, spies, etc.)
                                  #Also removes stubbing from *.replace[Getter|Setter]()
SINON.reset[Behavior|History]()   #Fire all SPYFUNC.reset[Behavior|History]()
SINON.verify[AndRestore]()        #Fire all MOCK.verify() and *.restore()

SANDBOX.*                         #Like SINON.* but restore|reset*|verify*() are scoped to that instance (instead of being global)
SINON.createSandbox([OPTS])       #OPTS:
 ->SANDBOX                        #  - injectInto (def: returned SANDBOX)
                                  #  - properties 'FUNC'_ARR (def: all)
                                  #  - useFakeTimers BOOL (def: false) or @sinonjs/fake-timers OPTS
                                  #  - useFakeServer BOOL (def: true) or NISE.fakeServer[WithClock]
SANDBOX.inject(OBJ)->OBJ          #
SANDBOX.leakThreshold             #NUM (def: 1e4). When doing >NUM mocks|stubs|etc. without restore(), print a warning

SANDBOX.define                    #Set OBJ.PROP = VAL. Undone when SANDBOX restored
 (OBJ, 'PROP', FUNC()->VAL)       #VAL cannot be undefined, but can be SPY|STUB|FAKE

SINON-TEST ==>                   ##Module wrapping a FUNC with SINON.createSandbox() and SANDBOX.verifyAndRestore()
                                 ##Prefer using before|after[Each]()

                                  ┌────────────┐
                                  │   OTHERS   │
                                  └────────────┘

SINON.useFakeTimers(...)->CLOCK
SINON.clock.create(...)->CLOCK    #References to @sinonjs/fake-timers install|createClock(...) (see its doc)

SINON.*                           #Reference to NISE.fakeXhr.* and NISE.* (see its doc)