tinyspy

minimal fork of nanospy, with more features 🕵🏻‍♂️

A 10KB package for minimal and easy testing with no dependencies. This package was created for having a tiny spy library to use in vitest, but it can also be used in jest and other test environments.

In case you need more tiny libraries like tinypool or tinyspy, please consider submitting an RFC

Installing

1// with npm
2$ npm install -D tinyspy
3
4// with pnpm
5$ pnpm install -D tinyspy
6
7// with yarn
8$ yarn install -D tinyspy

Usage

spy

Simplest usage would be:

1const fn = (n) => n + '!'
2const spied = spy(fn)
3
4spied('a')
5
6console.log(spied.called) // true
7console.log(spied.callCount) // 1
8console.log(spied.calls) // [['a']]
9console.log(spied.results) // [['ok', 'a!']]
10console.log(spied.returns) // ['a!']

You can reset calls, returns, called and callCount with reset function:

1const spied = spy((n) => n + '!')
2
3spied('a')
4
5console.log(spied.called) // true
6console.log(spied.callCount) // 1
7console.log(spied.calls) // [['a']]
8console.log(spied.returns) // ['a!']
9
10spied.reset()
11
12console.log(spied.called) // false
13console.log(spied.callCount) // 0
14console.log(spied.calls) // []
15console.log(spied.returns) // []

Since 3.0, tinyspy doesn't unwrap the Promise in returns and results anymore, so you need to await it manually:

1const spied = spy(async (n) => n + '!')
2
3const promise = spied('a')
4
5console.log(spied.called) // true
6console.log(spied.results) // ['ok', Promise<'a!'>]
7
8await promise
9
10console.log(spied.results) // ['ok', Promise<'a!'>]
11
12console.log(await spied.returns[0]) // 'a!'

[!WARNING] This also means the function that returned a Promise will always have result type 'ok' even if the Promise rejected

Tinyspy 3.0 still exposes resolved values on resolves property:

1const spied = spy(async (n) => n + '!')
2
3const promise = spied('a')
4
5console.log(spied.called) // true
6console.log(spied.resolves) // [] <- not resolved yet
7
8await promise
9
10console.log(spied.resolves) // ['ok', 'a!']

spyOn

All spy methods are available on spyOn.

You can spy on an object's method or setter/getter with spyOn function.

1let apples = 0
2const obj = {
3  getApples: () => 13,
4}
5
6const spy = spyOn(obj, 'getApples', () => apples)
7apples = 1
8
9console.log(obj.getApples()) // prints 1
10
11console.log(spy.called) // true
12console.log(spy.returns) // [1]

1let apples = 0
2let fakedApples = 0
3const obj = {
4  get apples() {
5    return apples
6  },
7  set apples(count) {
8    apples = count
9  },
10}
11
12const spyGetter = spyOn(obj, { getter: 'apples' }, () => fakedApples)
13const spySetter = spyOn(obj, { setter: 'apples' }, (count) => {
14  fakedApples = count
15})
16
17obj.apples = 1
18
19console.log(spySetter.called) // true
20console.log(spySetter.calls) // [[1]]
21
22console.log(obj.apples) // 1
23console.log(fakedApples) // 1
24console.log(apples) // 0
25
26console.log(spyGetter.called) // true
27console.log(spyGetter.returns) // [1]

You can reassign mocked function and restore mock to its original implementation with restore method:

1const obj = {
2  fn: (n) => n + '!',
3}
4const spied = spyOn(obj, 'fn').willCall((n) => n + '.')
5
6obj.fn('a')
7
8console.log(spied.returns) // ['a.']
9
10spied.restore()
11
12obj.fn('a')
13
14console.log(spied.returns) // ['a!']

You can even make an attribute into a dynamic getter!

1let apples = 0
2const obj = {
3  apples: 13,
4}
5
6const spy = spyOn(obj, { getter: 'apples' }, () => apples)
7
8apples = 1
9
10console.log(obj.apples) // prints 1

You can restore spied function to its original value with restore method:

1let apples = 0
2const obj = {
3  getApples: () => 13,
4}
5
6const spy = spyOn(obj, 'getApples', () => apples)
7
8console.log(obj.getApples()) // 0
9
10obj.restore()
11
12console.log(obj.getApples()) // 13

Authors

Mohammad Bagher	Vladimir

Sponsors

Your sponsorship can make a huge difference in continuing our work in open source!

Vladimir sponsors

Mohammad sponsors