test-quadruple

Simple and declarative mocks, spies, and replacements.

Combine with your unit test framework of choice.

Install

1npm install --save-dev test-quadruple

1yarn add --dev test-quadruple

1pnpm add --save-dev test-quadruple

Usage

1import test from "ava";
2import * as tq from "test-quadruple";
3
4test("test-quadrule", async t => {
5  const logger = tq.spy();
6
7  const { bar, baz } = await tq.replace<typeof import("./foo.js")>({
8    modulePath: new URL("path/to/foo.js", import.meta.url),
9    importMeta: import.meta,
10    localMocks: {
11      "./bar.js": {
12        bar: tq.spy([
13          tq.returns("Hello, world!"),
14          tq.returns("lorem ipsum"),
15        ]),
16        baz: tq.mock<Baz>({
17          bizz: "buzz",
18        }),
19      },
20    },
21    globalMocks: {
22      console: {
23        log: logger,
24      },
25    },
26  });
27
28  bar();
29  bar();
30  baz();
31
32  t.like(tq.explain(logger), {
33    callCount: 3,
34    called: true,
35    calls: [
36      { arguments: ["Hello, world!"] },
37      { arguments: ["lorem ipsum"] },
38      { arguments: ["buzz"] },
39    ],
40    flatCalls: [
41      "Hello, world!",
42      "lorem ipsum",
43      "buzz",
44    ],
45  });
46});

Definitions

Mocks

A mock is a partial object that behaves as a full object on the type level.

mock(object?)

Partially mocks an object.

1import * as tq from "test-quadruple";
2
3type Person = {
4  name: string;
5  getAge: () => number;
6  parents?: {
7    mother?: Person;
8    father?: Person;
9  };
10};
11
12declare const storePerson: (person: Person) => void;
13
14storePerson(tq.mock({
15  name: "John Doe",
16  parents: {
17    mother: {
18      name: "Jane Doe",
19      getAge: () => 42,
20    },
21  },
22}));

object

Type: object
Default: {}

The partially-mocked object.

Spies

A spy is a wrapped function or set of fake functions that tracks its calls.

spy(fn)

Wraps a function and tracks its calls.

1import * as tq from "test-quadruple";
2
3const add = (a: number, b: number) => a + b;
4const spy = tq.spy(add);
5//    ^? const spy: (a: number, b: number) => number
6
7spy(1, 2);
8//=> 3
9
10spy(3, 4);
11//=> 7
12
13console.log(tq.explain(spy));
14//=> { callCount: 2, called: true, calls: [{ arguments: [1, 2] }, { arguments: [3, 4] }] }

fn

Type: function

The function to spy on.

spy(fakes?)

spy(...fakes)

Creates a spy that uses the provided fakes, in order. Subsequent calls will use the last provided fake.

1import * as tq from "test-quadruple";
2
3const fn = tq.spy([tq.returns(1), tq.returns(2)]);
4// OR: tq.spy(tq.returns(1), tq.returns(2));
5
6fn();
7//=> 1
8
9fn();
10//=> 2
11
12fn();
13//=> 2

fakes

Type: function[]

An optional array of fakes to use, in order.

explain(spy): Explanation

List the tracked calls of a spy. Throws if the given function is not a spy.

1import test from "ava";
2import * as tq from "test-quadruple";
3
4test("tracks calls of a spy", async t => {
5  const fn = tq.spy(tq.resolves(1));
6
7  t.is(await fn(), 1);
8
9  t.like(tq.explain(fn), {
10    callCount: 1,
11    called: true,
12    calls: [{ arguments: [1, 2] }],
13    flatCalls: [1, 2],
14  });
15});

spy

Type: function

The spy to explain.

Explanation

Type: object

An object with information about the spy.

callCount

Type: number

The number of times the given spy was called.

called

Type: boolean

Whether or not the given spy was called.

calls

Type: Array<{ arguments: unknown[] }>

An array of calls to the given spy.

flatCalls

Type: unknown[]

A flattened array of calls to the given spy.

Fakes

A fake is a function that behaves in a specific manner, used in place of another function. test-quadruple provides a few utils to assist in faking behaviors.

1import * as tq from "test-quadruple";
2
3const fn = tq.spy([
4  tq.returns(1),
5  tq.returns(2),
6  tq.throws(new Error("Oops! All errors!")),
7  tq.resolves(3),
8  tq.rejects("Oops! Not an error!"),
9  tq.noop(),
10]);
11
12fn();
13//=> 1
14
15fn();
16//=> 2
17
18fn();
19//=> Error: "Oops! All errors!"
20
21await fn();
22//=> 3
23
24await fn();
25//=> "Oops! Not an error!"
26
27fn();
28//=> void

returns(value)

Creates a function that returns the given value.

throws(error)

Creates a function that throws the given error.

resolves(value)

Creates an async function that resolves to the given value.

rejects(error)

Creates an async function that rejects with the given error.

noop()

Creates a function that does nothing.

Replacements

A replacement is a (partially) mocked, spied, or faked module. Replacements are done asynchronously via esmock.

replace<ModuleType>(options)

Partially replaces local or global imports of a module.

1import { execa } from "execa";
2import { match, P } from "ts-pattern";
3import * as tq from "test-quadruple";
4
5const { program } = await tq.replace<typeof import('./program.js')>({
6  modulePath: new URL("program.js", import.meta.url),
7  importMeta: import.meta, // Required
8  localMocks: {
9    execa: {
10      execa: tq.spy(args => match(args)
11        .with("foo", tq.resolves("bar"))
12        .with([42, true], tq.resolves("The Ultimate Answer to Life, The Universe and Everything"))
13        .otherwise(execa)
14      ),
15    },
16  },
17});
18
19await program("foo");
20//=> "bar"
21
22await program(42, true);
23//=> "The Ultimate Answer to Life, The Universe and Everything"
24
25await program("echo hi");
26//=> "hi"

options

Type: object

modulePath

Type: string | URL

The path to the module to replace.

importMeta

Type: object

Pass in import.meta.

localMocks?

Type: object

Mock modules directly imported by the source module.

globalMocks?

Type: object

Mock modules or globals imported anywhere in the source tree.

Related

• testtriple - A handy little mocking library.
• testdouble.js - A minimal test double library for TDD with JavaScript.
• tinyspy - A minimal fork of nanospy, with more features. Also tracks spy returns.
• @fluffy-spoon/substitute - A TypeScript port of NSubstitute.
• Sinon - Standalone and test framework agnostic JavaScript test spies, stubs and mocks.
• esmock - ESM import and globals mocking for unit tests.